# Поручить интеграцию ИИ-агенту

> Claude, Cursor или другой ИИ-агент может написать интеграцию с Qut Pay сам. Что ему дать, как устроен автономный цикл в песочнице и почему боевой ключ агенту давать нельзя.

## Коротко

Интеграцию можно поручить ИИ-агенту. Дайте ему три вещи: **ссылки** — https://api.qut.kz/for-ai и https://api.qut.kz/llms.txt, **только ключ песочницы** (`qp_test_…`) и **чётко сформулированное задание**. В песочнице агент способен пройти полный цикл без участия человека: создать счёт → симулировать оплату через `simulate` → проверить, что пришёл вебхук. **Боевой ключ агенту не давайте.**

## Что дать агенту

### 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 | Руководство по самому этому подходу |

Не пишите агенту «знай API Qut Pay» — он его не знает. Дайте ссылку, он прочитает сам. С этими ссылками агент не выдумает названия полей, коды ошибок и формат вебхука.

### 2. Ключ песочницы

Кабинет → **Интеграции** → API-ключи → создаёте новый ключ. Условия:

- Режим **песочница**, ключ начинается с `qp_test_`
- Права только нужные: обычно `invoices:read`, `invoices:write`, при необходимости `webhooks:manage`
- Назовите понятно, например «ИИ-агент, песочница» — потом легче удалить

С таким ключом агент до реальных денег не доберётся: в песочнице Kaspi не вызывается вообще.

### 3. Само задание

Формулируйте конкретно, а не общими словами. В хорошем задании есть:

- По какому событию выставляется счёт (оформлен заказ, отправлена форма, по расписанию)
- Какой `kind` использовать: `qr` или `phone`
- Что передавать в `externalOrderId`
- На какой адрес должен приходить вебхук и что делать при его получении
- Как защититься от дублей: `Idempotency-Key` и идемпотентная обработка вебхука
- Что ключ читается из **переменной окружения**, а не пишется в код

Лучше списком, а не абзацем: список агент выполняет точнее.

## Автономный цикл в песочнице

Сила агента в том, что он может сам написать и сам проверить. В песочнице этот цикл проходит без человека:

1. **Создаёт счёт** — `POST /api/v1/invoices` с ключом `qp_test_`. Из ответа берёт `id` и `status`
2. **Симулирует оплату** — `POST /api/v1/invoices/{id}/simulate` с телом `{ "status": "paid" }`. Эндпоинт работает только в песочнице
3. **Проверяет вебхук** — дошло ли до его сервера событие `invoice.paid` и сходится ли подпись
4. **Подтверждает статус** — вернул ли `GET /api/v1/invoices/{id}` состояние `paid`
5. **Прогоняет негативные сценарии** — `cancelled`, `expired`, частичный возврат

Если все пять шагов проходят, интеграция действительно работает. Подробнее: [Симуляция оплаты в песочнице](/kb/ru/sandbox-simulate) и [Как протестировать интеграцию](/kb/ru/testing-integration).

Чтобы агент мог проверить вебхук, в тестовом окружении ему нужен доступный извне адрес. В продакшене адрес туннеля не принимается, но для проверки в песочнице он годится.

## Безопасность: почему ключ выдаётся ограниченный

ИИ-агент работает не на вашем сервере. Он отправляет ваш текст в свою инфраструктуру, может сохранять историю переписки, а часть инструментов пушит код в репозиторий. Отсюда правила:

| Правило | Причина |
|---|---|
| **Давайте только ключ `qp_test_`** | В песочнице реальных денег нет, худшее последствие — мусорные счета |
| **Боевой ключ не давайте никогда** | Зациклившийся агент выставит реальные счета и выжжет лимит |
| **Ключ кладётся в env, а не в код** | Если написанный агентом код попадёт в репозиторий, ключа там не будет |
| **Ограничьте права** | `refunds:write` и `subscriptions:manage` агенту не нужны |
| **Удалите ключ после работы** | Удаляется одним нажатием в кабинете, следов не остаётся |
| **Боевой ключ подставляете вы сами** | [Переход в боевой режим](/kb/ru/switch-to-live) — работа человека, не агента |

Если ключ всё-таки утёк, удалите его не откладывая: [API-ключ утёк](/kb/ru/leaked-key).

## Что проверить в коде, который написал агент

Готовый ответ агента — ещё не готовая интеграция. Пройдитесь по пяти пунктам сами:

1. **Где лежит ключ.** Не вписан ли в код, не попал ли в файл, который отдаётся браузеру
2. **Проверяется ли подпись вебхука.** Считать надо по неизменённому телу запроса, а не после разбора JSON
3. **Есть ли идемпотентность.** Один и тот же вебхук, пришедший дважды, не должен закрыть заказ дважды
4. **Обрабатываются ли ошибки.** Что происходит на 401, 403, 429 и ошибках тарифа
5. **Учтена ли поздняя оплата.** На `cancelled` или `expired` счёт может прийти `invoice.paid` с признаком `late: true`

Полный список: [Безопасность интеграции: чек-лист](/kb/ru/security-checklist).

## Вопросы и ответы

**Какой агент подойдёт?** Любой, который умеет читать документацию по ссылке: Claude Code, Cursor, другие кодовые агенты. Требование одно — доступ к чтению документов в интернете.

**Агент сделает всю интеграцию сам?** Часть про песочницу — чаще всего да. Переход в боевой режим, подключение кассира и оплату тарифа делает человек.

**Может агент потерять реальные деньги?** С ключом `qp_test_` — нет. В песочнице Kaspi не вызывается.

**Счета из песочницы считаются в лимит?** Нет. Они не входят в месячный лимит и не запускают пробный период.

**Нужен ли агенту доступ в кабинет?** Нет. Хватает ключа и документации. Кабинет — для человека.