Начало работы с 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 Экстерна для работы с черновиками и конструктором черновиков (draftsbuilder).
API Экстерна для работы с документооборотами и лентой событий.
Трейсинг запросов в 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.