API documentation · v2

API v2: create a session, receive a result and acknowledge receipt. Access is issued for an agreed integration.

OpenAPI 3.0 · JSON

Examples use synthetic identifiers. Keep the access key on your integration server; never put it in browser code, a QR code or a URL.

Access and authentication

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

The key identifies your organization. All three requests require stable UUIDs for the service point (exchange_point_id) and workstation (node_id). Agree their mapping during onboarding. Use a new request_id for a new document and reuse it for network retries.

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"
}

A 200 response contains request_id, status, mobile_url and expires_at. Display mobile_url as a QR code for the phone. Repeating a request with the same ID and context returns the same session. Expired sessions are not restarted; use a new UUID.

• photo_quality: high / medium / low; default medium.
• scan_mode: auto / digital / plastic / passport; default digital.

2. POST /sessions/{request_id}/result

{
    "exchange_point_id": "11111111-1111-4111-8111-111111111111",
    "node_id": "22222222-2222-4222-8222-222222222222",
    "receive": false
}

Polling with receive=false returns waiting or ready without document data and does not freeze an unfinished scan. Once the operator has finished both sides and chooses to receive the result, send receive=true with the same context.

{
    "status": "ready",
    "receipt_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "data": {
        "first_name": "SYNTHETIC",
        "last_name": "EXAMPLE",
        "document_number": "TEST-ONLY"
    }
}

The data example is abbreviated. Possible fields: document_name, iin, last_name, first_name, middle_name, birth_date, document_number, place_of_birth, nationality, issuing_authority, issue_date, expiry_date, citizenship.

Fields may be empty or absent. Dates are generally DD.MM.YYYY strings. Validate the data, avoid overwriting existing values with empty fields and tolerate additional fields. Repeating receive=true before ACK returns the same result and 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"
}

Durably save the result in your system before sending ACK. Response: {"status":"sent"}. ACK clears the server result and can be retried with the same receipt. Subsequent result requests return sent without data.

Expiry, statuses and errors

Sessions initially expire after 10 minutes. The first successful receive=true sets a 30-minute expiry. Respect expires_at and response status. Background cleanup removes expired results; ACK clears the result within the request. This describes API result retention, not retention by all external processors.

The v2 routes are throttled at 600 requests per minute. Polling every 2–3 seconds is a client recommendation, not a recognition-time guarantee.

Integration checks

1. Obtain separate access for agreed testing.
2. Test creation and retries, waiting, receiving and durable storage before ACK.
3. Test lost responses, repeated ACK, expiry and isolation between points and nodes.

Legacy GET /api/v1/scan consumes and clears the organization’s latest result. It is for existing integrations; never use it as a fallback for v2. The public demo does not issue an API key.

Tell us your system name and version, workflow and approximate document volume. Access keys are issued separately.