Рекомендации по работе 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. использование :doc:`ленты событий</dc/лента событий ДО>`,
    2. чтение списка документооборотов.

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

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

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

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

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

.. note:: получать список ДО только **по одному типу** документооборота с использованием фильтра ``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) нужно использовать метод :ref:`GET GetAllInventoryDocflows<rst-markup-get-all-inventory>` из раздела Документооборот описи.

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

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

Для загрузки и скачивания документов рекомендуем всегда использовать :doc:`Сервис контентов</contents/index>`. Такой способ надежно будет работать для контентов любого объема.

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

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

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

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

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