API и вебхуки
Загрузка и чтение документов доступно через REST API. Управление учетной записью, папками, метками и соединениями остается в приложении.
Ключ
Создается в Настройки → Для разработчиков. Ключ отображается один раз, при создании — после этого только его отпечаток. Потерянный ключ не восстанавливается, создается новый, а старый удаляется. Можно иметь пять ключей, каждый с опциональным сроком действия до двух лет.
Владелец учетной записи получит электронное письмо о каждом новом ключе, а также за два недели до истечения срока действия ключа. См. Уведомление по электронной почте.
Ключ отправляется в заголовке X-API-Key.
Что умеет API
| Операция | Описание |
|---|---|
POST /api/upload | Загрузка файла с параметрами: формат, направление, тип, валюта, схема, папка, вебхук |
POST /api/upload/url | То же самое с публичного адреса; файл загружается самостоятельно |
GET /api/jobs | Список документов с фильтрами и постраничным выводом |
GET /api/jobs/{id} | Статус, прочитанные данные, находки и результат в целевом формате |
GET /api/jobs/{id}/original | Загруженный файл |
DELETE /api/jobs/{id} | Удаление в корзину |
Excel и PDF возвращаются в результате как Base64. Кто не нуждается в результате, отправляет
includeResult=false, тем самым экономя ресурсы на сервере.
Описание интерфейса в формате OpenAPI доступно по адресу /api/docs; ссылка находится в настройках
у ключей. Описание генерируется из текущего кода, поэтому соответствует тому, что делает API.
Проверка у документов из API
Проверка перед отправкой действует по умолчанию и для документов, загруженных ключом: документ ждет подтверждения в приложении, а вебхук отправляется только после этого. Кто строит интеграцию, при которой никто не сидит у экрана, в Настройки → Проверка перед отправкой может убрать канал API или отключить проверку.
MCP
Для AI-агентов по адресу /api/mcp находится сервер MCP с тем же ключом. Он умеет читать
и искать документы, загрузка невозможна; загрузка возвращает готовую команду, которую агент
запустит сам.
Вебхуки
Вместо опроса состояния можно дождаться результата, когда он будет готов. Адрес устанавливается
для всей учетной записи в Настройки → Для разработчиков или для отдельной загрузки с параметром
targetWebhookUrl. Кнопка в настройках отправляет тестовое сообщение.
Отправляется POST с JSON: идентификатор документа, название файла, формат и результат в целевом
формате. Когда документ проходит проверку или обрабатывается повторно, вебхук приходит
второй раз с флагом исправления (IsCorrection).
Сообщение не подписывается. Проверьте отправителя, добавив свой секретный токен в адрес. Адреса в частные сети отклоняются.
Если вебхук не доставляется после всех попыток, примерно через четыре с половиной часа придет электронное письмо. Во время одного сбоя один раз, последующие сбои будут указаны в активности. Электронное письмо также придет после каждого изменения адреса вебхука, если его изменил кто-то другой, не вы.
Неудачные доставки повторяются с увеличивающейся задержкой, одиннадцать попыток в период примерно четырех с половиной часов. Каждая попытка видна в активности с ответом вашей стороны; у документа в выводе есть значок с результатом доставки.
Лимиты
API не имеет собственного лимита на количество вызовов в минуту; загрузка ограничивается кредитами, размером файла в зависимости от тарифа и двадцатью страницами на документ. Отказ будет возвращен как ошибка 400 с кодом, объясняющим причину. Сервер MCP ограничен десятью запросами в секунду.