Интеграция платного API руками нейросети: что дать агенту и где он сожжёт депозит

С бесплатным API ошибка агента стоит времени, с платным она списывает деньги с депозита. Поэтому агенту нужны на входе полная спецификация и явные правила, а его код проверяют на минимальной сумме до запуска.

#Бриф одним текстом вместо ссылки на сайт

Агент, которому дали адрес документации, может увидеть её лишь частично. Страницы обрезаются, часть текста подгружается скриптом, коды ошибок лежат на странице, до которой он не дошёл. Недостающее он додумывает, а додуманное поведение в платном API заканчивается двойными списаниями.

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

curl -s https://api.relayhub.surf/api/v1/vpn/llms.txt -o vpn-api-brief.md

#Ключ живёт в переменной окружения

Ключ тратит деньги с депозита. Промпт с ключом остаётся в истории переписки, в логах сервиса, а иногда и в репозитории, если агент вставит его в пример. Попросите агента читать ключ из переменной окружения и не печатать его в логи. Сам ключ впишите на сервере руками.

#Что вписать в задание

Явное правило агент выполняет точнее, чем выводит его из документации. Вставьте после брифа список требований. Пример для цифрового API:

1. Ключ API читать из переменной окружения HEX_API_KEY. Не писать его в код, логи и примеры.
2. custom_id генерировать один раз на заказ (UUID) и сохранять в базе до отправки запроса.
3. После таймаута и ответа 5xx повторять запрос с тем же custom_id и тем же телом.
4. На 429 ждать столько секунд, сколько указано в заголовке Retry-After.
5. Ответы 400, 401, 402 и 409 не повторять автоматически, записывать на разбор.
6. Статус опрашивать GET /order/{custom_id} до delivered, failed, cancelled или rejected,
   даже если вебхук настроен.
7. Суммы считать в целых полях *_nano, округлять один раз при выводе.
8. Подпись вебхука проверять по сырым байтам тела:
   "sha256=" + HMAC-SHA256(секрет, тело), сравнение через hmac.compare_digest.
9. Незнакомое событие вебхука и незнакомый error_code не считать ошибкой схемы.
10. Своего таймаута на доставку не ставить: у асинхронных товаров смотреть
    delivery_state и eta_seconds.

#Пять ошибок в коде агента, которые стоят денег

#Проверка на минимальной сумме

Баланс до и после смотрите через GET /balance. У VPN API повтор с тем же custom_id приходит с idempotent_replay: true, а событие для проверки обработчика отправляет POST /webhook/test. Каждую доставку с ответом вашего сервера видно в кабинете, в разделе «Доставки вебхуков».

#Для VPN-подписок: срок и повторные события

Подписка живёт после выдачи: продлевается, замораживается, меняет тариф. Попросите агента брать end_date из ответа API, а не считать от даты покупки: заморозка останавливает срок, и своя арифметика начнёт врать. Замороженную подписку API не продлевает и отвечает 409 subscription_frozen.

Одно событие VPN API может прийти повторно, поэтому дедуп идёт по event_id. Перед действием по событию обработчик перечитывает GET /subscriptions/{subscription_id}. Подробно про продления и события написано в статье про вебхуки VPN API.

#Чек-лист

• положить бриф API в контекст агента целиком
• читать ключ из переменной окружения
• вписать правила повторов и подписи в задание
• создавать custom_id до запроса, а не в цикле повторов
• проверить, что повтор того же запроса не меняет баланс
• проверить, что вебхук с чужой подписью отбивается