ASL RAQAM Connect: hamkorlar uchun qo‘llanma

API versiyasi: v1 · Hujjat versiyasi: 0.9.2, 14.10.2026 (dastlabki)

Bu hujjat onlayn-kassalar (E-POS), TSD va hisob tizimlari dasturchilari uchun. Ular markirovka kodlarini tekshirishni ASL RAQAM Connect orqali ulaydi. To‘liq spetsifikatsiya OpenAPI 3.1 formatida: openapi.yaml. Endpoint va maydon nomlari, xato kodlari — ruscha qo‘llanma bilan bir xil.

Holat. API v1 tayyor va ASL BELGISI emulyatorida avtomatik testlardan o‘tadi. Ishchi va test manzillari ulanishda beriladi: hujjatda ishchi nom https://connect.aslraqam.uz ko‘rsatilgan. Hali ishlab chiqilayotgan imkoniyatlar «Keyinroq qo‘shiladi» bo‘limida.

Mundarija

1. Connect nima qiladi
2. 5 qadamda boshlash
3. API ning umumiy qoidalari
4. Merchantni ulash
5. Kodlarni tekshirish: POST /check
6. Verdiktlar
7. Kassa hodisalari: POST /events
8. Qoldiqlar, kodlar, nomuvofiqliklar
9. Sinxronlash
10. Inventarizatsiya
11. Vebhuklar
12. Foydalanish va tariflash
13. Xatolar va limitlar
14. Sinov muhiti: test kodlari
15. Kod misollari
16. Keyinroq qo‘shiladi
17. O‘zgarishlar jurnali

1. Connect nima qiladi

Kassa markirovka kodini skanerlaydi, Connect esa soniyaning bir qismida tovarni sotish mumkinmi yoki yo‘qmi va nima uchunligini aytadi.

• Sotuvdan oldin tekshiruv. Kod do‘kon balansidami? Muomaladami? Avval sotilmaganmi? Qadoq kodi emasmi? Javobda rang (🟢 🟡 🔴 ⚪), can_sell belgisi va kassir uchun o‘zbek va rus tilidagi tayyor matn keladi.
• Do‘kon kodlari lederi. Connect do‘konning kaliti bilan ASL BELGISI dan uning balansidagi barcha kodlarni yuklab oladi va har kecha yangilaydi. Tekshiruvlarning ko‘pchiligiga lederdan javob beriladi: tez va ASL ga yuk tushmaydi.
• Harakat hisobi. Kassa sotuv, qaytarish, qabul, hisobdan chiqarish va ko‘chirish haqida xabar beradi. Connect kodlar bo‘yicha qoldiqni yuritadi va nomuvofiqliklarni topadi, masalan «o‘z balansidan sotilmagan» yoki «ikki marta sotilgan».
• TSD bilan inventarizatsiya. Javondagi skan balans bilan solishtiriladi, Connect kamomad va begona kodlarni topadi.

Kassa ASL BELGISI bilan bevosita ishlamaydi: kalitlar, limitlar, qayta urinishlar va ASL nosozliklarini Connect o‘z zimmasiga oladi.

Kassa / TSD ──HTTPS──▶  ASL RAQAM Connect  ──▶  ASL BELGISI (do‘kon kaliti)
      ▲                        │
      └──── vebhuklar ◀────────┘

Asosiy qoida: kassa Connect sababli savdoni hech qachon to‘xtatmaydi. Agar Connect 3 soniyada javob bermasa yoki 5xx qaytarsa, kassa sotadi va sotuv hodisasini keyinroq yuboradi (3.6).

2. 5 qadamda boshlash

Misollarda sinov muhiti va test kaliti ck_test_… ishlatiladi. Sinov muhiti oldindan tayyorlangan kodlari bor ASL emulyatorida ishlaydi (14-bo‘lim).

export CONNECT=https://sandbox.connect.aslraqam.uz/api/v1   # manzil ulanishda beriladi
export KEY=ck_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

1-qadam. Kirishni tekshiring.

curl -s $CONNECT/health
# {"status":"ok"}

2-qadam. Do‘konni (merchantni) STIR bo‘yicha ro‘yxatdan o‘tkazing.

curl -s -X POST $CONNECT/merchants \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tin": "300000001", "name": "«Baraka» do‘koni"}'

3-qadam. Markirovkalanadigan tovarlar katalogini (GTIN) yuboring.

