Рекомендации по работе c API

Советы по технической реализации интеграции

Параллельное выполнение запросов к API

Для обеспечения надежной работы API в Контур.Экстерне настроены ограничения для каждого клиента – 20 одновременных HTTP запросов. Все, что превышает данный уровень, отправляется в очередь и может быть отброшено с кодом ответа HTTP 429 Throttling.

Запросы к API можно выполнять параллельно. Рекомендуем выставлять уровень параллелизма с возможностью динамически изменять его.

Массовая отправка отчетности

Для отправки большого количества документооборотов рекомендуем реализовать очередь отправок с настройкой количества параллельных запросов.

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

Новые типы и параметры

API Контур Экстерна развивается, и постепенно появляется новая функциональность. Поэтому при проектировании интеграции обязательно учитывайте возможность расширения моделей, использующихся в API: список документооборотов, документов, статусов ленты событий и т.д.

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

Плохо делать так:

if (docType == "docType1") {
    ...
    return DocType1Description();
}
else if (docType == "docType2") {
    ...
    return DocType2Descriotion();
}
else throw Exception();

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

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

Тайм-ауты

Запросы к API можно выполнять с заданным тайм-аутом. Для этого при запросе укажите в параметре Request-Timeout количество секунд в формате double.

Особенности работы с методами

Получение ресурса по идентификатору

Не рекомендуем хранить идентификаторы на вашей стороне, чтобы защититься от ошибок вследствие их возможной смены. Например, возможно изменение:

accountId — идентификатора учетной записи,

orgId — идентификатора организации.

Мониторинг документооборотов

Для мониторинга документооборотов рекомендуем запрашивать список документооборотов (ДО) с помошью метода GET Docflows. При этом есть ограничения:

Для получения списка ДО для конкретного типа при запросе метода укажите фильтр type.
При получении общего списка ДО без фильтра type метод вернет все документооборы, кроме:
- проактивных выплат;
- регистрации бизнеса;
- рассылки от ФНС;
- рассылки от Росстат.
Для получения документооборота Ответ на требование (urn:docflow:fns534-inventory) нужно использовать метод GET GetAllInventoryDocflows из раздела Документооборот описи.

Детальную информацию о документообороте можно получить по его идентфикатору docflowId с помощью метода GET Docflow. В ответ метод вернет также подробную информацию о документах в нем.

Сервис контентов

Для загрузки и скачивания документов рекомендуем всегда использовать Сервис контентов. Такой способ надежно будет работать для контентов любого объема.

Время хранения контентов

Примечание

Контенты документов в документооборотах хранятся без ограничений по времени.

Для остальных видов контентов определено время хранения. Например:

Документы, загруженные через сервис контентов, хранятся 90 дней.

Печатные формы документов черновиков хранятся 1 год.

Печатные формы документов документооборотов хранятся 5 дней.

Время хранения контентов может измениться.

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

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

проверки, подготовки, отправки черновика;
печати документа в черновике;
печати документа в документообороте;
сборки DraftsBuilder в черновик.

Запросы по данным методам могут выполняться дольше других методов в API, иногда более 10 минут. Длительность зависит от размера и количества контентов документов, которые нужно обработать. Поэтому в таких методах реализован флаг асинхронного вызова методов deferred. Когда приходит запрос с deferred = true, создается задача на выполнение операции в фоновом режиме. Метод возвращает идентификатор задачи taskId, по которому можно запросить статус выполнения и получить результат.

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

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

Примечание

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

Запросы по данным методам могут выполняться дольше других методов в API, иногда более 10 минут. Длительность зависит от размера и количества контентов документов, которые нужно обработать.