API приложения
API «AI Документы»¶
API приложения AI Документы позволяет загружать документы в приложение, управлять ими и получать результаты распознавания без входа в интерфейс Битрикс24 — например, из внешней учётной системы или скрипта.
API имеет ресурсо-ориентированные URL-адреса, принимает тела запросов, кодируемые формой или JSON структурами, возвращает ответы, кодируемые JSON, и использует стандартные коды ответов HTTP и аутентификацию.
Доступ к API¶
Для работы с API необходим ключ (токен). Его можно получить в приложении AI Документы:
- Запустите приложение и откройте раздел меню Настройки/Настройки API
- Сгенерируйте API-токен кнопкой Сгенерировать API-токен
- Там же отображается базовый URL API (адрес приложения с суффиксом
/api/v1/) и перечень основных методов
Доступность по тарифу
Раздел Настройки API и выдача токена доступны, если ваш тариф включает опцию API-доступ. Если раздел недоступен — проверьте тариф в приложении.
Все запросы выполняются с заголовком Authorization:
curl -X GET \
https://example.com/api/v1/ai-document/1/ \
-H "Authorization: Token YOUR_TOKEN_HERE"
Замените YOUR_TOKEN_HERE на ваш фактический токен, а https://example.com — на адрес из раздела Настройки API.
Один токен — один владелец
Все документы, загруженные через API, принадлежат вашему порталу Битрикс24: чужие документы через API недоступны. При перегенерации токена старый перестаёт действовать.
Документ (объект ai-document)¶
Объект Документ содержит загруженный файл и результаты его обработки: определённый тип, подтип, распознанный текст и извлечённые данные.
Объект имеет следующую структуру (возвращается методом GET):
| Наименование | Тип данных | Комментарии |
|---|---|---|
| id | integer | идентификатор документа |
| crm_deal | integer | идентификатор сделки в приложении (если документ привязан к сделке) |
| ai_document_type | integer | идентификатор типа документа |
| subtype | integer | идентификатор подтипа документа |
| type_detection_status | string | статус определения типа (см. таблицу статусов) |
| type_detection_status_updated_at | date-time | дата обновления статуса определения типа |
| subtype_detection_status | string | статус определения подтипа |
| subtype_detection_status_updated_at | date-time | дата обновления статуса определения подтипа |
| recognition_status | string | статус распознавания (см. таблицу статусов) |
| recognition_status_updated_at | date-time | дата обновления статуса распознавания |
| text | string | распознанный текст документа |
| common | object | извлечённые данные в формате JSON: ключи соответствуют ключам JSON, заданным в настройках типа документа |
Загрузить документ¶
curl -X POST \
https://example.com/api/v1/ai-document/create/ \
-H "Authorization: <Ваш токен>" \
-F "attachment=@/path/to/file.pdf" \
-F "attachment_name=file.pdf"
Запрос отправляется в формате multipart/form-data:
attachment— файл документа (обязательно). Поддерживаются сканы, фотографии, PDF и Doc-файлыattachment_name— имя файла (обязательно)ai_document_type— идентификатор типа документа (необязательно). Если тип не указан, приложение определит его автоматическиcrm_deal— идентификатор сделки в приложении (необязательно)
Метод возвращает идентификатор созданного документа:
{
"id": 123
}
Обработка после загрузки
После загрузки документ обрабатывается автоматически: определяются тип и подтип, извлекается текст и данные. Отдельный запуск обработки не требуется — статусы можно отслеживать методом GET.
Если включён ручной режим обработки, документ вместо автоматической обработки будет ожидать запуска обработки в сделке (см. Ручной режим обработки).
Получить документ и результаты распознавания¶
curl -X GET \
https://example.com/api/v1/ai-document/123/ \
-H "Authorization: <Ваш токен>"
Метод GET на вход передает идентификатор документа {id} и возвращает полную структуру документа: статусы обработки, распознанный текст (text) и извлечённые данные (common).
Пример возвращаемой структуры¶
{
"id": 123,
"crm_deal": 45,
"type_detection_status": "completed",
"type_detection_status_updated_at": "2026-10-09T10:15:30.123456Z",
"ai_document_type": 7,
"subtype_detection_status": "completed",
"subtype_detection_status_updated_at": "2026-10-09T10:15:35.654321Z",
"subtype": 12,
"recognition_status": "recognised",
"recognition_status_updated_at": "2026-10-09T10:16:02.111111Z",
"text": "СЧЁТ № 145 от 01.10.2026 ...",
"common": {
"invoice_number": "145",
"invoice_date": "01.10.2026",
"total_amount": "25 000,00"
}
}
Статусы документа¶
Статусы показывают, на каком этапе обработки находится документ. Дождитесь значения recognised у поля recognition_status — после этого в common доступны извлечённые данные.
type_detection_status (определение типа):
| Значение | Описание |
|---|---|
| manual | тип указан вручную |
| pending | ожидает обработки |
| waiting_crm_deal_processing | ожидает запуска обработки в сделке (ручной режим обработки) |
| locked | обработка начата |
| completed | обработка завершена |
| retry | требуется повторная обработка |
| max_attempts_exceeded | превышено количество попыток |
| skip | определение не требуется |
| error | ошибка |
subtype_detection_status (определение подтипа):
| Значение | Описание |
|---|---|
| manual | подтип указан вручную |
| pending | ожидает обработки |
| locked | обработка начата |
| completed | обработка завершена |
| skip | определение не требуется |
| error | ошибка |
recognition_status (распознавание и извлечение данных):
| Значение | Описание |
|---|---|
| pending | ожидает обработки |
| locked | обработка начата |
| compressed | файл сжат |
| mime_type_detected | тип файла определён |
| text_extracted | текст извлечён |
| json_extracted | данные в JSON извлечены |
| computed_fields_processed | вычисляемые поля обработаны |
| recognised | распознан (обработка успешно завершена) |
| retry | требуется повторное распознавание |
| max_attempts_exceeded | превышено количество попыток |
| skip | распознавание не требуется |
| error | ошибка |
Ручной режим обработки¶
Если в приложении включён ручной режим обработки, документы, привязанные к сделке, не распознаются сразу после загрузки: они ожидают запуска обработки в сделке (кнопка Запустить обработку или метод run-processing). Документ, загруженный без указанного типа, при этом отображается в статусе waiting_crm_deal_processing.
Чтобы файлы распознавались сразу после загрузки, отключите ручной режим:
- Запустите приложение AI Документы и откройте раздел меню Настройки/Настройки ручного режима обработки
- Снимите признак Ручной режим обработки документов
- Нажмите кнопку Сохранить
После отключения режима обработка документов запускается автоматически. Документы, уже ожидающие обработки в сделках, будут обработаны при очередном запуске обработки сделки.
Сделки без обработки
Документ, загруженный без привязки к сделке, обрабатывается автоматически независимо от этого режима.
Изменить документ¶
curl -X PATCH \
https://example.com/api/v1/ai-document/123/update/ \
-H "Authorization: <Ваш токен>" \
-H "Content-Type: application/json" \
-d '{
"ai_document_type": 7
}'
Метод PATCH на вход передает идентификатор документа {id} в строке запроса и в теле запроса JSON структуру. Все поля необязательны — передаются только изменяемые:
attachment_name— новое имя документаai_document_type— идентификатор нового типа документаsubtype— идентификатор подтипа (подтип должен принадлежать выбранному типу)
Метод возвращает обновлённые данные документа в формате JSON:
{
"id": 123,
"attachment_name": "file.pdf",
"ai_document_type": "Счёт на оплату",
"ai_document_type_id": 7,
"subtype": "Счёт от поставщика",
"subtype_id": 12,
"recognition_status": "Ожидает обработки"
}
Изменение типа перезапускает обработку
Если изменить тип документа, приложение заново извлечёт из него данные в соответствии с новыми настройками. Изменение только подтипа повторное распознавание не запускает.
Удалить документ¶
Метод: DELETE — /api/v1/ai-document/{id}/delete/
curl -X DELETE \
https://example.com/api/v1/ai-document/123/delete/ \
-H "Authorization: <Ваш токен>"
Метод удаляет документ вместе с файлом и результатами обработки. Успешное выполнение возвращает пустой ответ с кодом 204.
Операции со сделкой¶
Для автоматизации обработки сделок доступны методы, в которых сделка адресуется по bx_id — идентификатору сделки в Битрикс24. Данные возвращаются в формате JSON.
| Метод | Путь | Назначение |
|---|---|---|
| GET | /api/v1/crm-deal/{bx_id}/status/ |
сводный статус обработки сделки |
| PATCH | /api/v1/crm-deal/{bx_id}/select-crm-deal-type/ |
назначение типа обработки сделки |
| POST | /api/v1/crm-deal/{bx_id}/run-processing/ |
запуск обработки сделки |
| POST | /api/v1/crm-deal/{bx_id}/run-processing-full-reset/ |
запуск обработки с полным сбросом результатов |
| GET | /api/v1/crm-deal/{bx_id}/ai-documents/ |
список документов сделки |
| GET | /api/v1/crm-deal/{bx_id}/ai-document-groups/ |
список привязанных групп регламентных документов |
| POST | /api/v1/crm-deal/{bx_id}/ai-document-groups/set/ |
установка набора привязанных групп |
| GET | /api/v1/crm-deal/{bx_id}/computed-entities/ |
сводные результаты обработки сделки |
| GET | /api/v1/crm-deal/{bx_id}/generate-tasks/ |
задачи генерации документов по сделке |
| GET | /api/v1/generate-tasks/{id}/ |
результат генерации документа |
Типовая последовательность автоматизации:
- Назначьте тип обработки сделки (
select-crm-deal-type) - Загрузите документы (см. Загрузить документ), указав сделку
- Запустите обработку (
run-processing) - Отслеживайте прогресс через
statusи списки документов/результатов - Сгенерированные по шаблонам документы забирайте через
generate-tasksиgenerate-tasks/{id}(метод возвращает ссылки на файлы DOCX/PDF)
Очистка данных сделки
Метод POST /api/v1/crm-deal/{bx_id}/cleanup/ удаляет все данные обработки сделки (документы, сводные результаты, сгенерированные документы) необратимо и доступен только администратору. Сама сделка и её CRM-данные не затрагиваются.