REST API анализа документов
Когда договоры уже лежат в CRM или ЭДО, ручная загрузка в веб-кабинет тормозит процесс. API принимает файл, возвращает статус и структурированный результат анализа — чтобы юрист видел отчёт там же, где согласовывает сделку.
Базовый поток интеграции
- Авторизация. API-ключ в заголовке запроса; ключи выпускаются в кабинете, их можно отозвать.
- Загрузка. POST документа (PDF/DOCX и другие поддерживаемые форматы) с привязкой к проекту или внешнему ID сделки.
- Ожидание. Анализ асинхронный: опрашиваете status или ждёте webhook
analysis.completed/analysis.failed. - Результат. JSON с рисками, реквизитами, чек-листом и ссылками на выгрузки; при необходимости — export в файл.
Что обычно вызывают из кода
| Операция | Зачем | Замечание |
|---|---|---|
| Создание / загрузка документа | Старт анализа из CRM | Лимит размера файла по тарифу |
| Статус обработки | Polling без webhook | Не чаще разумного интервала |
| Результаты анализа | Карточка сделки / задача юристу | Структура версионируется |
| Пакетная загрузка | Пачка приложений к одной сделке | Квота на число файлов в batch |
| Экспорт | PDF/Excel отчёта во внутренний архив | См. также экспорт |
Webhooks и безопасность
- События. Завершение анализа, ошибка обработки, (опционально) критичный риск — подписка настраивается на URL.
- Retry. При недоступности endpoint система повторяет доставку с backoff; ваш обработчик должен быть идемпотентным.
- Транспорт. Только HTTPS; ключи не кладите в фронтенд-код браузера.
- Изоляция. Отдельный ключ на среду (sandbox / prod) и на сервис-интегратор; IP allowlist — по возможности.
Лимиты и границы применимости
- Rate limit и суточная квота документов зависят от тарифа; 429 — сигнал снизить параллелизм или увеличить план.
- API не заменяет UI для ручного разбора спорных формулировок: отчёт всё равно читает человек.
- Сканы без текста требуют OCR; качество распознавания влияет на полноту JSON.
- Обратная совместимость полей результата сохраняется в рамках major-версии; при смене версии — миграционный гайд в документации.
Когда нужен API, а не кабинет
Подключайте API, если договоры появляются из ЭДО/CRM пачками, нужен единый статус «проверено AIARM» в карточке сделки или вы строите внутренний конвейер согласования. Для нескольких файлов в неделю проще веб-интерфейс; API окупается на потоке и на встраивании в уже существующий UI.
Чек-лист внедрения API
| № | Что проверить | Где / контекст | Критерий «ОК» | Типичная ошибка |
|---|---|---|---|---|
| 1 | Ключ и среда | Кабинет / секреты | Отдельные ключи sandbox и prod | Один ключ в git |
| 2 | Идемпотентность | Ваш backend | Повтор webhook не дублирует задачу | Две задачи юристу на один файл |
| 3 | Обработка 429 | Клиент API | Backoff и очередь | Жёсткий retry в цикле |
| 4 | Маппинг полей | CRM | Риски и score видны в сделке | Только «анализ завершён» |
| 5 | Права доступа | Проекты AIARM | Сервисный аккаунт с минимальными правами | Админ-ключ на все проекты |
Порядок использования
- Получите sandbox-ключ и прогоните один PDF до получения JSON результата.
- Поднимите webhook и проверьте retry на недоступном URL.
- Встройте статус в карточку сделки; критичные риски — в задачу юристу.
- Переключите prod-ключ и включите мониторинг квоты.
Пример из практики
Договор из Битрикс24 → отчёт юристу
Без API. Менеджер скачивал файл из сделки, загружал на сайт, копировал выводы в комментарий. Часть договоров уходила на подпись без проверки.
С API. При смене стадии «согласование договора» CRM шлёт файл в AIARM; webhook возвращает score и список критичных пунктов; создаётся задача на юриста со ссылкой на отчёт. Связано с пакетной обработкой и безопасностью.
Частые вопросы
Синхронный ответ с полным анализом возможен?
Нет в общем случае: разбор договора занимает секунды или десятки секунд. Корректная схема — принять файл, вернуть ID, забрать результат по status или webhook. Синхронно имеет смысл только лёгкие утилиты из раздела tools, не полный отчёт.
Где хранить API-ключ?
В секретах сервера или vault, не в репозитории и не в мобильном/браузерном клиенте. Для каждого интегратора — свой ключ с возможностью отзыва без смены остальных.
Можно ли гонять персональные данные через API?
Технически канал тот же HTTPS, что и в кабинете. Организационно действуйте по своей политике: договор поручения, список лиц с доступом к ключу, минимизация полей во внешних логах (не пишите тело документа в plaintext-логи).
Что делать при смене формата JSON результата?
Фиксируйте Accept/версию API в клиенте. При major-обновлении сначала прогоните sandbox на фикстурах договоров, затем переключите prod. Не парсите «человеческие» строки отчёта — только стабильные поля схемы.
Соберите пилот на sandbox-ключе
Зарегистрируйтесь, выпустите ключ и прогоните один договор до JSON результата и webhook.