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

Коротко

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

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

1. Ссылки

Не пишите агенту «знай 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, частичный возврат

Если все пять шагов проходят, интеграция действительно работает. Подробнее: Симуляция оплаты в песочнице и Как протестировать интеграцию.

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

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

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

Если ключ всё-таки утёк, удалите его не откладывая: API-ключ утёк.

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

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

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

Полный список: Безопасность интеграции: чек-лист.

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

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

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

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

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

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