curl -s -X PUT $CONNECT/merchants/300000001/catalog \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode": "replace", "items": [{"gtin": "04780012345677", "name": "Suv 0,5 l"}]}'

4-qadam. ASL BELGISI ni ulang: do‘konning API kalitini va roziligini yuboring.

curl -s -X PUT $CONNECT/merchants/300000001/asl-key \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"key": "<do‘konning ASL API kaliti>",
       "consent": {"accepted": true, "version": "2026-10-v1", "user": "Direktor A. Karimov"}}'
# {"status":"active","organization":"…","product_groups":["14"],"expires_on":"2027-06-30T23:59:59+00:00","key_last4":"0001"}

Shundan so‘ng Connect balansni birinchi marta sinxronlashni boshlaydi. U tugagach, sync.completed vebhuki keladi.

5-qadam. Kodni kassada tekshiring.

curl -s -X POST $CONNECT/check \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  --max-time 3 \
  -d '{"merchant_tin": "300000001", "store_id": "store-01", "context": "SALE",
       "codes": ["010478001234567721OKOKOK00001"]}'

{
  "request_id": "01a13a69-0dcb-793f-9de1-319ece312fb9",
  "results": [{
    "index": 0,
    "ki": "010478001234567721OKOKOK00001",
    "verdict": "OK", "color": "green", "can_sell": true,
    "served_from": "ledger", "stale": false,
    "message": {"ru": "Можно продавать", "uz": "Sotish mumkin"},
    "hint": {"ru": "", "uz": ""},
    "product": {"gtin": "04780012345677"},
    "package": null,
    "asl": {"status": "INTRODUCED"},
    "details": {},
    "billable": false
  }],
  "summary": {"total": 1, "green": 1, "yellow": 0, "red": 0, "grey": 0, "can_sell_all": true},
  "connection": {"status": "active"}
}

Sotuvdan keyin SALE hodisasini yuboring (7-bo‘lim). Shu bilan eng kichik integratsiya tayyor.

3. API ning umumiy qoidalari

3.1. Manzil va protokol

3.2. Avtorizatsiya

Authorization: Bearer ck_live_…    # ishchi kalit
Authorization: Bearer ck_test_…    # test kalit

• Kalit berilganda bir marta ko‘rsatiladi. Biz faqat uning xeshini saqlaymiz va kalitni tiklay olmaymiz. Yo‘qotsangiz, yangisini beramiz, eskisini bekor qilamiz.
• Kalitga huquqlar (scope) va ruxsat etilgan IP manzillar cheklovini qo‘yish mumkin.
• Uzilishsiz almashtirish uchun hamkorda bir vaqtda ikkita amaldagi kalit bo‘lishi mumkin.
• Kalit hamkor serverida saqlanadi. Uni hech qachon brauzerga yoki kassirning mobil ilovasiga bermang.

3.3. Merchant va nuqtalar

• Merchant STIR orqali aniqlanadi: yo‘lda /merchants/{tin}/…, /check va /events da esa merchant_tin maydonida. STIR 9 xonali (yuridik shaxs) yoki 14 xonali (YaTT ning JShShIR) bo‘ladi.
• Begona yoki ro‘yxatdan o‘tmagan STIR uchun 404 MERCHANT_NOT_FOUND qaytadi, 403 emas: shunday qilib kim ulanganligi oshkor bo‘lmaydi.
• store_id — nuqtaning sizning tizimingizdagi ID si, 64 belgigacha bo‘lgan satr. Nuqtani oldindan ro‘yxatga olish shart emas: birinchi marta tilga olinganda u avtomatik yaratiladi. Nomi va manzilini PUT /merchants/{tin}/stores/{store_id} orqali berish mumkin.

3.4. Idempotentlik

• Barcha POST/PUT/PATCH/DELETE so‘rovlari uchun noyob qiymatli (UUID tavsiya etiladi) Idempotency-Key sarlavhasi majburiy. Istisno — /check: unda sarlavha ixtiyoriy, lekin tavsiya etiladi.
• Kalit 24 soat saqlanadi.
• Xuddi shu kalit va xuddi shu tana bilan qayta yuborilgan so‘rov o‘sha javobni Idempotent-Replayed: true sarlavhasi bilan qaytaradi. Aloqa uzilgandan keyin so‘rovni xavfsiz qaytarish mumkin.
• Xuddi shu kalit boshqa tana bilan kelsa — 409 IDEMPOTENCY_CONFLICT. Birinchi so‘rov hali bajarilayotgan bo‘lsa ham shu javob keladi (details.in_progress: true).
• So‘rov xato bilan tugasa, kalit bo‘shaydi va so‘rovni o‘sha kalit bilan qaytarish mumkin.

