Рекомендации по работе 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:

  1. использование ленты событий,
  2. чтение списка документооборотов.

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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