Начало работы с 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, который позволяет сгенерировать данные пользователя, а также примеры отчетов в ФНС.

Разделы методов Swagger

Трейсинг запросов в 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 Контур.Экстерна:

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

Отложенное выполнение задач

В API применяется отложенное выполнение задач в методах, где это предусмотрено. Например, в методах:

Некоторые операции из этого списка потенциально выполняются дольше других методов в API, возможно даже более 10-15 минут. Данные методы обрабатывают контенты документов, поэтому длительность работы также зависит от их размера.

В таких методах реализован флаг асинхронного вызова методов deferred. Когда приходит запрос с deferred = true, создается задача на выполнение операции в фоновом режиме. Метод возвращает идентификатор задачи, чтобы можно было отследить прогресс ее выполнения и получить результат.

Отложенное выполнение задач более надежно, т.к. все HTTP запросы на постановку задачи и получение ее результатов будут короткие. Это минимизирует риск получить ошибку из-за обрыва соединения.

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

Предупреждение

С мая 2022 значение флага false устарело и больше не используется в методах API. При таком значении вернется ошибка 400 BadRequest.