Документация API · v2
API v2: создание сессии, получение результата и подтверждение приёма. Доступ выдаётся для согласованной интеграции.
Примеры содержат вымышленные идентификаторы. Рабочий ключ не публикуется: храните его в серверной части интеграции, не передавайте в браузер, QR-код или URL.
Подключение и авторизация
https://a8pro.kz/qrscan/api/v2 Authorization: Bearer YOUR_API_KEY Accept: application/json Content-Type: application/json
Ключ привязан к организации. Во всех трёх запросах передавайте постоянные UUID точки обслуживания (exchange_point_id) и рабочего узла (node_id). Согласуйте их назначение при подключении. Новый request_id создаётся для нового документа; при сетевом повторе используйте прежний.
1. POST /sessions
{
"request_id": "33333333-3333-4333-8333-333333333333",
"exchange_point_id": "11111111-1111-4111-8111-111111111111",
"node_id": "22222222-2222-4222-8222-222222222222",
"photo_quality": "medium",
"scan_mode": "digital"
}
Ответ 200 содержит request_id, status, mobile_url и expires_at. Покажите mobile_url как QR-код: оператор откроет его камерой телефона. Повтор с тем же request_id и контекстом возвращает ту же сессию. Истёкшая сессия не перезапускается — создайте новый UUID.
photo_quality: high / medium / low; по умолчанию medium.scan_mode: auto / digital / plastic / passport; по умолчанию digital.
2. POST /sessions/{request_id}/result
{
"exchange_point_id": "11111111-1111-4111-8111-111111111111",
"node_id": "22222222-2222-4222-8222-222222222222",
"receive": false
}
Фоновый опрос с receive=false возвращает waiting или ready без данных и не фиксирует незавершённую съёмку. Когда оператор закончил обе стороны документа и выбрал получение, отправьте receive=true с тем же контекстом.
{
"status": "ready",
"receipt_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"data": {
"first_name": "SYNTHETIC",
"last_name": "EXAMPLE",
"document_number": "TEST-ONLY"
}
}
Пример data сокращён. Возможные поля: document_name, iin, last_name, first_name, middle_name, birth_date, document_number, place_of_birth, nationality, issuing_authority, issue_date, expiry_date, citizenship.
Поля могут быть пустыми или отсутствовать. Даты обычно представлены строками ДД.ММ.ГГГГ. Проверяйте данные, не заменяйте существующие значения пустыми и допускайте дополнительные поля. Повтор receive=true до ACK возвращает тот же результат и receipt_token.
3. POST /sessions/{request_id}/ack
{
"exchange_point_id": "11111111-1111-4111-8111-111111111111",
"node_id": "22222222-2222-4222-8222-222222222222",
"receipt_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
Сначала надёжно сохраните результат в своей системе, затем отправьте ACK. Ответ: {"status":"sent"}. ACK очищает серверный результат; повторный ACK с правильной квитанцией допустим. После ACK запрос результата вернёт sent без данных.
Сроки, статусы и ошибки
Исходный срок сессии — 10 минут. Первое получение готового результата с receive=true устанавливает срок 30 минут. Ориентируйтесь на expires_at и статус ответа. Фоновая очистка удаляет просроченные результаты; после ACK данные очищаются в рамках обработки запроса. Это описание результата API, а не заявление об удалении данных у всех внешних обработчиков.
| HTTP / status | Действие |
|---|---|
| 200 · waiting / ready | Продолжить опрос / получить результат по действию оператора. |
| 200 · sent / expired / error | Завершить опрос. Для нового сканирования создать новый request_id. |
| 401 / 403 | Проверить Bearer-ключ / доступ организации. |
| 404 / 409 | Проверить идентификатор, точку, узел и квитанцию; не менять контекст существующей сессии. |
| 422 | Исправить поля согласно errors в JSON. |
| 429 / 5xx | Повторять с задержкой; при 429 учитывать Retry-After. Не создавать новый request_id при обычном сетевом повторе. |
Маршруты v2 ограничены 600 запросами в минуту. Для обычного ожидания достаточно опроса раз в 2–3 секунды; это рекомендация клиенту, а не гарантия времени распознавания.
Проверка интеграции
- Получите отдельный доступ для согласованного тестирования.
- Проверьте создание и повтор запроса, ожидание, получение и сохранение до ACK.
- Проверьте потерю ответа, повтор ACK, истечение срока и изоляцию разных точек и узлов.
Старый GET /api/v1/scan предназначен для существующих интеграций: чтение забирает и очищает последний результат организации. Не используйте его как резервный путь для v2. Общедоступное демо не выдаёт API-ключ.
Для обсуждения подключения укажите название и версию системы, сценарий работы и примерный объём документов. Ключ доступа выдаётся отдельно.