Kassa hodisalari uchun yaxshi amaliyot — kalitni chek ma’lumotlaridan yasash, masalan sale-{terminal_id}-{external_ref}. Shunda oflayn navbatdan qayta yuborilganda dublikat paydo bo‘lmaydi.

3.5. Kuzatuv, til, moslik

• X-Request-Id: siz yuborsangiz, javobda qaytadi; yubormasangiz, server o‘zinikini yaratadi. U har bir javob va har bir xatoda bor. Qo‘llab-quvvatlash xizmatiga yozganda shu ID ni ko‘rsating.
• Accept-Language: ru | uz xatolardagi message maydoni tilini tanlaydi. O‘zbekcha matn har doim message_uz da keladi. Tekshiruv natijalarida doim ikkala til bor.
• Noma’lum maydonlarni e’tiborsiz qoldiring. Yangi maydonlar versiya o‘zgarmasdan qo‘shiladi.
• Mos kelmaydigan o‘zgarishlar faqat /v2 da chiqadi; shundan keyin /v1 yana 6 oy ishlaydi.

3.6. Taymautlar va fail-open (majburiy)

ASL BELGISI nosozliklari /check da xatoga olib kelmaydi. ASL ishlamasa, Connect 200 bilan UNKNOWN verdiktini (⚪, can_sell: true) yoki stale: true belgili leder javobini qaytaradi. 5xx xatolari faqat Connect ning o‘zi nosoz bo‘lganda bo‘lishi mumkin.

3.7. Sahifalash

Ro‘yxatlar {"items": [...], "next_cursor": "…"} qaytaradi. Keyingi sahifa ?cursor=<next_cursor> bilan so‘raladi; limit 1000 dan oshmaydi (sukut bo‘yicha 100). next_cursor: null — ro‘yxat oxiri.

4. Merchantni ulash

4.1. Tartib

1. POST /merchants merchantni ro‘yxatga oladi, holati pending.
2. PUT /merchants/{tin}/catalog do‘kon sotadigan markirovkalanadigan GTIN lar ro‘yxatini yuboradi. Katalogni ulangandan keyin ham yuborish mumkin: yangi GTIN lar avtomatik yuklanadi.
3. PUT /merchants/{tin}/asl-key do‘konning ASL API kalitini va roziligini yuboradi. Connect kalitni tekshiradi (10 soniyagacha), shifrlangan holda saqlaydi va birinchi sinxronlashni boshlaydi.
4. merchant.connected vebhuki darhol keladi, sync.completed esa balans yuklangandan keyin.

4.2. Do‘konning ASL kaliti

Do‘kon API kalitini ASL BELGISI shaxsiy kabinetida yaratadi. Kalit foydalanuvchisida «Kuzatuvchi» roli «Markirovka kodlari» imtiyozi bilan bo‘lishi kerak.

PUT /merchants/300000001/asl-key
{
  "key": "<ASL API kaliti>",
  "rotation_mode": "manual",
  "consent": {"accepted": true, "version": "2026-10-v1", "user": "Direktor A. Karimov"}
}

Connect nimani tekshiradi: kalit formati, merchant STIR iga tegishliligi, rollar (ASL ga sinov so‘rovi), tashkilot va tovar guruhlari. Javob:

{"status": "active", "organization": "«Baraka» MChJ", "product_groups": ["14"],
 "expires_on": "2027-06-30T23:59:59+00:00", "key_last4": "0001"}

Ulanish xatolari (HTTP 422):

Ishlab turgan merchantning yangi kaliti tekshiruvdan o‘tmasa, Connect eski kalit bilan ishlashda davom etadi.

4.3. Ulanish holati

GET /merchants/{tin}/connection:

{"status": "active", "method": "manual", "key_last4": "0001",
 "expires_on": "2027-06-30T23:59:59+00:00", "key_expires_in_days": 259,
 "last_checked_at": "2026-10-14T12:34:57Z", "check_status": "ok", "missing_roles": [],
 "rotation_mode": "manual", "product_groups": ["14"], "consent_version": "2026-10-v1",
 "edo_status": null}

