Требования к интеграции

Этот документ можно использовать как задание разработчику или ИИ вместе с OpenAPI, полным текстом и примерами. Генерация клиента по схеме не реализует автоматически финансовую логику, согласие владельца, обработку неизвестного результата или защиту секретов.

Входные данные задания

До реализации зафиксируйте URL и релиз API, режим клиентов, окружение, валюты, разрешённые зоны, scopes, исходящие IP, webhook URL, правила вашего розничного биллинга и место хранения ключей. Отсутствующие значения запрашиваются у оператора; их нельзя угадывать по примерам.

Источником HTTP-контракта является OpenAPI этого релиза. Руководства определяют порядок операций и ограничения, которые не выражаются JSON Schema. При противоречии остановите выпуск интеграции и уточните контракт, а не выбирайте случайный вариант.

Загрузка документации в ИИ

Начните с индекса llms.txt, затем загрузите руководства нужного сценария, OpenAPI и Markdown-страницы задействованных методов по ссылкам индекса. Такой порядок даёт модели сначала процесс и ограничения, затем точные поля запросов и ответов. llms-full.txt содержит полный материал, но может превышать контекст модели: используйте поиск и загрузку фрагментов по HTTP-методу и пути, добавляя общие правила авторизации, ошибок, идемпотентности и пагинации.

Не передавайте модели настоящие bearer-ключи, auth code, секреты восстановления или webhook, ЭЦП и персональные данные клиентов. Используйте синтетические примеры. Документация не гарантирует, что любая модель автоматически создаст правильную интеграцию: сгенерированный код требует проверки разработчиком и прохождения приёмочных сценариев ниже.

Локальная модель

Храните соответствия собственных ID с customer_uuid, contact UUID, order UUID, service_uuid, domain UUID и operation UUID, разделённые по реселлеру и окружению. Для каждого намерения изменения сохраняйте до отправки:

• собственный неизменяемый ID намерения и бизнес-основание;
• HTTP-метод, путь с query, точные байты JSON и Idempotency-Key;
• состояние отправки, число попыток, время следующей проверки;
• принятые UUID, HTTP-статус и X-Request-ID без секретов;
• подтверждённый результат либо отметку неопределённости.

Защитите уникальным ограничением одновременное создание двух намерений для одной покупки. После сбоя процесса возобновляйте сохранённое намерение, а не конструируйте новую покупку из формы пользователя. Webhook inbox также должен иметь уникальный ключ события.

Обязательное поведение

1. Проверять права пользователя собственного биллинга до выбора UUID и вызова API.
2. Отправлять ключ только на фиксированный доверенный API origin; запретить следование redirect с авторизацией.
3. Не смешивать test и live, не переносить между ними UUID и quotes.
4. Использовать суммы quote в целых minor units; показывать согласованную цену до платной операции.
5. Разделять создание заказа регистрации и последующие асинхронные операции управления.
6. Сохранять идемпотентный ключ и тело до первого сетевого вызова; не менять их при timeout/5xx.
7. Ограничивать повторы и частоту polling; учитывать Retry-After, общий бюджет ключа и jitter.
8. Не считать 201/202 завершением; сверять фактические даты и состояние после результата.
9. Для uncertain не создавать вторую команду и не возвращать деньги автоматически без финансовой сверки.
10. Проверять подпись webhook по исходным байтам, фиксировать событие надёжно до 2xx, терпеть повторы и перестановку событий.
11. Дополнять webhooks периодическим чтением: уведомление не является единственным источником состояния.
12. Не логировать Bearer, подписи, auth code, restore secret и персональные поля контактов.

Приёмочные сценарии

Проверка	Ожидаемый результат
Неверный/отозванный ключ	Контролируемая ошибка; бесконечные повторы отсутствуют.
Ключ другого реселлера или окружения	Нет доступа к чужим клиентам, услугам и операциям.
Недостаточный scope и запрещённый IP	Отказ виден оператору интеграции, не выдаётся за отсутствие домена в реестре.
Managed и aggregate	Верное создание/выбор клиента без смешения владения.
Пагинация более одной страницы	Все UUID обработаны, курсор и фильтры сохранены, дубликаты безопасны.
Истёкший quote до покупки	Новая цена согласована до нового заказа.
Недостаточный баланс	Нет ложного успешного заказа и повторного розничного списания.
Имя заняли после проверки	Отказ регистрации обработан отдельно от оплаты.
HTTP timeout после принятия запроса	Повтор прежнего намерения не создаёт вторую услугу/операцию.
Одинаковый ключ, иное тело	409 обрабатывается как конфликт, ключ автоматически не заменяется.
Перезапуск процесса между отправкой и сохранением ответа	Сохранённые ключ/тело восстанавливают тот же запрос.
429	Учитывается пауза; все workers с этим ключом не создают повторный всплеск.
Ответ HTML/502 от proxy	Сохраняется техническая ошибка без попытки трактовать её как Domain.
EPP выполнил команду, ответ потерян	uncertain не превращается в повторную платную команду.
Продление до 24 часов / сверх 10 лет	Запрет показан до покупки; серверный отказ также обработан.
Успешное продление	Итоговый expires_at берётся из платформы, не локально прибавленным годом.
Перенос pending/отказ/отмена	Сохраняются различимые состояния, резерв и услуга сверяются.
Подмена webhook, повтор, неверный timestamp	Подмена отклоняется; разрешённый повтор не дублирует бизнес-эффект.
События пришли не по порядку	Позднее старое событие не откатывает подтверждённое состояние; выполняется GET-сверка.
Отказ автопродления	Создано уведомление ответственному, обещание продления покупателю не выдано.
Неизвестный enum/код/дополнительное поле	Клиент не падает и не признаёт неизвестную операцию успешной.

Прогоняйте платные и изменяющие сценарии в sandbox с разрешёнными тестовыми данными. Для live сначала согласуйте ограниченную контрольную операцию с оператором и владельцем домена. Отчёт о прохождении должен содержать окружение, релиз и request/operation ID без секретов.

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

Не добавляйте вымышленные endpoints оплаты, отмены любой операции, управления DNS-записями, DNSSEC, редактирования чужого клиента или мгновенного возврата через платёжный шлюз. Не используйте POST повторно новым ключом только потому, что GET ещё не показывает изменение. Не считайте одинаковый domain name достаточной связью между test/live.

Для обращения в поддержку передавайте время UTC, endpoint, HTTP-статус, машинный код, request ID, order/domain/operation UUID и описание ожидаемого результата. Данные подписи, секреты и полный профиль владельца в диагностический пакет не включаются.