Рекомендации по работе 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`` — идентификатора организации.

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

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

1. Для получения списка ДО для конкретного типа при запросе метода укажите фильтр ``type``.
2. При получении общего списка ДО без фильтра ``type`` метод вернет все документооборы, кроме:  

    * проактивных выплат;
    * регистрации бизнеса;
    * рассылки от ФНС;
    * рассылки от Росстат. 

3. Для получения документооборота Ответ на требование (urn:docflow:fns534-inventory) нужно использовать метод :ref:`GET GetAllInventoryDocflows<rst-markup-get-all-inventory>` из раздела Документооборот описи.

Детальную информацию о документообороте можно получить по его идентфикатору ``docflowId`` с помощью метода :ref:`GET Docflow<rst-markup-get-dc>`. В ответ метод вернет также подробную информацию о документах в нем.

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

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

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

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

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

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

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

.. _rst-markup-deferred:

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

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

* :ref:`проверки<rst-markup-check>`, :ref:`подготовки<rst-markup-prepare>`, :ref:`отправки<rst-markup-send>` черновика;
* :ref:`печати документа<rst-markup-draft-print>` в черновике;
* :ref:`печати документа<rst-markup-dcprint>` в документообороте;
* :ref:`сборки DraftsBuilder<rst-markup-buildDB>` в черновик.

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

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

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

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

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