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

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

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

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

Запросы к API можно выполнять параллельно, но нужно осторожно выставлять уровень параллелизма и выносить его в настройки.

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

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

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

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

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

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 для диагностики работы вашего приложения.

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

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

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

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

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

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

Для мониторинга документооборотов есть два варианта работы с API:

использование ленты событий,

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

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

Список документооборотов удобно использовать, когда в интеграции одна учетная запись. В таком сценарии достаточно будет вычитывать список документооборотов.

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

Работа со списком документооборотов

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

Примечание

получать список ДО только по одному типу документооборота с использованием фильтра type и сортировкой по дате создания или изменения.

При получении общего списка ДО без фильтра type метод GET Docflows не возвращает ДО следующих типов:

urn:docflow:business-registration,

urn:docflow:fns534-cu-broadcast,

urn:docflow:stat-cu-broadcast,

urn:docflow:fss-sedo-abonent-subscription-result,

urn:docflow:fss-sedo-provider-subscription,

urn:docflow:fss-sedo-abonent-subscription,

urn:docflow:fss-sedo-error,

urn:docflow:fss-sedo-pvso-notification.

Для документооборота Ответ на требование (urn:docflow:fns534-inventory) нужно использовать метод GET GetAllInventoryDocflows из раздела Документооборот описи.

После выбора из списка нужного документооборота получите его по идентификатору. В ответе вернется информация о документообороте и документах в нем. Не рекомендуем использовать отдельные методы получения документов по идентификатору: вся информация о них содержится в документообороте.

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

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

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

Примечание

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

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

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

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

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

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