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

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

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

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

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

Пройдите аутентификацию и получите Access Token.
Создайте и отправьте черновик в контролирующий орган.
Отследите статус документооборота.
Отправьте ответные документы в контролирующий орган.

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

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

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

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

Для C# есть официальный SDK.
Аутентификация реализована на базе протокола OpenId Connect. Для получения токена нужен api-key и client_id.
Возвращаемые значения в значении 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.

Также мы подготовили примеры файлов отчетности и контракты для формирования документов в черновике.

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

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