Kalit muddati tugashi haqidagi eslatmalar merchant.connection.expiring vebhuki bilan 14, 7, 3 va 1 kun oldin keladi.

4.4. Merchant sozlamalari

PATCH /merchants/{tin}:

{"name": "«Baraka» do‘koni", "policy": "strict",
 "policy_overrides": {"NOT_INTRODUCED": "block", "PACKAGE_CODE": "warn"}}

• policy: soft (sukut) yoki strict. Qat’iy rejimda 🟡 verdiktlar can_sell: false beradi. null — hamkorning sukut bo‘yicha sozlamasi.
• policy_overrides: muayyan verdiktga munosabat, allow, warn yoki block. Sabab bo‘yicha aniqlashtirish mumkin: "NOT_ON_BALANCE:INVOICE_NOT_SIGNED": "warn". Ustuvorlik tartibi: sabab verdiktdan muhimroq, merchant sozlamasi hamkor sozlamasidan muhimroq.
• 🔴 verdiktlarni allow ga o‘tkazib bo‘lmaydi: bunday so‘rov 400 qaytaradi.

4.5. Uzish

DELETE /merchants/{tin}: ASL kaliti darhol o‘chiriladi, leder ma’lumotlari hisobotlar uchun 90 kun saqlanadi.

4.6. Merchant uchun vidjet: sessiya

Ulash, qoldiqlar, nomuvofiqliklar va inventarizatsiya ekranlarini kassa interfeysiga vidjet sifatida joylash mumkin (vidjetning o‘zi ishlab chiqilmoqda, sessiyalar API si allaqachon ishlaydi).

1. Sizning serveringiz bir martalik token so‘raydi (widget:issue huquqi):

POST /widget/sessions
{"merchant_tin": "300000001", "store_id": "store-01", "locale": "uz",
 "user": {"id": "u-17", "name": "Aziz", "role": "owner"},
 "scopes": ["connect", "reports", "inventory", "settings"]}
→ 201 {"token": "wt_…", "url": "https://connect.aslraqam.uz/widget/", "expires_at": "…"}

1. Token 15 daqiqa yashaydi va bir marta almashtiriladi. Uni iframe ga sahifa manzilida emas, postMessage orqali bering: manzillar loglarga tushadi.
2. Vidjet tokenni o‘zi sessiyaga almashtiradi (POST /widget/exchange) va uni faqat xotirada saqlaydi. Sessiya bitta merchant bilan cheklangan: begona STIR — 404.

Kod tekshiruvi vidjetda doim ochiq. Hamkor kaliti brauzerga hech qachon tushmaydi.

5. Kodlarni tekshirish: POST /check

5.1. So‘rov

{
  "merchant_tin": "300000001",
  "store_id": "store-01",
  "context": "SALE",
  "receipt_draft_id": "draft-1001",
  "codes": ["010478001234567721OKOKOK00001"],
  "options": {"verify_authenticity": "off"}
}

Kodlarni skanerdan kelganicha yuborish mumkin: GS belgilari (\u001d), qavslar (01)…(21)…, ]d2 prefiksi, kripto-dum bilan. Connect kodni o‘zi KI ga (GTIN va seriya raqami) keltiradi. Kripto-dum faqat haqiqiylikni tekshirish uchun ishlatiladi, hech qayerda saqlanmaydi va hech qachon qaytarilmaydi.

5.2. Kontekstlar

5.3. Javob

Har bir kirish kodiga results[] da bitta element mos keladi, tartib o‘sha.

Misol: RECEIVE kontekstida qadoq kodi.

{
  "index": 0, "ki": "00467800123456BOX00001",
  "verdict": "OK", "color": "green", "can_sell": true, "served_from": "live",
  "package": {"type": "BOX_LV_1", "children_count": 3,
              "children": ["010478001234567721CHILD000001", "010478001234567721CHILD000002",
                           "010478001234567721CHILD000003"]},
  "asl": {"status": "INTRODUCED"}
}

5.4. Kassada qanday ko‘rsatish kerak

