Smart kassaga topshirish

Smart kassa pulni qurilmada allaqachon yashaydigan sertifikatlangan toʻlov ilovasi orqali yigʻadi. Sitora kartani ham, PIN ni ham, provayder sessiyasini ham hech qachon koʻrmaydi — u hamrohingizga tasvirlangan yigʻimni topshiradi va nima qaytganini qayd etadi.

Hayotiy sikl

kassir smart_pos marshrutini tanlaydi
        │
        ▼
  niyat yaratildi ── soʻrovingiz ──▶ presented
        │                                │
        │                     toʻlov ilovasi ishlaydi
        │                                │
        │                          xabaringiz
        │                                ▼
        │                           processing
        │                                │
        │              kassir tasdiqlaydi (yoki bekor qiladi)
        ▼                                ▼
     expired                         succeeded

Marshrut kassirga faqat kassaga tirik topshirish qurilmasi biriktirilganda taklif qilinadi. «Tirik» degani faol heartbeat yuborayotgan — jim boʻlgan hamrohdan marshrut olib qoʻyiladi, unga hech kim bajarmaydigan ish topshirilmaydi.

Tayinlovni olish

GET /api/payments/v1/devices/assignment/
If-None-Match: "<last etag>"

{
  "assignment": {
    "intent_id": 42,
    "intent_display_number": 7,
    "order_display_number": 118,
    "station_name": "Kassa 1",
    "amount": "100000.00",
    "currency": "UZS",
    "status": "presented",
    "handoff_target": "uz.example.payapp",
    "expires_at": "2026-08-09T12:15:00Z"
  },
  "server_time": "2026-08-09T12:00:11Z"
}

Yigʻadigan narsa boʻlmasa, assignment null boʻladi. Yangi tayinlovni olish uni presented deb qayd etadi — bu qurilma oʻzicha keltirib chiqara oladigan yagona holat oʻzgarishi.

Har bir javob, 200 ham, 304 ham, X-Sitora-Poll-After va Retry-After ni keyingi soʻrovgacha kutiladigan soniyalar bilan olib yuradi — bugun ular uchta. Bu son Sitoraga tegishli va u sizning relizingizsiz oʻzgartirishi mumkin.

handoff_target — restoran egasi shu qurilma uchun sozlagan ishga tushirish havolasi. Sitora uni shaffof emas deb hisoblaydi: uni hech qachon tahlil qilmaydi, solishtirmaydi va unga qarab shoxlamaydi. Agar hamrohingiz nimani ishga tushirishini oʻzi bilsa, uni boʻsh qoldiring.

expires_at haqiqiy. Muddati oʻtgan niyat expired boʻladi va kassirga yangisini yaratishga toʻgʻri keladi, shuning uchun tayinlov ustida oʻtirib qolmang.

Natija haqida xabar berish

POST /api/payments/v1/devices/assignment/report/

{
  "intent_id": 42,
  "outcome": "reported_success",
  "provider_reference": "RRN-000123",
  "provider_code": "00",
  "client_idempotency_key": "collection-42-attempt-1"
}

Natija	Qachon ishlatiladi
`reported_success`	Toʻlov ilovasi tasdiqni qaytardi
`reported_declined`	U rad etishni qaytardi
`reported_cancelled`	Mehmon yoki kassir ilovada undan voz kechdi
`reported_unknown`	U yaroqli hech nima qaytarmadi yoki siz kutib ulgurmadingiz

provider_reference — ilovaning urinish uchun oʻz havolasi: RRN, slip raqami. U kassir tasdigʻi meros qilib oladigan havolaga aylanadi va integratsiyaning amaliy foydasi shunda: hech kim qogʻoz slipdan raqamni qayta termaydi.

provider_code — sizning kodlangan natijangiz, mashina lugʻati sifatida soʻzma-soʻz saqlanadi. U xodimlarga hech qachon xabar sifatida koʻrsatilmaydi.

client_idempotency_key yuboring. Oʻsha kalit bilan qayta urinish ikkinchi xabarni yozish oʻrniga dastlabki natijani qaytaradi.

Xabar nima qiladi va nima qilmaydi

U niyatni processing ga oʻtkazadi va kassirga siz nima deganingizni koʻrsatadi.

U quyidagilarni qilmaydi:

tranzaksiya yaratmaydi,
buyurtmani toʻlangan deb belgilamaydi,
niyatni yakunlamaydi — ikkala tomonga ham.

Agar siz rad etish haqida xabar bersangiz va kassir ekranida hamon «hisob-kitob qilish» taklifi tursa, bu xato emas, toʻgʻri xatti-harakat: qurilma eʼlon qilgan rad etish notoʻgʻri boʻlsa, buyurtmani ikkinchi marta yigʻish uchun boʻshatib yuborardi, shuning uchun Sitora ikkala javob uchun ham insonni konturda qoldiradi. Halol xabar bering va qarorni kassirga qoldiring.

reported_unknown — toʻlaqonli javob. Kutib ulgurilmagan yigʻimning natijasi nomaʼlum, va buni aytish taxmin qilishdan ancha yaxshi: kassir terminalga qarab, oʻzi koʻrgan narsadan kelib chiqib tasdiqlashi yoki bekor qilishi mumkin.

Rad etishlar

Holat	Kod	Maʼnosi
`404`	`handoff_not_assigned`	Bu niyat bu qurilmaga tayinlanmagan
`409`	`intent_not_actionable`	Allaqachon hisob-kitob qilingan, bekor qilingan yoki muddati oʻtgan
`403`	(vakolat sababi, `detail` ichida)	Qurilmangiz yoki kassangiz vakolatini yoʻqotdi
`503`	`content_key_missing`	Sitoraning bu oʻrnatmasi notoʻgʻri sozlangan; qayta urinish yordam bermaydi

404 va 409 detail siz {"code": "..."} qaytaradi, 409 esa niyatning status ini qoʻshadi. 403 soʻrovingiz bu endpointga yetib borgunicha rad etiladi, shuning uchun u sababini detail ichida nasr sifatida nomlaydi — autentifikatsiya bu sababni maydon sifatida qayerdan oʻqishni tushuntiradi.

"status": "expired" bilan kelgan 409 niyat ilovangiz ishlab turgan paytda muddati oʻtganini bildiradi. Uni qayta urinmang; yigʻimni kassirdan boshlab qaytadan boshlash kerak.