Жеткізу қызметіне

Қысқаша

Курьер есік алдында тұрғанда счётты сол жерде шығарады: Telegram бот арқылы немесе өзіңіздің курьер қосымшаңыздан. Клиент телефонын алып QR сканерлейді немесе Kaspi қосымшасына келген счётты растайды. Ақша тіке компанияның Kaspi шотына түседі, курьер қолма-қол ақша тасымайды. Тапсырыс нөмірін externalOrderId өрісіне, курьер мен маршрутты metadata ішіне жазасыз — сонда есеп өздігінен жиналады.

Сценарий

Тапсырыс сайтта немесе қоңырау арқылы қабылданды, төлемі — жеткізу кезінде. Бұрын бұл қалай жүретін: курьер қолма-қол ақша алады, майдасы жетпейді, күн соңында кассаға тапсырады, біреуі жоғалады, есеп ай соңында ғана шығады.

Керегі: курьер есік алдында бір батырма бассын, клиент телефонынан төлесін, ақша бірден компанияның шотына түссін, диспетчер тапсырыстың төленгенін нақты уақытта көрсін.

Жұмыс схемасы қадамдап

1. Курьер келді. Тапсырысты тапсырады, сомасын растайды (тауар алмастырылса сома өзгеруі мүмкін).
2. Счёт шығарылады. Курьер Telegram ботта /invoice командасын береді немесе өз қосымшасындағы «Төлем» батырмасын басады. Артында POST /api/v1/invoices шақырылады.
3. Клиент төлейді. Екі нұсқа: курьер экраннан QR көрсетеді, немесе kind: "phone" арқылы счёт клиенттің Kaspi қосымшасына push болып барады.
4. Растау келеді. Webhook invoice.paid жіберіледі, курьер қосымшасында тапсырыс «төленді» болады. Іс жүзінде бұл бірнеше секунд алады.
5. Курьер тауарды береді де, келесі мекенжайға кетеді.
6. Диспетчер көреді. Кабинетте немесе өз жүйеңізде маршрут бойынша қай тапсырыс төленгені көрінеді.

Қандай API әдісі керек

QR ма, телефонға счёт па

Телефонға счёт жібергенде нөмір 7XXXXXXXXXX пішімінде болуы керек. Айырмашылығы толық: QR счёт пен телефонға счёт.

QR-дың сканерлеу терезесі шектеулі. Клиент бірден сканерлемесе, терезе бітуі мүмкін — ондайда ескі счётты cancel арқылы жауып, жаңасын жасайсыз. Терезенің нақты уақытын expiresAt өрісінен алыңыз, кодқа тұрақты сан жазып қоймаңыз.

Тапсырыс нөмірі мен метадеректер

Счёт жасаған сәтте белгілерді дұрыс қойсаңыз, есеп кейін өздігінен жиналады:

• externalOrderId — тапсырыс нөміріңіз. Бұл өріс webhook-та қайта келеді, тізімде де, экспортта да көрінеді. «Бұл төлем қай тапсырыс бойынша» деген сұрақ бір іздеуде шешіледі.
• metadata — кез келген JSON. Мұнда курьердің идентификаторын, маршрут нөмірін, ауысымды, қоймалық аймақты, жеткізу уақытын сақтаңыз.
• description — клиент көретін мәтін. «Тапсырыс №1204, жеткізу» түрінде жазыңыз. QR счётта 100 таңба, телефонға счётта 60.

Курьер бойынша есеп жинағыңыз келсе, metadata ішіндегі курьер идентификаторы жеткілікті — CSV экспорттағанда сол өріс бойынша топтайсыз. Толығы: Metadata және тапсырыс нөмірі.

Кодсыз нұсқасы: Telegram бот

Курьерге бөлек қосымша жазудың қажеті жоқ — Telegram бот жеткілікті. Командалары:

Курьер телефонында Telegram болса жеткілікті. Ботты кабинеттен байланыстырасыз. Толығы: Telegram бот командалары.