• message ni yirik, hint ni uning ostida maydaroq ko‘rsating. Tilni kassa sozlamasidan oling.
• Rangni color dan, «chekka urish yoki yo‘q» qarorini can_sell dan oling.
• can_sell — tavsiya. Kassa 🟡 ni katta kassir tasdig‘i bilan o‘tkazib yuborishi mumkin. Tovar tavsiyaga qarshi sotilgan bo‘lsa, buni sotuv hodisasining items[].override maydonida yuboring (7-bo‘lim).
• ⚪ (UNKNOWN, NOT_CONNECTED, SERVICE_SUSPENDED) doim sotishga ruxsat beradi.

5.5. Qancha kutish kerak

Lederdan javob o‘nlab millisekundda keladi. ASL ga jonli so‘rov 1,5 soniya bilan cheklangan. ASL ulgurmasa, Connect leder bo‘yicha javob (stale) yoki UNKNOWN qaytaradi va tekshiruvni fonda tugatadi. Fonda kod 🔴 bo‘lib chiqsa, check.updated vebhuki keladi.

6. Verdiktlar

Ikkala tildagi to‘liq matnlar va maslahatlar /check javobida (message va hint) keladi, ularni o‘zingizda saqlash shart emas.

NOT_ON_BALANCE sabablari (details.reason) Didox ulangandan keyin paydo bo‘ladi: INVOICE_NOT_SIGNED, INVOICE_SIGNED_PENDING, INVOICE_SIGNED_STUCK, INVOICE_REJECTED, NO_INVOICE. Didox siz bu maydon bo‘lmaydi.

7. Kassa hodisalari: POST /events

Kassa markirovkalangan tovar bilan har bir amal haqida xabar beradi. Shu ma’lumotlar bo‘yicha Connect qoldiqni yuritadi va nomuvofiqliklarni topadi.

{
  "merchant_tin": "300000001",
  "store_id": "store-01",
  "type": "SALE",
  "external_ref": "CHK-000123",
  "fiscal_sign": "123456789012",
  "terminal_id": "POS-1",
  "occurred_at": "2026-10-14T09:15:00Z",
  "items": [{"code": "010478001234567721OKOKOK00001", "price_tiyin": 450000}]
}

Javob 201:

{"event_id": 2, "accepted_items": 1, "rejected_items": [],
 "warnings": [{"index": 0, "warning": "SOLD_WITH_RED_VERDICT", "verdict": "ALREADY_SOLD"}],
 "late": false}

• Hodisa har doim qabul qilinadi, verdiktlar yomon bo‘lsa ham: kassa amalni allaqachon bajargan. Connect faktni qayd etadi va kerak bo‘lsa nomuvofiqlik ochadi.
• rejected_items[] — qabul qilinmagan pozitsiyalar (INVALID_FORMAT, DUPLICATE_IN_EVENT, INVALID_QUANTITY, INVALID_UNIT, INVALID_ITEM). Qolganlari qabul qilingan.
• warnings[]: SOLD_WITH_RED_VERDICT (🔴 verdiktli kod sotilgan), SOLD_TWICE (qaytarishsiz ikkinchi SALE).
• Oflayn kassalar hodisalari kechikib va tartibsiz kelishi mumkin. Connect ularni occurred_at tartibida qo‘llaydi.

Hodisani bekor qilish (bekor qilingan chek): POST /events/{event_id}/reverse. Takroriy bekor qilish xato bermaydi va o‘sha natijani qaytaradi.

{"event_id": 1, "reversed": true, "reversed_at": "2026-10-14T12:34:57Z", "restored": 1}

8. Qoldiqlar, kodlar, nomuvofiqliklar

Faylga yuklab olish. stock, codes va discrepancies da format=csv|xlsx parametri bor: filtrlar hisobga olingan barcha sahifalar bitta faylda keladi (100 000 qatorgacha; ko‘p bo‘lsa — 422 EXPORT_TOO_LARGE, filtrni toraytiring). CSV — BOM li UTF-8 va ; ajratgich, Excel da sozlashsiz ochiladi.

curl -s -H "Authorization: Bearer $KEY" -o stock.xlsx "$CONNECT/merchants/300000001/stock?format=xlsx"

Qoldiqlar misoli:

{"items": [{"gtin": "04780012345677", "name": "Suv 0,5 l", "on_balance": 5, "in_stock_local": 4,
            "sold_30d": 1, "open_discrepancies": 0, "last_sync_at": "2026-10-14T12:34:57Z"}],
 "next_cursor": null}

Nomuvofiqlik turlari

