Интеграция с агентом

Интеграции всё чаще пишет разработчик вместе с агентом. Проблема в том, что агент без источника додумывает: выдумывает несуществующие поля, путает копейки с сумами, забывает про идемпотентность. Ошибка при этом выглядит уверенно, и находится она уже на боевых деньгах.

Поэтому мы отдаём документацию в машиночитаемом виде. Дайте агенту ссылки ниже — дальше он будет отвечать фактами из неё, а не догадками.

https://docs.assalam.uz/llms.txt
    карта документации и главные правила

https://docs.assalam.uz/llms-full.txt
    вся документация одним текстом

https://api.assalam.uz/api-docs-json
    спецификация OpenAPI — точные поля

https://api.assalam.uz/api-docs
    интерактивный справочник для человека

Прочитай https://docs.assalam.uz/llms-full.txt
и напиши на нашем стеке приём платежей
через Assalam. Мы продаём товары, значит
поверхность Checkout: заказ и ссылка
на оплату, карт мы не касаемся.

Соблюдай правила из раздела «Обязательно
знать»: суммы в тийинах целыми, ключ
идемпотентности от номера заказа, номер
карты на наш сервер не отправлять.
Возврата на карту у платформы нет —
не закладывай его в сценарий.

Что в каком файле

llms.txt — короткая карта: о чём платформа, какие есть разделы и правила, которые ломают интеграцию молча. Годится, когда агент сам решает, что читать дальше.

llms-full.txt — вся документация одним текстом: порядок работы, примеры запросов, обработка вебхуков с проверкой подписи, тестовые сценарии, формат ошибок. Годится, когда нужно дать всё сразу, за одно обращение.

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

api-docs-json — спецификация OpenAPI. Это источник истины по полям: текст мы пишем руками и он может отстать, спецификация порождается из самого кода. По ней же генерируются клиенты.

MCP

Своего MCP-сервера мы пока не предлагаем. Если ваш агент работает через MCP, подключите спецификацию OpenAPI любым мостом OpenAPI→MCP — она порождается из кода и всегда актуальна, в отличие от отдельного сервера, который пришлось бы поддерживать вручную.

Правила из llms.txt при этом стоит положить агенту в системную подсказку: спецификация описывает поля, но не объясняет, почему ключ идемпотентности должен быть производным от номера заказа.

Нужен именно MCP-сервер — напишите нам. Мы не строим его наугад, пока никто не попросил: неподдерживаемый сервер хуже его отсутствия.

Что перепроверить за агентом

Даже с документацией стоит просмотреть четыре места — на них агенты ошибаются чаще всего, и все четыре ошибки тихие: код работает, а деньги ведут себя неправильно.

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

amount: 50000.50     ✗ дробная сумма
amount: 5000050      ✓ тийины целым числом

Idempotency-Key: uuid-v4-каждый-раз   ✗
Idempotency-Key: order-1024           ✓

{"livemode": true}   ✗ поля нет
sk_live_...          ✓ режим задаёт ключ

pan на ваш сервер    ✗ PCI-контур
card_sessions        ✓ номер к нам напрямую

if (err.message === '...')  ✗ текст меняем
if (err.error.code === ...) ✓ коды не меняем

Дальше по теме