Көтерме саудаға

Қысқаша

Көтерме саудада бір күнде аз счёт, бірақ әрқайсысы ірі — және әрқайсысының артында нақты тапсырыс, жүкқұжат, есеп айырысу тұр. Сондықтан бұл жерде маңыздысы QR емес, есептің дұрыс жүруі: externalOrderId арқылы счётты тапсырысқа байлау, Idempotency-Key арқылы қосарланудан қорғану және webhook арқылы төлемді өз жүйеңізге жазу. Бір сұрауда 100-ге дейін счёт шығаруға болады, ал тұрақты клиенттердің ай сайынғы төлемін жазылымға беруге болады.

Негізгі сценарий

Менеджер 1С-те немесе CRM-де тапсырысты бекітеді: №РН-00142, 1 480 000 ₸.
Жүйе счёт жасайды:

POST /api/v1/invoices
{
  "amount": 1480000,
  "kind": "phone",
  "description": "Тапсырыс РН-00142",
  "externalOrderId": "RN-00142",
  "customer": { "name": "ЖШС «Арна Трейд»", "phone": "77011234567" },
  "metadata": { "manager": "sultan", "warehouse": "almaty-1", "doc": "RN-00142" }
}

Клиенттің Kaspi-іне push келеді, ол төлейді.
Сізге invoice.paid webhook келеді — 1С-те төлем тіркеледі, тапсырыс жөнелтуге шығады.

Көтермеде kind: "phone" көбіне ыңғайлы: клиент офисте отырады, QR көрсететін экран жоқ. Бірақ мұнда екі шектеу бар: description 60 таңба және телефон 7XXXXXXXXXX пішімінде болуы керек. Клиент қасыңызда тұрса немесе қоймадан алып жатса, kind: "qr" қолайлы, онда сипаттама 100 таңбаға дейін.

Сома туралы

amount — теңгемен. QR счёт ең көбі екі ондық белгіні алады, телефонға счёт бүтін теңге болуы керек. Тиынды дөңгелектеуді өз жүйеңізде жасаңыз, әйтпесе сома қабылданбай қалады: Сома дұрыс емес немесе тиын жоғалып жатыр.
Біздің жағымызда құжатталған жоғарғы сома шегі жоқ, бірақ Kaspi өз жағынан шектеу қоюы мүмкін — ол шектеулерді Kaspi белгілейді, біз оларға әсер ете алмаймыз. Сондықтан бұрын-соңды болмаған ірі сомамен жұмыс бастар алдында бір счётты сынап көріңіз.
Клиенттің Kaspi жағындағы лимиті де бар. Сома өтпесе, мәселе бізде емес екенін тексеріңіз: Мәселе менде ме, Kaspi-де ме.

Қосарланудан қорғану

Ірі сомада қосарланған счёт — нақты шығын. Екі құралды бірге қолданыңыз.

Idempotency-Key тақырыбы. Мәні тапсырысқа байланған болсын, мысалы RN-00142-v1. Сол кілтпен қайталап жіберсеңіз жаңа счёт жасалмайды, бұрынғысы қайтады (HTTP 200, idempotentReplay: true). Желі үзіліп, жауап жетпей қалғанда осы құтқарады.

externalOrderId. Сіздің тапсырыс нөміріңіз. Webhook-та қайта келеді, іздеуде де қолданылады. Осы арқылы счётты құжатқа байлайсыз.

Егер қосарланған счёттар жаппай кетіп жатса, ең бірінші кілтті жойып, ағынды тоқтатыңыз: Счёттар қосарланып жатыр. Толық сипаттама: Идемпоттылық.

Топтап счёт: POST /invoices/bulk

Ай басында дилерлерге, дүкендерге немесе нүктелерге бір мезгілде счёт шығару керек болса, бір сұрауда 1-100 счёт жібересіз.

Маңызды тәртіп:

Әр элемент бөлек тексеріледі. Біреуінің телефоны қате болса, қалғандары жасала береді. Бәрі құламайды.
Жауапты элемент бойынша қарап шығыңыз: қайсысы жасалды, қайсысы қандай қатемен құлады.
Құлағандарын түзеп қайта жіберіңіз — бірақ сол Idempotency-Key немесе сол externalOrderId мәндерімен, әйтпесе сәтті жасалғандары қосарланады.
100-ден көп болса, бірнеше сұрауға бөліңіз. Бәрін бір мезетте атқылап жібермеңіз: Сұрау жиілігінің шектеулері.
Есепте metadata ішіне дилер кодын жазып қойыңыз, кейін топтауға ыңғайлы.

Толығырақ: Топтап счёт жасау.

Тұрақты клиенттерге жазылым

Ай сайын бір клиентке бір сома шығып тұратын болса (сервис ақысы, абоненттік жеткізу, жалдамалы жабдық), жазылым қолайлы.

