Қысқаша
Интеграцияны ЖИ-агентке тапсыруға болады. Ол үшін агентке үш нәрсе беріңіз: сілтемелер — https://api.qut.kz/for-ai және https://api.qut.kz/llms.txt, тек sandbox кілті (qp_test_…), және не істеу керегін нақты айтып жазылған тапсырма. Sandbox-та агент адамның көмегінсіз толық цикл жүргізе алады: счёт жасау → simulate арқылы төлемді симуляциялау → webhook келгенін тексеру. Live кілтті агентке бермеңіз.
Агентке не беру керек
1. Сілтемелер
| Сілтеме | Не үшін |
|---|---|
| https://api.qut.kz/for-ai | Агентке арналған бет: API-дің толық сипаттамасы бір жерде |
| https://api.qut.kz/llms.txt | Машина оқитын қысқа карта: қай құжат қайда |
| https://api.qut.kz/docs | Адамға арналған толық құжаттама |
| https://api.qut.kz/docs/guide/for_ai | Осы тәсілдің нұсқаулығы |
Агентке «Qut Pay API-ін біл» деп айтпаңыз — ол білмейді. Сілтемені беріңіз, ол өзі оқып алады. Осы сілтемелер болғанда агент өрістердің атауын, қате кодтарын және webhook пішімін ойдан шығармайды.
2. Sandbox кілті
Кабинет → Интеграциялар → API кілттер → жаңа кілт жасайсыз. Шарттары:
- Режимі sandbox, кілт
qp_test_префиксімен басталады - Scope-тары тек керегінше: әдетте
invoices:read,invoices:write, қажет болсаwebhooks:manage - Атын анық қойыңыз, мысалы «ЖИ-агент, sandbox» — кейін жою оңай болады
Осы кілтпен агент нақты ақшаға жете алмайды: sandbox-та Kaspi мүлде шақырылмайды.
3. Не істеу керегі
Агентке бұлыңғыр емес, нақты тапсырма беріңіз. Жақсы тапсырманың ішінде:
- Қандай оқиғада счёт шығару керек (тапсырыс жасалғанда, форма толтырылғанда, кестеге сай)
kindқайсысы:qrәлдеphoneexternalOrderIdретінде не жіберілетіні- Webhook қай адреске келуі керек және оны алғанда не істеу керек
- Қайталанудан қалай сақтану керек:
Idempotency-Keyжәне webhook өңдеуінің идемпоттылығы - Кілт орта айнымалысынан оқылуы керек, кодқа жазылмауы тиіс
Тапсырманы бір абзацпен емес, тізіммен жазған дұрыс: агент тізімді нақты орындайды.
Автономды sandbox циклі
Агенттің күшті жері — өзі жазып, өзі тексере алуы. Sandbox-та бұл циклді адамның қатысуынсыз жүргізуге болады:
- Счёт жасайды —
POST /api/v1/invoices,qp_test_кілтімен. Жауаптанidменstatusалады - Төлемді симуляциялайды —
POST /api/v1/invoices/{id}/simulate, денесінде{ "status": "paid" }. Бұл эндпоинт тек sandbox-та жұмыс істейді - Webhook келгенін тексереді — өз сервері
invoice.paidоқиғасын алды ма, қолтаңбасы дұрыс па - Күйді оқып растайды —
GET /api/v1/invoices/{id}paidқайтарды ма - Қате сценарийлерін де өтеді —
cancelled,expired, ішінара қайтару
Осы бес қадам ойдағыдай өтсе, интеграция шын мәнінде жұмыс істеп тұр деген сөз. Толығырақ: Sandbox-та төлемді симуляциялау және Интеграцияны қалай сынау керек.
Агент webhook-ті локалды тексере алуы үшін оған сынақ ортасында ашық адрес керек. Продакшенде туннель адресі қабылданбайды, бірақ sandbox-та сынау үшін жарайды.
Кілтті агентке беру қауіпсіздігі
ЖИ-агент — сіздің серверіңізде жұмыс істемейді. Ол сіз жазған мәтінді өзінің инфрақұрылымына жібереді, сөйлесу тарихын сақтауы мүмкін, ал кейбір құралдар кодты жария репозиторийге итеріп жібереді. Сондықтан:
| Ереже | Себебі |
|---|---|
Тек qp_test_ кілтін беріңіз | Sandbox-та нақты ақша жүрмейді, ең жаманы — қоқыс счёттар |
| Live кілтті ешқашан бермеңіз | Агент кездейсоқ цикл жасаса, нақты счёттар шығады және лимитіңіз бітеді |
| Кілтті кодқа емес, env-ке саласыз | Агент жазған код репозиторийге түссе, кілт онда болмайды |
| Scope-ты шектеңіз | refunds:write мен subscriptions:manage агентке керек емес |
| Жұмыс біткен соң кілтті жойыңыз | Кабинеттен бір басумен жойылады, ізі қалмайды |
| Live кілтті өзіңіз қоясыз | Live-қа көшу — адамның жұмысы, агенттікі емес |
Кілт кездейсоқ сыртқа шығып кетсе, кешіктірмей жойыңыз: API кілт сыртқа шығып кетті.
Агент жазған кодты қабылдағанда не тексеру керек
Агент нәтиже берді дегеніңіз — дайын деген сөз емес. Осы бесеуін өзіңіз қарап шығыңыз:
- Кілт қайда тұр. Кодта жазылып қалмаған ба, клиент жағындағы файлға түспеген бе
- Webhook қолтаңбасы тексеріле ме. Дене өзгертілмеген байт күйінде тексерілуі керек, JSON-ға айналдырғаннан кейін емес
- Идемпоттылық бар ма. Бір webhook екі рет келсе, тапсырыс екі рет жабылмауы керек
- Қателер өңделе ме. 401, 403, 429 және тариф қателеріне не болады
- Кеш төлем ескерілген бе.
cancelledнемесеexpiredсчётқаinvoice.paidlate: trueбелгісімен келуі мүмкін
Толық тізім: Интеграция қауіпсіздігі: чек-парақ.
Жиі қойылатын сұрақтар
Қай агент жарайды? Сілтемедегі құжаттаманы оқи алатын кез келгені: Claude Code, Cursor, басқа код жазатын агенттер. Талап біреу — интернеттен құжат оқи алуы керек.
Агент бүкіл интеграцияны өзі бітіре ме? Sandbox бөлігін — көбіне иә. Live-қа көшуді, кассир қосуды және тариф төлеуді адам істейді.
Агент нақты ақшаны жоғалта ала ма? qp_test_ кілтімен — жоқ. Sandbox-та Kaspi мүлде шақырылмайды.
Sandbox счёттары лимитке кіре ме? Жоқ. Sandbox счёттары айлық лимитке кірмейді және сынақ мерзімін де бастамайды.
Агентке кабинетке кіру керек пе? Жоқ. Кілт пен құжаттама жетеді. Кабинет — адамға.