Sharti yo‘qolganda nomuvofiqlik avtomatik yopiladi, masalan yetkazib beruvchi kodlarni o‘tkazganda. Yuqori muhimlikdagi yangi nomuvofiqlik discrepancy.created vebhuki bilan keladi.

9. Sinxronlash

Connect do‘kon balansini ASL dan o‘zi yuklaydi: ulanganda to‘liq, keyin har kecha (harakatli GTIN lar har kuni, qolganlari haftada bir). Katalogdagi yangi GTIN lar kunduzi yuklanadi.

Qo‘lda ishga tushirish — merchant uchun soatiga 1 martadan ko‘p emas:

POST /merchants/{tin}/sync          {"gtins": ["04780012345677"]}   ← ixtiyoriy; maydonsiz — barcha GTIN lar
→ 202 {"sync_job_id": "01a13a68-…"}

GET /sync-jobs/{id}
→ {"id": "…", "kind": "manual", "status": "done", "gtins_total": 1, "gtins_done": 1,
   "codes_upserted": 6, "codes_left_balance": 3, "discrepancies_found": 2, "error": null}

status: queued, running, done, partial (GTIN larning bir qismi yuklanmadi), failed. Bir soatdan oldin qayta ishga tushirish details.retry_at bilan 429 qaytaradi. Tugagach sync.completed (birinchi va qo‘lda sinxronlash uchun) yoki sync.failed (har qanday turi uchun) vebhuki keladi.

10. Inventarizatsiya

1. POST /merchants/{tin}/inventory-sessions   {"store_id": "store-01", "scope": "all"}
                                              (yoki "scope": {"gtins": ["04780012345677"]})
   → 201 {"id": "<session_id>", "status": "open"}

2. POST /inventory-sessions/{id}/scans        {"codes": [...1000 tagacha...], "device_id": "TSD-7"}
   skanni bekor qilish: {"void": ["<ki>", ...]}

3. POST /inventory-sessions/{id}/finish       {"apply": false}

4. GET  /inventory-sessions/{id}               hisobot istalgan vaqtda

• Qadoq kodi tarkibiga ochiladi, ichidagi kodlar topilgan deb belgilanadi.
• Bitta kodning qayta skani takrorlanmaydi.
• Hisobot:

{"session_id": "…", "applied": false, "found_on_balance": 3,
 "shortage": ["…"], "shortage_count": 2,
 "foreign": ["010478001234567721FOREIGN0001"], "foreign_count": 1,
 "found_but_sold": [], "unknown_store_codes": 1,
 "by_gtin": [{"gtin": "04780012345677", "expected": 5, "found": 3}]}

• Kamomad D6 nomuvofiqligini, begona kodlar D7 ni ochadi.
• apply: true bo‘lsa, topilgan kodlar «mavjud», topilmaganlari «kamomad» holatiga o‘tadi.
• Tugagach inventory.finished vebhuki keladi.
• Excel dagi hisobot: GET /inventory-sessions/{id}?format=xlsx — «Сводка», «По GTIN», «Недостача», «Чужие коды», «Продано, но найдено» varaqlari.

11. Vebhuklar

11.1. Obuna

POST /webhooks  {"url": "https://pos.example.uz/hooks/connect",
                 "events": ["merchant.connected", "sync.completed", "discrepancy.created", "check.updated"]}
→ 201 {"id": "…", "secret": "…"}          ← sir bir marta ko‘rsatiladi (so‘rov takrorlansa — secret: null)
GET    /webhooks
DELETE /webhooks/{id}
POST   /webhooks/{id}/test                ← webhook.test sinov hodisasi

Manzil HTTPS bo‘lishi shart.

11.2. Hodisalar

11.3. Format

POST /hooks/connect HTTP/1.1
Content-Type: application/json
X-Connect-Signature: t=1760445325,v1=5f2b…
X-Connect-Event: merchant.connected
X-Connect-Delivery: 01a13a69-…

{"id": "evt_01a13a690cf578b8", "type": "merchant.connected",
 "created_at": "2026-10-14T12:35:25Z", "api_version": "v1", "merchant_tin": "300000001",
 "data": {"organization": "«Baraka» MChJ", "product_groups": ["14"], "expires_on": "2027-06-30T23:59:59+00:00"}}

11.4. Imzoni tekshirish (majburiy)