Бірақ көтермеде оның шегін білу керек: жазылым тек счёт шығарады, ақша өздігінен алынбайды — клиент әр төлемді Kaspi-де өзі растайды. Сондықтан ол келісімшарт бойынша міндетті төлемді кепілдендірмейді, ол тек «счётты қолмен шығаруды ұмытып кету» мәселесін шешеді.

Баптаулары: аралық month/week/day және кратность every; қайталау сатысы retryDelaysMin (әдепкі [15, 60, 360] минут, ең көбі 5 мән); өткізіп алу саясаты misfirePolicy — run_once (әдепкі) немесе skip, misfireAfterMin әдепкі 1440. Клиент уақытша тоқтаса pause, қайта бастағанда resume, өткен кезекті қуып жету керек болса { catchUp: true }.

Толығырақ: Жазылымдық бизнеске.

1С-пен байланыстыру

Дайын модуль жоқ, бірақ типтік схема жұмыс істейді:

HTTP-сервис немесе фондық тапсырма. 1С «Счёт на оплату» немесе «Реализация» құжатынан POST /api/v1/invoices жібереді. externalOrderId — құжат нөмірі.
Кілт 1С серверінде тұрады, пайдаланушының машинасында емес.
Төлемді екі жолмен қабылдайсыз. Ең сенімдісі — webhook сіздің серверіңізге келеді, ол 1С-ке жазады. Егер 1С сыртқа шыға алмайтын контурда тұрса, GET /api/v1/invoices арқылы мезгілмен сұрап тұрасыз.
Номенклатура бізге жіберілмейді. Счётта тек сома мен сипаттама бар, тауар тізімі 1С-те қалады.

Нұсқаулық: https://api.qut.kz/docs/guide/1c және 1С-тен Kaspi счёттарын шығару.

Ішінара төлем және қайтару

Ішінара төлем. Бір счёттың бір бөлігін төлеу мүмкін емес — Kaspi счёты бөлінбейді. Транш керек болса, бірнеше счёт шығарасыз:

Алдын ала төлем 30%: externalOrderId: "RN-00142-A", сомасы 444 000.
Қалғаны жөнелтер алдында: externalOrderId: "RN-00142-B", сомасы 1 036 000.
Екеуінің metadata ішінде ортақ doc: "RN-00142" тұрсын — есепте бір тапсырыс болып жиналады.

Тапсырысты бөліктердің бәрі төленгенде ғана жабыңыз.

Қайтару. Толық та, ішінара да болады:

POST /api/v1/invoices/{id}/refund
{ "amount": 120000, "reason": "Жарамсыз тауар қайтарылды, РН-00142" }

Ішінара қайтарылған счёт partially_refunded күйіне өтеді, ал ол әлі де «төленген» деп есептеледі. Жауап белгісіз күймен келсе (refund_unknown) қайталап жібере салмаңыз — ірі сомада бұл қымбатқа түседі: Екі рет қайтарып жіберуден қалай сақтану керек. Толығы: Қайтару API.

Есеп айырысу және салыстыру

CSV экспорт — кезең бойынша, бухгалтерияға беруге дайын: CSV экспорт және есеп.
Салыстыруды externalOrderId бойынша жасаңыз, сома бойынша емес. Бірдей сомалы екі тапсырыс жиі кездеседі.
Ақша тіке сіздің Kaspi шотыңызға түседі, бізде ұсталмайды. Сондықтан банк үзіндісімен салыстырғанда сома сол қалпында көрінеді, Kaspi-дің өз шарттарын ескеріңіз.
Кеш келген төлемді ұмытпаңыз. Жабылған счётқа ақша кейін келсе, invoice.paid late: true белгісімен келеді — ай жабылып кеткен болуы мүмкін: Кеш келген төлем.

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

Ең үлкен сома қанша болуы мүмкін? Біздің жағымызда құжатталған шек жоқ. Kaspi мен клиенттің өз лимиттері болуы мүмкін — оны Kaspi белгілейді. Үлкен сомамен жұмысты бір сынақ счётынан бастаңыз.

Бір сұрауда қанша счёт жіберуге болады? 1-ден 100-ге дейін. Әр элемент бөлек тексеріледі, біреуінің қатесі қалғандарын құлатпайды.

Клиент соманың жартысын төлей ала ма? Бір счёт бойынша — жоқ. Транш үшін бөлек счёттар шығарасыз және оларды metadata арқылы бір тапсырысқа байлайсыз.

Жазылым келісімшарттық төлемді кепілдендіре ме? Жоқ. Ол счётты кестеге сай шығарады, ал төлемді клиент өзі растайды. Ақша өздігінен алынбайды.

1С-ке дайын өңдеу бар ма? Дайын модуль жоқ, бірақ типтік схема мен нұсқаулық бар: https://api.qut.kz/docs/guide/1c

Qut Pay — тәуелсіз сервис, «Kaspi Bank» АҚ-мен аффилирленбеген. Kaspi және Kaspi Pay — құқық иесінің тауар белгілері.