Аз көлемді жеткізуде диспетчердің кабинеттен қолмен счёт жасап, сілтемені курьерге жіберуі де жарайды.

Қайтару

Клиент тауарды ашып көріп, қайтарып берсе, ақшаны POST /invoices/{id}/refund арқылы қайтарасыз: { amount?, reason? }. amount бермесеңіз толық, берсеңіз ішінара қайтарылады (мысалы бір позицияны ғана).

Екі рет қайтарып жібермеу үшін: сұраудың жауабы белгісіз болса (желі үзілді, таймаут), бірден қайталамаңыз. Алдымен GET /invoices/{id} арқылы қайтарулар тізімін оқыңыз. Толығы: Қайтару API.

Курьерге қайтару құқығын бермей, диспетчерге қалдырған дұрыс: refunds:write scope-ын курьер қолданатын кілттен алып тастаңыз.

Жеткізілмеген тапсырыс

Клиент үйде жоқ, телефон алмайды немесе қабылдаудан бас тартты. Реті:

1. Счёт жасалмаған болса — ештеңе істеудің қажеті жоқ, тапсырысты өз жүйеңізде «жеткізілмеді» деп белгілейсіз.
2. Счёт жасалып қойса, төленбесе — POST /invoices/{id}/cancel арқылы жабасыз. Ашық счёттар жиналып қалмағаны дұрыс.
3. Клиент төлеп қойып, содан кейін бас тартса — қайтару жасайсыз.
4. Кеш төлем келсе — бұл болатын жағдай. cancelled немесе expired счётқа ақша кейін келсе, invoice.paid оқиғасы late: true белгісімен келеді. Ондайда не тауарды қайта жеткізесіз, не ақшаны қайтарасыз. Жүйеңізде осы тармақ болсын: Кеш келген төлем.

Ерекше ескертулер

• Курьер қолма-қол ақша тасымайды — бұл негізгі пайдасы. Бірақ клиенттердің бір бөлігі бәрібір қолма-қол төлегісі келеді, екі жолды қатар қалдырыңыз.
• Кассир нөмірі клиентке көрінеді счёт хабарламасында. Бұл Kaspi-дің қалыпты жұмысы. Курьердің жеке нөмірі емес, компанияның кассир нөмірі көрінеді.
• Курьерге API кілтті бермеңіз. Курьер қосымшасы сіздің серверіңізге жүгінеді, ал сервер бізге. Кілт мобильді қосымшаға салынбауы керек.
• Интернет. Кейбір мекенжайларда байланыс нашар. Курьер қосымшасында счёт жасау сәтсіз болса, қайталауға мүмкіндік беретін батырма болсын — бірақ Idempotency-Key арқылы дубльден қорғаңыз.
• Сома өзгерсе ескі счётты жауып, жаңасын жасаңыз. Бір счёттың сомасын өзгерту мүмкін емес.
• Алдымен sandbox. qp_test_… кілтімен бүкіл циклді өткізіңіз: счёт, төлем симуляциясы, қайтару, болдырмау.

Жиі қойылатын сұрақтар

Курьерге бөлек құрылғы керек пе? Жоқ. Telegram бот кез келген телефонда жұмыс істейді. Өз қосымшаңыз болса, оған «Төлем» батырмасын қосасыз.

Курьер бөтен счётты көре ала ма? API кілтті нақты кассирге байласаңыз, ол тек сол кассир арқылы жүрген счёттарды көреді, басқаларына 404 қайтады.

Ақша курьердің шотына түсе ме? Жоқ. Ақша компанияның Kaspi шотына тікелей түседі.

Клиент есік алдында ойын өзгертсе не істеу керек? Счёт төленбеген болса cancel арқылы жабасыз. Төленіп қойса, қайтару жасайсыз.

Бір маршрутқа счёттарды алдын ала жасап қоюға бола ма? Болады, bulk арқылы. Бірақ QR-дың сканерлеу терезесі шектеулі, сондықтан счётты жеткізу сәтінде жасаған дұрыс.