API құжаттамасы · v2

API v2: сессия жасау, нәтижені алу және қабылдауды растау. Қолжетімділік келісілген интеграция үшін беріледі.

OpenAPI 3.0 · JSON

Мысалдардағы идентификаторлар ойдан алынған. Кілтті интеграцияның серверлік бөлігінде сақтаңыз; браузерге, QR-кодқа немесе URL-ге қоспаңыз.

Қосылу және авторизация

https://a8pro.kz/qrscan/api/v2
Authorization: Bearer YOUR_API_KEY
Accept: application/json
Content-Type: application/json

Кілт ұйымға байланысты. Үш сұраудың бәрінде қызмет көрсету нүктесінің (exchange_point_id) және жұмыс торабының (node_id) тұрақты UUID мәндерін жіберіңіз. Жаңа құжатқа жаңа 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-код ретінде көрсетіңіз. Бірдей идентификатор мен контекст қайталанса, сол сессия қайтарылады. Мерзімі аяқталған сессия үшін жаңа 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.

Өрістер бос болуы немесе болмауы мүмкін. Күндер әдетте КК.АА.ЖЖЖЖ жолдары түрінде беріледі. Деректерді тексеріңіз, бар мәндерді бос өрістермен алмастырмаңыз. ACK-ке дейін receive=true қайталау сол нәтиже мен 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 сервердегі нәтижені тазалайды; сол түбіртекпен қайталауға болады. Одан кейін нәтиже сұрауы деректерсіз sent қайтарады.

Мерзімдер, күйлер және қателер

Бастапқы сессия мерзімі — 10 минут. Дайын нәтижені receive=true арқылы алғаш алу мерзімді 30 минутқа орнатады. expires_at пен жауап күйін ескеріңіз. Фондық тазалау мерзімі өткен нәтижелерді жояды; ACK нәтиже деректерін сұрауды өңдеу кезінде тазалайды. Бұл сыртқы өңдеушілердің барлық деректерін жою туралы мәлімдеме емес.

v2 маршруттары минутына 600 сұраумен шектелген. Әр 2–3 секундта тексеру ұсынылады; бұл тану уақытына кепілдік емес.

Интеграцияны тексеру

1. Келісілген тестілеуге бөлек қолжетімділік алыңыз.
2. Жасау мен қайталауды, күтуді, алуды және ACK-ке дейін сақтауды тексеріңіз.
3. Жоғалған жауапты, ACK қайталауын, мерзім аяқталуын және нүктелер мен тораптар оқшаулауын тексеріңіз.

Ескі GET /api/v1/scan ұйымның соңғы нәтижесін алып, тазалайды. Ол бар интеграцияларға арналған; оны v2 үшін резервтік жол ретінде пайдаланбаңыз. Ашық демо API кілтін бермейді.

Қосылуды талқылау үшін жүйенің атауы мен нұсқасын, жұмыс сценарийін және құжаттардың шамамен санын көрсетіңіз. Қол жеткізу кілті бөлек беріледі.