v1 = HMAC-SHA256(secret, "<t>." + so‘rovning xom tanasi), o‘n oltilik ko‘rinishda. 5 daqiqadan eski xabarlarni rad eting. Imzoni qayta seriyalangan JSON bo‘yicha emas, xom tana bo‘yicha hisoblang.

import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        ts = int(parts["t"])
    except (ValueError, KeyError):
        return False
    if abs(time.time() - ts) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

PHP va Node.js misollari 15-bo‘limda.

11.5. Yetkazish

• Serveringiz 10 soniya ichida 2xx bilan javob berishi kerak. Og‘ir ishlovni asinxron bajaring.
• Qayta urinishlar: 1 daq, 5 daq, 15 daq, 1 soat, 3 soat, 6 soat, 12 soat, 24 soatdan keyin; so‘ng yetkazish failed holatini oladi.
• Manzil 3 kun davomida hodisalarni qabul qilmasa, u o‘chiriladi va biz siz bilan bog‘lanamiz.
• Kafolat «kamida bir marta»: dublikatlarni id bo‘yicha tashlab yuboring. Hodisalar tartibi kafolatlanmaydi, created_at ga tayaning.

12. Foydalanish va tariflash

GET /usage?date_from=2026-10-01&date_to=2026-10-31 (davr 92 kungacha):

{"items": [{"day": "2026-10-14", "merchant_tin": "300000001", "store_id": "store-01",
            "checks_total": 14, "checks_billable": 9, "events_total": 1}],
 "totals": {"checks_total": 14, "checks_billable": 9, "events_total": 1, "active_stores": 1}}

Nima tariflanmaydi: - ck_test_ test kaliti bilan so‘rovlar; - INVALID_FORMAT, DUPLICATE_IN_REQUEST, UNKNOWN, NOT_CONNECTED, SERVICE_SUSPENDED verdiktlari; - o‘sha nuqtada o‘sha kodni 10 daqiqa ichida qayta tekshirish.

Tarif shartlari (faol nuqta uchun abonent to‘lovi, tekshiruvlar kvotasi, BHM) shartnomada belgilanadi. Joriy kun ma’lumotlari so‘rov paytida yangilanadi.

13. Xatolar va limitlar

13.1. Xato formati

{"error": {"code": "MERCHANT_NOT_FOUND", "message": "Мерчант не найден",
           "message_uz": "Merchant topilmadi",
           "request_id": "01a13a69-0f6e-78d2-b7b7-05a7e9b6c832", "details": {}}}

13.2. Limitlar

Limitlar hamkor uchun alohida sozlanadi. Har bir javobda X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset sarlavhalari bor.

14. Sinov muhiti: test kodlari

Sinov muhitida Connect ASL BELGISI emulyatori bilan ishlaydi. Test merchanti — STIR 300000001, test GTIN — 04780012345677. Sinov muhiti uchun ASL API kaliti hamkor kaliti bilan birga beriladi.

SALE kontekstidagi verdiktlar:

Jadval har safar hujjat yig‘ilganda avtomatik test bilan tekshiriladi.

15. Kod misollari

15.1. Python: fail-open bilan tekshiruv

import uuid
import httpx

CONNECT = "https://connect.aslraqam.uz/api/v1"
client = httpx.Client(base_url=CONNECT, headers={"Authorization": "Bearer ck_live_…"},
                      timeout=httpx.Timeout(3.0))

def check(tin: str, store: str, codes: list[str], draft_id: str) -> dict | None:
    """None — Connect ishlamayapti: sotamiz (fail-open)."""
    try:
        r = client.post("/check", json={"merchant_tin": tin, "store_id": store, "context": "SALE",
                                        "receipt_draft_id": draft_id, "codes": codes})
        if r.status_code == 200:
            return r.json()
        if r.status_code >= 500 or r.status_code == 429:
            return None
        r.raise_for_status()          # 4xx — integratsiya xatosi, uni tuzatish kerak
    except httpx.TransportError:      # taymaut, tarmoq yo‘q
        return None

def send_sale(tin: str, store: str, receipt_no: str, terminal: str, occurred_at: str, items: list[dict]):
    # Kalit chek ma’lumotlaridan: oflayn navbatdan qayta yuborish dublikat yaratmaydi
    key = f"sale-{terminal}-{receipt_no}"
    r = client.post("/events", headers={"Idempotency-Key": key}, json={
        "merchant_tin": tin, "store_id": store, "type": "SALE", "external_ref": receipt_no,
        "terminal_id": terminal, "occurred_at": occurred_at, "items": items}, timeout=10)
    r.raise_for_status()
    return r.json()

