Контур.Экстерн

Приложение Контур.Экстерн подключает аккаунт электронной отчётности к рабочему столу Promto. Агент читает организации, сертификаты, документообороты и события, собирает черновики отчётности, добавляет документы и запускает проверку.

Назначение

Экстерн подходит для контроля отчётных цепочек ФНС, СФР, Росстата и других направлений, разбора свежих событий, проверки сертификатов и подготовки отчёта до этапа квалифицированной подписи.

Подключение

Для каждого запроса Экстерн требует два секрета одновременно:

1. сессионный токен auth.sid;
2. API-ключ X-Kontur-Apikey.

Получите доступ для организации в кабинете разработчика Контура, откройте Контур.Экстерн → Настройки, вставьте оба значения и выберите контур. Для отдельного тестового доступа можно включить адрес extern-api.testkontur.ru; обычное подключение использует extern-api.kontur.ru.

Promto проверяет пару запросом списка аккаунтов GET /v1. Если доступен один аккаунт, он выбирается автоматически; если несколько — владелец выбирает основной в настройках. Секреты хранятся на сервере и отображаются только масками.

Интерфейс и данные

На главной находятся сценарии:

• Документообороты по типу;
• Лента событий;
• Сертификаты;
• Собрать и проверить черновик;
• Подключить Экстерн.

Настройки показывают выбранный контур и хост, маски двух секретов, доступные аккаунты с ИНН и КПП, основной аккаунт, последнюю ошибку, доступ агента и отключение.

Возможности агента

Инструмент — promto_extern. Он поддерживает:

• list_accounts, get_account, list_organizations;
• list_certificates с признаками облачной подписи;
• list_docflows, get_docflow, get_docflow_documents, get_document_description;
• list_events;
• list_drafts, get_draft;
• create_draft, add_draft_document, check_draft;
• generate_reply с публичной частью сертификата;
• start_cloud_sign, confirm_cloud_sign;
• request для дополнительных путей пространства /v1.

list_docflows всегда следует вызывать с параметром type. Без него Экстерн молча не включает несколько семейств документооборотов, поэтому неполный ответ можно ошибочно принять за полный. Пагинация использует skip и take: обычно до 100 элементов, для документооборотов — до 1000.

Сценарии

Документообороты одного типа

Через promto_extern сначала уточни у меня type, затем вызови list_docflows для выбранного аккаунта. Покажи статус, последнее событие и цепочки, которые ждут реакции. Не называй отправленный отчёт принятым без квитанции о приёме.

Проверка черновика

Через promto_extern подготовь create_draft и add_draft_document, показав точные данные до каждого изменения. После моего подтверждения создай черновик и вызови check_draft. На шагах prepare и send остановись: их завершает человек с сертификатом.

Ограничения и подтверждения

• create_draft, add_draft_document, generate_reply, start_cloud_sign и confirm_cloud_sign требуют явного согласия и confirm=true.
• check_draft может проверить неподписанные документы и не заменяет отправку.
• prepare и send сознательно не вынесены в отдельные действия. Generic request не создаёт недостающую подпись.
• Зашифрованные входящие документы ФНС нельзя прочитать или распечатать без закрытого ключа пользователя.
• Облачную подпись завершает человек: тип подтверждения приходит в confirm-type (sms, my-dss и другие варианты).
• Ответ ограничен 512 КБ. Сервер допускает не более 20 одновременных запросов к Экстерну.

Если что-то не работает

• 401. Не повторяйте запрос циклом. Чаще всего истёк auth.sid; получите новый сессионный токен и переподключите приложение.
• 403. У пары учётных данных нет права на аккаунт или действие.
• 409. Черновик или документооборот временно заблокирован текущей операцией. Подождите и повторите с ограниченной задержкой.
• Список документооборотов выглядит неполным. Передайте точный type; без него Экстерн пропускает отдельные семейства.
• Несколько аккаунтов. Выберите основной в настройках или передайте account_id явно.
• Не читается входящий файл ФНС. Он зашифрован на сертификат пользователя; откройте его в клиенте, где доступен закрытый ключ.

При обращении в поддержку сохраните безопасный текст ошибки и trace_id, если Экстерн вернул его. Не передавайте auth.sid или API-ключ.

Связанные материалы

• Интеграции
• Агенты
• Настройки Promto