.. _`Работа с учетными записями и организациями`: https://developer.kontur.ru/doc/extern
.. _`Работа с черновиками и конструктором черновиков (draftsbuilder)`: https://developer.kontur.ru/doc/extern.drafts
.. _`Работа с документооборотами и лентой событий`: https://developer.kontur.ru/doc/extern.docflows
.. _`Работа с сервисом контентов`: https://developer.kontur.ru/doc/extern.contents
.. _`SDK`: https://github.com/skbkontur/extern-csharp-sdk 
.. _`Extern Test Tools`: https://developer.kontur.ru/doc/extern.test.tools
.. _`тестовой площадке`: https://extern-api.testkontur.ru
.. _`сертификат электронной подписи`: https://kontur.ru/ca/spravka/36-iz_chego_sostoit_sertifikat_elektronnoj_podpisi
.. _`отправьте заявку на подключение`: https://kontur.ru/extern/api
.. _`swagger документации`: https://developer.kontur.ru/

Начало работы с API
===================

Перед тем, как начать работу с API:

* `отправьте заявку на подключение`_ к API Контур.Экстерна. Менеджер свяжется с вами и предоставит :doc:`api-key и client_id</auth_oidc/api-key>`;
* получите электронную подпись для криптографических операций.

Алгоритм работы с методами API Контур.Экстерна
----------------------------------------------

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

1. Пройдите :doc:`аутентификацию и получите Access Token</auth_oidc/index>`.
2. :doc:`Создайте и отправьте черновик</drafts/work-order-drafts>` в контролирующий орган.
3. :doc:`Отследите статус</dc/work-order-do>` документооборота.
4. Отправьте ответные документы в контролирующий орган. 

Для некоторых сценариев алгоритм работы с методами может отличаться, особенности описаны в соответствующих статьях по сценариям. 

Что нужно знать об API
----------------------

* **Работа с методами**. Все доступные методы можно смотреть через Swagger:

    * `Работа с учетными записями и организациями`_.
    * `Работа с черновиками и конструктором черновиков (draftsbuilder)`_.
    * `Работа с документооборотами и лентой событий`_.
    * `Работа с сервисом контентов`_.

 На основе JSON-файла swagger'а можно сгенерировать клиента, это упрощает создание HTTP-клиентов для языка программирования. Если потребуется отправлять запросы через Postman, то можете скачать JSON файл swagger’a и импортировать его в Postman.

* Для **C#** есть официальный `SDK`_.
* **Аутентификация** реализована на базе протокола :doc:`OpenId Connect</auth_oidc/index>`. Для получения токена нужен :doc:`api-key и client_id</auth_oidc/api-key>`.
* **Возвращаемые значения** в значении application/json, кроме сервиса контентов. Даже если метод вернет байты, то они будут в виде Json-строки. 
* **Сервис контентов** – в API Контур.Экстерн реализована группа методов по загрузке контентов. Принимаемые значения в формате application/octet-stream. Возвращаемые значения в формате base64.
* Для **генерации тестовых данных** мы разработали сервис `Extern Test Tools`_, который позволяет сгенерировать тестовые отчеты, письма и другие виды отчетности, например, входящие требования.

Рабочая площадка
----------------

Сервис: https://extern-api.kontur.ru/

Тестовая площадка
-----------------

Сервис: https://extern-api.testkontur.ru/

В `swagger документации`_ все запросы по умолчанию отправляются на тестовую площадку.

Сервис генерации тестовых данных `Extern Test Tools`_.

На тестовых площадках есть специальные роботы, которые имитируют реальные контролирующие органы. Чтобы отправить отчетность роботу, укажите следующие коды инспекций в поле ``receipt`` при создании черновика:

* для ФНС в параметре ``ifns-code``:

    * 0087 – принимает все документы;
    * 0088 – не принимает ни один документ;
    * 0085 – присылает уведомления об уточнении.

* для Росстат в параметре ``togs-code``:

    * 00-87 – принимает все документы;
    * 00-88 – не принимает ни один документ.

* для СЭДО в параметре ``fss-code``:

    * SEDO-TEST.

Также мы подготовили :doc:`примеры файлов</test/files-for-examples>` отчетности и :doc:`контракты для формирования документов</test/contracts>` в черновике. 

Сертификаты и подписи
---------------------

* Для криптографических операций необходимо иметь `сертификат электронной подписи`_. См. также статью :doc:`Криптография</manuals/cryptography>`.
* Виды поддерживаемой подписи: открепленная, встроенная, множественная.
* Поддерживаемые форматы подписи: CMS/PKCS #7, XMLDsig.