Модель данных и расчётов

Владелец данных

API-ключ однозначно определяет реселлера и окружение. Передача чужого provider_uuid, UUID клиента или другого Host не переключает контекст. UUID не является доказательством права доступа. Чужой объект обычно скрывается как отсутствующий; не интерпретируйте каждый 404 как удаление объекта в реестре.

Режим	Как организовать интеграцию
managed	Создавать отдельных клиентов и передавать их customer_uuid в клиентозависимых операциях. Контакты домена должны принадлежать тому же клиенту.
aggregate	Все услуги принадлежат клиенту, назначенному оператором для реселлера. Обычно customer_uuid опускается. Создание клиентов через API запрещено. Собственных конечных покупателей учитывать в своём биллинге.

Это режим учёта услуг, а не возможность выдать ключ конечному покупателю. Реселлер обязан проверять права своего пользователя до вызова API.

Идентификаторы

Поле	Назначение
customer_uuid	Клиент внутри платформы, не UUID учётной записи пользователя.
Contact uuid	Профиль доменного контакта. Это не EPP contact ID реестра.
Offering uuid	Предложение в каталоге. Не подставлять вместо UUID зоны.
Catalog resource_uuid	Ресурс предложения, например доменная зона; передаётся в quote.
Order uuid	Заказ, в том числе асинхронная регистрация.
service_uuid	Общая услуга биллинга.
Domain uuid, domain_uuid, domain_service_uuid	Идентификатор доменного объекта, используемый в /domains/{domainUuid} и в payload quote для продления. Не равен UUID общей услуги.
Operation uuid	Асинхронная операция управления, читается через /operations/{operationUuid}.
external_id	Идентификатор соответствующего объекта в вашем биллинге. Заказ и услуга имеют разные external_id.

Сохраняйте соответствия UUID, а не пытайтесь вычислить их из имени домена. external_id уникален в своей области объектов реселлера и окружения; он помогает восстановить связь, но не заменяет Idempotency-Key.

Клиенты, заказы и домены поддерживают поиск по external_id согласно справочнику. Не предполагайте такой фильтр у каждого списка: например, для контактов сохранение UUID обязательно. В managed список контактов требует customer_uuid.

Деньги и quote

Денежные поля с суффиксом _minor содержат целое число минимальных денежных единиц. Для KZT 125000 означает 1 250,00 тенге. Валюта передаётся отдельным кодом. Не рассчитывайте списания через float и не считайте, что у всех валют одинаковое число десятичных знаков.

Каталог определяет доступность предложения, операций и периодов. Финальная сумма операции берётся из POST /quotes, а не из устаревшего локального прайса. Quote привязан к реселлеру, окружению, ключу и клиенту; нельзя создавать его одним ключом, а использовать другим. Срок действия по умолчанию 15 минут, фактический срок смотрите в ответе. Quote одноразовый.

Суммы unit_price_minor, subtotal_minor и total_minor в публичном ответе quote являются розничными. Оптовая сумма резерва рассчитывается по правилам реселлера и может отличаться от total_minor; отдельная оптовая цена в этом ответе не возвращается. Финансовый результат сверяйте через закупочный баланс и ledger, не приравнивайте розничную сумму к оптовому списанию. Валюта всей котировки выбирается по первой строке items либо настройке реселлера: передавайте одинаковую валюту во всех строках.

Для регистрации используется operation: register, для продления renew, для переноса transfer, для восстановления restore. Восстановление имеет отдельную цену: нельзя подставлять цену продления, если тариф восстановления не настроен.

Реселлер с собственным биллингом использует согласованный с оператором checkout_mode: external. При платных live-операциях платформа резервирует средства оптового prepaid-баланса. Оплату вашего конечного покупателя и ваш розничный чек ведёт ваш биллинг. Подключение внешней платёжной системы этим API не производится.

Исход	Что делать в своём биллинге
Операция подтверждена	Зафиксировать оказание услуги; сверить сумму и итоговые данные.
Подтверждённый отказ или ошибка до отправки	Проверить отказ и освобождение резерва; отдельно применить свою политику возврата покупателю.
Неизвестный результат после отправки	Не создавать повторную покупку. Сохранить ожидание/ручную проверку: резерв может оставаться удержанным.

Ни 201, ни 202 не являются доказательством окончательного списания и оказания услуги. Баланс и ledger доступны только live. Не обещайте покупателю автоматический возврат на банковскую карту на основании ошибки регистрации: это отдельный процесс вашего биллинга.

Время, списки и состояния

Метки времени ответов содержат ISO 8601 со смещением часового пояса; nullable-поля могут быть null. Календарная дата profile.birth_date возвращается отдельно в формате YYYY-MM-DD, без времени и смещения. Сравнивайте моменты времени, а не строки. Часовой пояс клиента не меняет момент окончания регистрации.

Списки используют курсорную пагинацию. Передавайте полученный next_cursor как непрозрачную строку, сохраняя фильтры. Не используйте page=2 и не вычисляйте курсор самостоятельно. per_page по умолчанию 25, максимум 100; конкретная оболочка meta/links приведена у метода. Отсутствие следующего курсора завершает обход, но не гарантирует согласованный снимок при параллельных изменениях.

У домена раздельны состояние услуги, состояние регистрации и статусы реестра. Подтверждение личности не означает подтверждение образовательной лицензии. Перенос может долго оставаться pending. В локальной модели не сводите всё к одному флагу active.