Интеграция с помощью ИИ

Эту документацию удобно отдавать ИИ-ассистенту: ChatGPT, Claude, Cursor, GitHub Copilot и другим.

Документация для ИИ

Файл	Что внутри
https://avantpay.io/developers/llms-full.txt	Вся документация одним файлом в формате Markdown: поля, примеры, ошибки, уведомления, чеклист. Лучший вариант для ассистента.
https://avantpay.io/developers/llms.txt	Оглавление по стандарту llms.txt со ссылками на страницы и разделы справочника.
Страница + .md	Любая страница в формате Markdown. Например, https://avantpay.io/developers/api.md — справочник API.

Файлы собираются из страниц этого сайта при каждом обновлении документации, поэтому всегда совпадают с ним.

Если ассистент не умеет открывать ссылки, скачайте https://avantpay.io/developers/llms-full.txt и приложите файл к сообщению.

Готовое задание

Скопируйте текст, допишите в первой строке свой язык и фреймворк и отправьте ассистенту.

Подключи приём платежей AvantPay к моему проекту. Проект: <язык, фреймворк, где хранятся заказы>.

Документация: https://avantpay.io/developers/llms-full.txt. Прочитай её целиком до того, как писать код. Используй только методы, поля и значения из этой документации. Если чего-то в документации нет, не придумывай — спроси меня.

Что нужно сделать:
1. Создание платежа: POST https://api.avantpay.io/v3/payments, HTTP Basic (ID магазина и секретный ключ из переменных окружения AVANTPAY_SHOP_ID и AVANTPAY_SECRET_KEY). Поля: amount (value — строка с двумя знаками после точки, currency — RUB), capture = true (обязательно), confirmation (type = redirect, return_url — адрес страницы этого заказа), description, metadata.email — email покупателя (обязательно; покупатель из Telegram — <id или username>@telegram.org), metadata.order_id — номер заказа. Не передавай receipt и другие поля, которых нет в разделе «Создать платёж» справочника.
2. Ключ идемпотентности (заголовок Idempotence-Key): новый UUID на каждую попытку оплаты. Сохрани его в заказе до запроса. При таймауте, ответе 500, 429 или 202 повтори запрос с тем же ключом и тем же телом: 1–2 минуты, потом покажи покупателю «Платёж создаётся» и продолжай в фоне с тем же ключом, но не дольше 24 часов. Сохрани id платежа из ответа в заказе.
3. Перенаправление покупателя на confirmation.confirmation_url — только если status = pending и ссылка есть. Если повтор с тем же ключом вернул status = canceled, платёж не создался до конца: создай новый платёж с новым ключом.
4. Обработчик уведомлений (POST на мой адрес): проверь подпись из заголовков Signature и Signature-Timestamp по строке «<Signature-Timestamp>.<сырое тело запроса>» и отклони уведомление старше 5 минут; на незнакомый event ответь 200 и ничего не делай; запроси платёж GET https://api.avantpay.io/v3/payments/{id} и решай по ответу API; на ответ 404 и на платёж, которого нет в моих заказах (например, счёт из личного кабинета), ответь 200 и ничего не делай; при status = succeeded сверь amount.value и amount.currency с суммой заказа и отметь заказ оплаченным атомарно (условный UPDATE … WHERE paid_payment_id IS NULL или блокировка строки), потом выполни заказ ровно один раз; ответь 200 не позже чем через 10 секунд; если не удалось обработать — ответь 500.
5. Страница возврата (return_url): AvantPay открывает её без параметров. Найди заказ по адресу страницы, возьми из заказа id платежа, запроси платёж GET https://api.avantpay.io/v3/payments/{id} и покажи покупателю результат по status. Если выполняешь заказ и здесь — той же атомарной функцией, что и обработчик уведомлений: возврат покупателя и уведомление приходят одновременно.
6. Сверка по расписанию: раз в несколько минут запрашивай GET https://api.avantpay.io/v3/payments?status=succeeded&captured_at.gte=<время прошлой сверки минус 10 минут> по всем страницам и обрабатывай каждый платёж тем же кодом, что и уведомление. Уведомление может не дойти.
7. Учти: статус canceled может смениться на succeeded; одно уведомление может прийти несколько раз и не по порядку; незнакомые поля в ответах не должны ломать код; повторная оплата того же заказа — новый платёж с новым ключом идемпотентности; если сумма заказа изменилась после создания платежа, создай новый платёж с новым ключом, а платёж на старую сумму не засчитывай.
8. Запросы к API — только с сервера. Секретный ключ не должен попасть в браузер, мобильное приложение, логи или репозиторий.

В конце перечисли, что я должен настроить в личном кабинете AvantPay (адрес уведомлений — до первого платежа), и как проверить интеграцию по разделу «Проверка интеграции» документации.

Что проверить в коде от ассистента

Пройдите чеклист перед запуском. Чаще всего ассистенты ошибаются так:

• не передают email покупателя в metadata.email — платёж не создаётся, ошибка 400;
• не передают "capture": true;
• передают receipt — чеки AvantPay не отправляет, запрос получит ошибку 400;
• выполняют заказ, когда покупатель вернулся на return_url, без проверки статуса;
• не сверяют amount платежа с суммой заказа: после смены корзины заказ выполняется по старому платежу на меньшую сумму;
• проверяют «заказ не выполнен», а потом выполняют его без атомарной отметки: уведомление и возврат покупателя выполняют заказ дважды;
• выполняют заказ только по уведомлению, без сверки по расписанию;
• отвечают 500 на уведомление о платеже, которого нет в заказах, или на ответ 404 — уведомление повторяется сутки;
• ждут на странице возврата параметр с id платежа — его там нет;
• создают новый ключ идемпотентности при каждом повторе запроса;
• передают сумму числом (100) вместо строки ("100.00");
• считают подпись только по телу, без Signature-Timestamp;
• считают canceled окончательным статусом;
• выполняют заказ повторно на повторное уведомление.