Счёттар қосарланып жатыр

Қысқаша

Ең алдымен ағынды тоқтатыңыз: кабинеттен API кілтті жойыңыз. Кілт жойылған сәттен бастап сол кілтпен келген сұраулардың бәрі 401 алады, яғни жаңа счёт жасалмайды — кодыңызды түзетіп үлгергенше клиенттер артық счёт көрмейді. Ағын тоқтағаннан кейін ғана себебін іздеңіз: әдетте бұл идемпоттылықтың жоқтығы, қайталау циклі немесе webhook-ты қате өңдеу. Тұрақты шешімі — әр счёт сұрауына Idempotency-Key тақырыбын қосу.

Шұғыл тоқтату

1. Кабинетке кіресіз, API кілттер бөлімін ашасыз
2. Счёт шығарып жатқан кілтті жоясыз
3. Кодыңызды түзетесіз
4. Жаңа кілт жасап, серверде ауыстырасыз

Кілтті жою — ең жылдам «ажыратқыш». Оны өшіру үшін кодыңызды қайта жаюдың, серверді өшірудің қажеті жоқ.

Не өзгермейді: бұрын жасалған счёттар орнында қалады, webhook баптаулары сақталады, Kaspi байланысы үзілмейді. Кілттің өзі ғана жарамсыз болады.

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

Артық счёттарды тазалау

Ағын тоқтаған соң:

• Төленбеген артық счёттарды POST /api/v1/invoices/{id}/cancel арқылы жауып тастаңыз — сонда клиент оларды кездейсоқ төлеп қоймайды
• Клиент шынымен екі рет төлеп қойса, артығын қайтарасыз: Қайтару өтпей жатыр
• Счёттар тізімін externalOrderId бойынша сүзіп, бір тапсырысқа нешеу шыққанын көресіз

Асықпаңыз: pending күйіндегі счёт әлі төленуі мүмкін, сондықтан тазалауды ағынды тоқтатқаннан кейін ғана бастаңыз.

Себебін табу

tariff_daily_burst — бизнес лимиті емес, циклге түскен интеграциядан қорғайтын сақтандырғыш. Ол келсе, тарифті көтеруге асықпаңыз: алдымен кодты тексеріңіз. Айлық лимит бөлек кодпен келеді — tariff_limit_reached.

Idempotency-Key қалай қолданылады

Счёт жасау сұрауына Idempotency-Key тақырыбын қосасыз. Сол кілтпен екінші рет жіберсеңіз, жаңа счёт жасалмайды: бұрынғысы қайтады, HTTP 200 және жауапта idempotentReplay: true белгісі болады.

POST /api/v1/invoices
X-API-Key: qp_live_…
Idempotency-Key: order-10482
Content-Type: application/json

{ "amount": 12500, "externalOrderId": "10482" }

Кілтті қалай таңдау керек:

• Тапсырысқа байланысты болсын: тапсырыс нөмірі, себет идентификаторы, төлем әрекетінің идентификаторы
• Кездейсоқ болмасын. Әр сұрауда жаңа UUID жасасаңыз, идемпоттылықтан пайда жоқ
• Қайталанбасын. Бір тапсырысқа әдейі екі бөлек төлем керек болса, кілтке нөмір қосыңыз: order-10482-1, order-10482-2
• Сонымен қатар externalOrderId өрісін толтырыңыз: ол webhook-та қайта келеді және счёттарды іздеуге ыңғайлы

Идемпоттылық — бір жолғы түзету емес, әдеттегі тәртіп. Оны бәрі дұрыс істеп тұрғанда да қосып қойыңыз: желі үзілгенде, timeout болғанда, қайта жүктегенде ол сізді өзі қорғайды.

Қайталау циклін дұрыс жазу

Счёт жасау сұрауы қате бергенде қайталау қауіпсіз болуы үшін:

• Тек қайталауға болатын қателерде қайталаңыз: 502, 503 және Retry-After көрсеткен 429. 4xx қателерін қайталаудың мәні жоқ — сұрауды түзету керек
• Кідірісті өсіріңіз: 1, 2, 4, 8 секунд. Бірден циклмен қайталамаңыз
• Санын шектеңіз: мысалы 5 әрекеттен кейін тоқтап, қолмен қарауға белгі қойыңыз
• Әр әрекетте сол Idempotency-Key кілтін жіберіңіз, жаңасын емес
• Timeout-ты сәтсіздік деп есептемеңіз. Сұрау жетіп, счёт жасалып, тек жауап жоғалған болуы мүмкін. Идемпоттылық кілті осы жағдайды шешеді

Webhook өңдеуде идемпоттылық

Біз 2xx емес жауапқа хабарламаны 11 рет қайталаймыз. Сондықтан бір оқиға бірнеше рет келеді — бұл қалыпты. Егер өңдеушіңіз әр келген хабарламаға жауап ретінде жаңа счёт жасаса немесе тапсырысты қайта өңдесе, қосарлану сол жерден шығады.

(invoice.id, status) жұбын кілт ретінде алып, бұрын өңдеген оқиғаны екінші рет өңдемеңіз. Өңдеу ұзақ болса, алдымен 200 қайтарып, жұмысты фонда істеңіз — әйтпесе біз timeout деп есептеп, қайта жібереміз.

Алдын алу

• Клиенттің «Төлеу» батырмасын бірінші басқаннан кейін өшіріп қойыңыз
• Бір тапсырыста ашық счёт бар ма, жаңасын жасамай тұрып тексеріңіз
• Sandbox-та қайталауды әдейі сынаңыз: сол Idempotency-Key кілтімен екі рет жіберіп, екінші жауапта idempotentReplay: true келгенін көріңіз
• Кабинетте счёттардың саны кенет өсіп кетсе байқайтындай етіп, Telegram ботын қосып қойыңыз

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

Кілтті жойсам, бұрынғы счёттар жойыла ма? Жоқ. Счёттар, олардың күйлері мен тарихы сақталады. Тек кілттің өзі жарамсыз болады.

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

Sandbox счёттары лимитке кіре ме? Жоқ, sandbox счёттары айлық лимитке есептелмейді.

Клиент екі счётты да төлеп қойды, енді не істеймін? Артық сомасын қайтарасыз. Ішінара қайтару да қолдау көрсетіледі.

externalOrderId идемпоттылықты өзі қамтамасыз ете ме? Жоқ, ол іздеу мен есеп үшін. Қайталаудан қорғайтыны — Idempotency-Key тақырыбы.