Начало работы с API

Для начала работы с API

  • Получите api-key.
  • Пройдите аутентификацию и получите Access Token.
  • Для криптографических операций необходимо иметь электронную подпись.

Если вы еще не заключали договор с Контуром и хотите познакомиться с методами API, напишите нам. Мы вышлем вам тестовый api-key, сертификат и тестовую учетную запись.

Когда вы примете решение об интеграции и заключите договор с Контуром, вам будут высланы данные вашей персональной учетной записи для боевой и тестовой площадки.

Так как в API много разделов и методов, это может запутать вас при первом погружении в тему электронного документооборота. Ниже описаны главные особенности API, которые нужно учитывать при работе с методами. Чтобы помочь вам постепенно погрузиться в API и использовать только нужные методы, мы описали наиболее частые сценарии по работе с API и составили алгоритм действий для каждого из них.

Что нужно знать об API

  • Возвращаемые значения — json, кроме сервиса контентов. Даже если в методе возвращаются байты, то они вернутся в виде Json-строки. Внутри строки контент возвращается в формате base64. Напротив, принимаемые значения контентов ожидаются как application/octet-stream.
  • Работа с методами. Все доступные методы можно смотреть через swagger. Это упрощает создание http клиентов для вашего языка программирования. Если хотите отправлять запросы через Postman, то вы можете скачать JSON файл swagger’a и импортировать его в Postman.
  • Для Java есть официальный SDK.
  • Аутентификация реализована на базе протокола OpenId Connect. Для получения токена нужен api-key и client_id.
  • Для генерации тестовых данных мы разработали сервис Extern Test Tools, который позволяет сгенерировать данные пользователя, а также примеры отчетов в ФНС.

Трейсинг запросов в API Контур.Экстерна

В ответе каждого запроса к API Контур.Экстерна возвращается будет лежать заголовок X-Kontur-Trace-Id — уникальный идентификатор запроса. Рекомендуем сохранять или логировать на вашей стороне данный идентификатор для диагностики работы вашего приложения

Тестовая площадка

Сервис: https://extern-api.testkontur.ru/

В swagger документации все запросы по умолчанию отправляются на тестовую площадку.

Сервис генерации тестовых данных Extern Test Tools.

Для ФНС на тестовой площадке есть свой набор инспекций (роботов), которые нужно указывать в тестовых файлах отчетов и параметре ifns-code. Они отличаются стратегией обработки документооборотов. При работе с отчетностью в ФНС используйте следующие коды инспекций:

  • 0087 — Принимает все документы.
  • 0088 — Что бы вы ему не прислали — не примет.
  • 0085 — Присылает уведомления об уточнении.

Сертификаты и подписи

  • Для криптографических операций необходимо иметь сертификат электронной подписи. См. также статью Криптография.
  • Виды поддерживаемой подписи: открепленная, встроенная, множественная.
  • Поддерживаемые форматы подписи: CMS/PKCS #7, XMLDsig.

Сценарии работы с API

Порядок работы с методами зависит от цели и задач, которые вы решаете. Выделим основные три направления в работе с API Контур.Экстерна:

Все перечисленные сценарии описаны в виде алгоритма действий с примерами вызова методов.