.. _`API Экстерна для работы с учетными записями и организациями`: https://developer.kontur.ru/doc/extern .. _`API Экстерна для работы с черновиками и конструктором черновиков (draftsbuilder)`: https://developer.kontur.ru/doc/extern.drafts .. _`API Экстерна для работы с документооборотами и лентой событий`: https://developer.kontur.ru/doc/extern.docflows .. _`API Экстерна для работы с сервисом контентов`: https://developer.kontur.ru/doc/extern.contents .. _`API Экстерна для работы с сверкой по НДС`: https://developer.kontur.ru/doc/extern.nds .. _`SDK`: https://github.com/skbkontur/extern-java-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 Начало работы с API =================== .. toctree:: :maxdepth: 2 :hidden: stepbystep howtodrafts howtodocflow .. rubric:: Для начала работы с API * Получите :doc:`/auth_oidc/api-key`. * Пройдите :doc:`аутентификацию` и получите Access Token. * Для криптографических операций необходимо иметь электронную подпись. Если вы еще не заключали договор с Контуром и хотите познакомиться с методами API, напишите нам. Мы вышлем вам тестовый api-key, сертификат и тестовую учетную запись. Когда вы примете решение об интеграции и заключите договор с Контуром, вам будут высланы данные вашей персональной учетной записи для боевой и тестовой площадки. Так как в API много разделов и методов, это может запутать вас при первом погружении в тему электронного документооборота. Ниже описаны главные особенности API, которые нужно учитывать при работе с методами. Чтобы помочь вам постепенно погрузиться в API и использовать только нужные методы, мы описали наиболее частые сценарии по работе с API и составили алгоритм действий для каждого из них. .. rubric:: Что нужно знать об API * **Возвращаемые значения** — json, кроме сервиса контентов. Даже если в методе возвращаются байты, то они вернутся в виде Json-строки. Внутри строки контент возвращается в формате base64. Напротив, **принимаемые значения** контентов ожидаются как application/octet-stream. * **Работа с методами.** Все доступные методы можно смотреть через Swagger. Это упрощает создание http клиентов для вашего языка программирования. Если хотите отправлять запросы через Postman, то вы можете скачать JSON файл swagger’a и импортировать его в Postman. * Для Java есть официальный `SDK`_. * **Аутентификация** реализована на базе протокола :doc:`OpenId Connect`. Для получения токена нужен :doc:`api-key и client_id`. * Для **генерации тестовых данных** мы разработали сервис `Extern Test Tools`_, который позволяет сгенерировать данные пользователя, а также примеры отчетов в ФНС. **Разделы методов Swagger** * `API Экстерна для работы с учетными записями и организациями`_. * `API Экстерна для работы с черновиками и конструктором черновиков (draftsbuilder)`_. * `API Экстерна для работы с документооборотами и лентой событий`_. * `API Экстерна для работы с сервисом контентов`_. * `API Экстерна для работы с сверкой по НДС`_. **Трейсинг запросов в API Контур.Экстерна** В ответе каждого запроса к API Контур.Экстерна возвращается будет лежать заголовок X-Kontur-Trace-Id — уникальный идентификатор запроса. Рекомендуем сохранять или логировать на вашей стороне данный идентификатор для диагностики работы вашего приложения **Тестовая площадка** Сервис: https://extern-api.testkontur.ru/ В swagger документации все запросы по умолчанию отправляются на тестовую площадку. Сервис генерации тестовых данных `Extern Test Tools`_. Для ФНС на тестовой площадке есть свой набор инспекций (роботов), которые нужно указывать в тестовых файлах отчетов и параметре ifns-code. Они отличаются стратегией обработки документооборотов. При работе с *отчетностью в ФНС* используйте следующие коды инспекций: * 0087 — Принимает все документы. * 0088 — Что бы вы ему не прислали — не примет. * 0085 — Присылает уведомления об уточнении. **Сертификаты и подписи** * Для криптографических операций необходимо иметь `сертификат электронной подписи`_. См. также статью :doc:`Криптография`. * Виды поддерживаемой подписи: открепленная, встроенная, множественная. * Поддерживаемые форматы подписи: CMS/PKCS #7, XMLDsig. .. rubric:: Сценарии работы с API Порядок работы с методами зависит от цели и задач, которые вы решаете. Выделим основные три направления в работе с API Контур.Экстерна: - :ref:`отправка отчетности в контролирующие органы`, - :doc:`мониторинг документооборотов`, - представление ответа на требования ИФНС. Все перечисленные сценарии описаны в виде алгоритма действий с примерами вызова методов. .. _rst-markup-deferred: **Отложенное выполнение задач** В API применяется отложенное выполнение задач в методах, где это предусмотрено. Например, в методах: - :ref:`проверки`, :ref:`подготовки`, :ref:`отправки` черновика; - :ref:`печати документа в черновике`; - :ref:`печати документа в документообороте`; - :ref:`сборки DraftsBuilder в черновик`. Некоторые операции из этого списка потенциально выполняются дольше других методов в API, возможно даже более 10-15 минут. Данные методы обрабатывают контенты документов, поэтому длительность работы также зависит от их размера. В таких методах реализован флаг асинхронного вызова методов ``deferred``. Когда приходит запрос с deferred = true, создается задача на выполнение операции в фоновом режиме. Метод возвращает идентификатор задачи, чтобы можно было отследить прогресс ее выполнения и получить результат. Отложенное выполнение задач более надежно, т.к. все HTTP запросы на постановку задачи и получение ее результатов будут короткие. Это минимизирует риск получить ошибку из-за обрыва соединения. Даже если при тестировании API идет обработка небольших документов, то в реальной работе в любой момент возможна отправка объемного документа, например, ответ на требование или декларация по НДС. В этом случае операция с контентом может долго выполняться, и сетевое соединение может быть разорвано. Тогда результат не будет получен, и операцию придется выполнять заново. .. warning:: С мая 2022 значение флага false устарело и больше не используется в методах API. При таком значении вернется ошибка 400 BadRequest.