15.2. PHP: tekshiruv

<?php
function connect_check(string $tin, string $store, array $codes): ?array {
    $ch = curl_init('https://connect.aslraqam.uz/api/v1/check');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT_MS => 3000,                       // 3 soniyadan keyin fail-open
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('CONNECT_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'merchant_tin' => $tin, 'store_id' => $store, 'context' => 'SALE', 'codes' => $codes,
        ]),
    ]);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($body === false || $code >= 500 || $code == 429) {
        return null;                                      // sotamiz, hodisani keyin yuboramiz
    }
    return json_decode($body, true);
}

// Vebhuk imzosini tekshirish
function connect_verify(string $secret, string $header, string $rawBody, int $tolerance = 300): bool {
    $parts = [];
    foreach (explode(',', $header) as $p) {
        [$k, $v] = array_pad(explode('=', $p, 2), 2, '');
        $parts[$k] = $v;
    }
    if (!isset($parts['t'], $parts['v1']) || abs(time() - (int)$parts['t']) > $tolerance) {
        return false;
    }
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1']);
}
// $raw = file_get_contents('php://input');
// connect_verify($secret, $_SERVER['HTTP_X_CONNECT_SIGNATURE'] ?? '', $raw);

15.3. JavaScript (Node.js 18+)

const CONNECT = "https://connect.aslraqam.uz/api/v1";

export async function check(tin, store, codes) {
  try {
    const r = await fetch(`${CONNECT}/check`, {
      method: "POST",
      headers: { Authorization: `Bearer ${process.env.CONNECT_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({ merchant_tin: tin, store_id: store, context: "SALE", codes }),
      signal: AbortSignal.timeout(3000),          // 3 soniyadan keyin fail-open
    });
    if (r.status >= 500 || r.status === 429) return null;
    if (!r.ok) throw new Error(`Connect ${r.status}: ${await r.text()}`);
    return await r.json();
  } catch (e) {
    if (e.name === "TimeoutError" || e.name === "TypeError") return null;   // taymaut / tarmoq
    throw e;
  }
}

// Vebhuk imzosini tekshirish (express: app.post(path, express.raw({type: "application/json"}), …))
import crypto from "node:crypto";
export function verify(secret, header, rawBody, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const ts = Number(parts.t);
  if (!ts || Math.abs(Date.now() / 1000 - ts) > tolerance) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.`).update(rawBody).digest("hex");
  const got = Buffer.from(parts.v1 || "", "utf8");
  const exp = Buffer.from(expected, "utf8");
  return got.length === exp.length && crypto.timingSafeEqual(got, exp);
}

15.4. Ishga tushirishdan oldingi tekshiruv ro‘yxati

• [ ] /check taymauti 3 soniya; taymaut, 5xx yoki 429 da sotishga ruxsat beriladi.
• [ ] Hodisalar oflayn navbati, Idempotency-Key chek ma’lumotlaridan yasaladi.
• [ ] occurred_at vaqt zonasi bilan; 30 kundan eski hodisalar qabul qilinmaydi.
• [ ] Chekda bitta kodning qayta skanini ushlash uchun receipt_draft_id yuboriladi.
• [ ] Bekor qilingan chek /events/{id}/reverse orqali bekor qilinadi.
• [ ] 🟡/🔴 ga qarshi sotuv items[].override da yuboriladi.
• [ ] Vebhuklar: imzo xom tana bo‘yicha tekshiriladi, dublikatlar id bo‘yicha tashlanadi, 10 soniyada 2xx javob.
• [ ] Javoblardagi noma’lum maydonlar e’tiborsiz qoldiriladi.
• [ ] ck_live_ kalitlari faqat serverda saqlanadi; do‘konning ASL kaliti sizda saqlanmaydi.
• [ ] Loglarda X-Request-Id bor.

16. Keyinroq qo‘shiladi

Bu jadvaldagi metodlar /v1 ga mavjudlarini o‘zgartirmasdan qo‘shiladi.

17. O‘zgarishlar jurnali

Qo‘llab-quvvatlash: murojaat qilganda javobdagi X-Request-Id ni ilova qiling. Texnik yordam kontaktlari ulanishda beriladi.