API проверки документов: запрос, ответ и повторные обращения
Система отправляет комплект документов одним обращением с токеном компании и получает разбор: состав дела, исход каждой проверки и места расхождений. Повторное обращение по тому же делу не тарифицируется, поэтому безопасно повторять запрос при обрыве связи.
Короткий ответ: обращение выглядит как одна отправка комплекта с токеном и один ответ с разбором. Ниже разбор того, что важно учесть при встраивании в свою систему.
Авторизация
Компания получает токен при регистрации. Токен показывается один раз: в базе сервиса хранится только его отпечаток, восстановить значение нельзя. Практические следствия.
- Сохраните токен в хранилище секретов своей системы, а не в коде.
- Токен привязан к компании: по нему сервис понимает, чьё это дело и в чью историю его записать.
- Токен можно отозвать и выпустить новый, если он утёк.
- Каждая компания видит только свои дела, разделение сделано на уровне базы данных.
Что отправляется
Комплект документов и контрольные данные из вашей системы. Контрольные данные это то, с чем сервис будет сверять документы: номер дела, ИИН, сумма, дата. Чем больше контрольных значений передано, тем больше проверок выполняется.
| Что передаём | Зачем |
|---|---|
| Файлы документов | Собственно комплект дела |
| Номер дела в вашей системе | Чтобы связать разбор с вашей записью |
| Контрольные значения | Чтобы сверить документы с вашими данными |
| Ожидаемый состав комплекта | Чтобы понять, какого документа не хватает |
Что приходит в ответ
Ответ это не распознанный текст документов, а разбор. В нём три части.
- Состав комплекта. Какие документы опознаны, какие нет, каких не хватает.
- Проверки. По каждой: что сравнивали, какие значения нашли, совпало или нет, в каком документе.
- Итог. Сколько проверок сошлось, сколько нет, можно ли считать дело принятым.
Ответ подписывается ключом экземпляра сервиса, поэтому его можно хранить как подтверждение того, что разбор не менялся после выдачи.
Повторные обращения и обрывы связи
Комплект со сканами считается десятками секунд, а иногда минутами. За это время соединение может оборваться, и система не узнает результат. Правильное поведение в такой ситуации это повторить запрос.
Повторное обращение по тому же делу не тарифицируется: дело считается один раз, независимо от числа обращений по нему. Поэтому повтор безопасен и не приводит к двойной оплате. Это же правило снимает вопрос о том, что делать при таймауте: повторять.
Пределы и бесплатный объём
- Первые 50 дел в месяц бесплатны, дальше от 1500 тенге за комплект.
- При исчерпании бесплатного объёма сервис отвечает понятным отказом, а не молча отклоняет запрос.
- Размер комплекта ограничен сверху, крупные дела имеет смысл делить на части.
- Текущий расход виден в кабинете в любой момент, отдельного запроса для этого не нужно.
Что проверить при встраивании
- Обработку отказа по бесплатному пределу: система должна понимать, что делать дальше.
- Поведение при таймауте: повторять запрос, а не создавать новое дело.
- Хранение токена: в секретах, с возможностью замены без правки кода.
- Сохранение подписанного ответа, если разбор нужен как доказательство.
Частые вопросы
Как авторизуется обращение к сервису
По токену компании. Он выдаётся при регистрации, показывается один раз и хранится в базе только отпечатком. Токен можно отозвать и выпустить новый.
Тарифицируется ли повторный запрос по тому же делу
Нет. Дело считается один раз независимо от числа обращений, поэтому повторять запрос при обрыве связи безопасно.
Что приходит в ответе
Разбор дела: состав комплекта, исход каждой проверки с указанием документов и значений, и общий итог. Ответ подписывается ключом сервиса.
Видит ли одна компания дела другой
Нет. Разделение сделано в самой базе данных, а не фильтром в коде: чужие строки не возвращаются даже при ошибке в запросе.
Что с этим делать дальше
Если документы идут потоком, проверку стоит отдать сервису. DocVision Ai читает сканы и PDF, достаёт реквизиты, сверяет документы комплекта между собой и ведёт историю дел. Первые 50 дел в месяц бесплатно, дальше от 1500 тенге за комплект. Отдельный документ можно распознать онлайн без регистрации: файл читается в браузере и на сервер не уходит.