# ЖИ-агентке интеграцияны тапсыру

> Claude, Cursor немесе басқа ЖИ-агент Qut Pay интеграциясын өзі жаза алады. Оған не беру керек, sandbox-та автономды цикл қалай құрылады және кілтті беру қауіпсіздігі.

## Қысқаша

Интеграцияны ЖИ-агентке тапсыруға болады. Ол үшін агентке үш нәрсе беріңіз: **сілтемелер** — 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` әлде `phone`
- `externalOrderId` ретінде не жіберілетіні
- Webhook қай адреске келуі керек және оны алғанда не істеу керек
- Қайталанудан қалай сақтану керек: `Idempotency-Key` және webhook өңдеуінің идемпоттылығы
- Кілт **орта айнымалысынан** оқылуы керек, кодқа жазылмауы тиіс

Тапсырманы бір абзацпен емес, тізіммен жазған дұрыс: агент тізімді нақты орындайды.

## Автономды sandbox циклі

Агенттің күшті жері — өзі жазып, өзі тексере алуы. Sandbox-та бұл циклді адамның қатысуынсыз жүргізуге болады:

1. **Счёт жасайды** — `POST /api/v1/invoices`, `qp_test_` кілтімен. Жауаптан `id` мен `status` алады
2. **Төлемді симуляциялайды** — `POST /api/v1/invoices/{id}/simulate`, денесінде `{ "status": "paid" }`. Бұл эндпоинт тек sandbox-та жұмыс істейді
3. **Webhook келгенін тексереді** — өз сервері `invoice.paid` оқиғасын алды ма, қолтаңбасы дұрыс па
4. **Күйді оқып растайды** — `GET /api/v1/invoices/{id}` `paid` қайтарды ма
5. **Қате сценарийлерін де өтеді** — `cancelled`, `expired`, ішінара қайтару

Осы бес қадам ойдағыдай өтсе, интеграция шын мәнінде жұмыс істеп тұр деген сөз. Толығырақ: [Sandbox-та төлемді симуляциялау](/kb/sandbox-simulate) және [Интеграцияны қалай сынау керек](/kb/testing-integration).

Агент webhook-ті локалды тексере алуы үшін оған сынақ ортасында ашық адрес керек. Продакшенде туннель адресі қабылданбайды, бірақ sandbox-та сынау үшін жарайды.

## Кілтті агентке беру қауіпсіздігі

ЖИ-агент — сіздің серверіңізде жұмыс істемейді. Ол сіз жазған мәтінді өзінің инфрақұрылымына жібереді, сөйлесу тарихын сақтауы мүмкін, ал кейбір құралдар кодты жария репозиторийге итеріп жібереді. Сондықтан:

| Ереже | Себебі |
|---|---|
| **Тек `qp_test_` кілтін беріңіз** | Sandbox-та нақты ақша жүрмейді, ең жаманы — қоқыс счёттар |
| **Live кілтті ешқашан бермеңіз** | Агент кездейсоқ цикл жасаса, нақты счёттар шығады және лимитіңіз бітеді |
| **Кілтті кодқа емес, env-ке саласыз** | Агент жазған код репозиторийге түссе, кілт онда болмайды |
| **Scope-ты шектеңіз** | `refunds:write` мен `subscriptions:manage` агентке керек емес |
| **Жұмыс біткен соң кілтті жойыңыз** | Кабинеттен бір басумен жойылады, ізі қалмайды |
| **Live кілтті өзіңіз қоясыз** | [Live-қа көшу](/kb/switch-to-live) — адамның жұмысы, агенттікі емес |

Кілт кездейсоқ сыртқа шығып кетсе, кешіктірмей жойыңыз: [API кілт сыртқа шығып кетті](/kb/leaked-key).

## Агент жазған кодты қабылдағанда не тексеру керек

Агент нәтиже берді дегеніңіз — дайын деген сөз емес. Осы бесеуін өзіңіз қарап шығыңыз:

1. **Кілт қайда тұр.** Кодта жазылып қалмаған ба, клиент жағындағы файлға түспеген бе
2. **Webhook қолтаңбасы тексеріле ме.** Дене өзгертілмеген байт күйінде тексерілуі керек, JSON-ға айналдырғаннан кейін емес
3. **Идемпоттылық бар ма.** Бір webhook екі рет келсе, тапсырыс екі рет жабылмауы керек
4. **Қателер өңделе ме.** 401, 403, 429 және тариф қателеріне не болады
5. **Кеш төлем ескерілген бе.** `cancelled` немесе `expired` счётқа `invoice.paid` `late: true` белгісімен келуі мүмкін

Толық тізім: [Интеграция қауіпсіздігі: чек-парақ](/kb/security-checklist).

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

**Қай агент жарайды?** Сілтемедегі құжаттаманы оқи алатын кез келгені: Claude Code, Cursor, басқа код жазатын агенттер. Талап біреу — интернеттен құжат оқи алуы керек.

**Агент бүкіл интеграцияны өзі бітіре ме?** Sandbox бөлігін — көбіне иә. Live-қа көшуді, кассир қосуды және тариф төлеуді адам істейді.

**Агент нақты ақшаны жоғалта ала ма?** `qp_test_` кілтімен — жоқ. Sandbox-та Kaspi мүлде шақырылмайды.

**Sandbox счёттары лимитке кіре ме?** Жоқ. Sandbox счёттары айлық лимитке кірмейді және сынақ мерзімін де бастамайды.

**Агентке кабинетке кіру керек пе?** Жоқ. Кілт пен құжаттама жетеді. Кабинет — адамға.