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

Этот сценарий предназначен для server-to-server интеграции с собственным биллингом и внешними расчётами. В каждом примере JSON замените UUID результатами предыдущих шагов. Для каждого нового POST нужен отдельный Idempotency-Key; при сетевом повторе того же шага ключ и тело сохраняются.

Общие заголовки: Authorization: Bearer <credential>, Accept: application/json, Content-Type: application/json. Подробные ответы каждого шага представлены в справочнике методов. Исполняемый пример сохраняет промежуточный прогресс.

1. Выбрать зону

Вызовите GET /catalog/domain-zones. Выберите разрешённое предложение и проверьте allowed_operations, allowed_periods и ограничения зоны. В quote используется resource_uuid зоны, а не uuid предложения. Перед live-покупкой перечитывайте каталог и цену: вчерашний тариф не является основанием для списания.

2. Создать клиента в managed

POST /customers:

{
  "external_id": "customer-1001",
  "type": "individual",
  "display_name": "Ivan Petrov",
  "email": "owner@example.net",
  "first_name": "Ivan",
  "last_name": "Petrov",
  "preferred_currency": "KZT",
  "locale": "ru",
  "timezone": "Asia/Almaty"
}

Сохраните data.uuid как customer_uuid. Перед повторным созданием после утраты локального состояния выполните GET /customers?external_id=customer-1001. Не создавайте новый external_id для того же клиента из-за таймаута.

Для компании применяется type: legal с реквизитами юридического лица согласно схеме. Тип клиента и тип доменного контакта имеют разные названия: individual/legal у клиента, person/organization у контакта. В aggregate этот шаг пропускается; не отправляйте произвольный UUID покупателя.

3. Создать контакт

POST /contacts:

{
  "customer_uuid": "11111111-1111-4111-8111-111111111111",
  "external_id": "contact-1001",
  "type": "person",
  "first_name": "Ivan",
  "last_name": "Petrov",
  "middle_name": "Ivanovich",
  "email": "owner@example.net",
  "phone": "+77010000000",
  "country_code": "KZ",
  "residence_country_code": "KZ",
  "city": "Almaty",
  "address_line": "Example street 1",
  "postal_code": "050000"
}

В aggregate опустите customer_uuid. Сохраните data.uuid. Контакт из этого примера показывает структуру, но не гарантирует пригодность для каждой зоны: NIC.KZ может требовать ИИН/БИН и документы. Используйте реальные законно полученные данные владельца либо согласованные sandbox-данные. Не выдумывайте идентификатор с подходящей длиной: проверяются формат, контрольная сумма и требования зоны.

Для организации укажите type: organization и organization_name; идентификатор передаётся парой external_id_type и external_id_value. Это идентификатор документа, а external_id выше является ключом объекта вашего биллинга. Требования .edu.kz, включая тип документа и образовательную лицензию, проверяются отдельно от создания контакта.

Один контакт можно назначить всем четырём ролям, когда это соответствует реальным полномочиям. Контакты должны находиться в том же клиенте, реселлере и окружении. API не требует вручную создавать EPP contact ID.

4. Проверить доступность

POST /domains/check:

{"domain":"example.kz"}

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

5. Зафиксировать цену

POST /quotes:

{
  "customer_uuid": "11111111-1111-4111-8111-111111111111",
  "items": [
    {
      "resource_type": "domain_zone",
      "resource_uuid": "22222222-2222-4222-8222-222222222222",
      "operation": "register",
      "period_unit": "year",
      "period_count": 1,
      "quantity": 1,
      "currency": "KZT",
      "payload": {
        "domain_name": "example.kz",
        "external_id": "domain-1001",
        "contact_uuids": {
          "owner": "33333333-3333-4333-8333-333333333333",
          "admin": "33333333-3333-4333-8333-333333333333",
          "tech": "33333333-3333-4333-8333-333333333333",
          "billing": "33333333-3333-4333-8333-333333333333"
        },
        "nameservers": [
          {"hostname":"ns1.example.net"},
          {"hostname":"ns2.example.net"}
        ]
      }
    }
  ]
}

Сохраните UUID quote, срок действия, валюту и суммы. В aggregate опустите customer_uuid. Проверьте сумму перед подтверждением покупки. Входящие параметры quote описывают будущую услугу; они не являются свободным хранилищем ваших данных.

Если quote истёк до создания заказа, получите новую цену и повторно согласуйте её при необходимости. Если отправка заказа уже произошла и её исход неизвестен, не создавайте новый quote и заказ до сверки.

6. Создать заказ

POST /domains (алиас доменной регистрации через создание заказа):

{
  "quote_uuid": "44444444-4444-4444-8444-444444444444",
  "customer_uuid": "11111111-1111-4111-8111-111111111111",
  "external_id": "order-1001"
}

Ответ 201 содержит Order, а не Domain или Operation. Сохраните data.uuid, data.items[].service_uuid, data.items[].service_external_id и data.invoice, если он не null. В aggregate опустите customer_uuid. order-1001 относится к заказу, domain-1001 из quote относится к будущей услуге.

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

7. Дождаться результата

Читайте GET /orders/{orderUuid} и GET /domains?external_id=domain-1001; используйте backoff и webhooks. Начальная регистрация не является задачей /operations: этот раздел предназначен для последующих операций управления.

После появления Domain сохраните его uuid отдельно от service_uuid. Проверьте registration_status, registrar_operation_status, registered_at, expires_at и статусы реестра. Оплаченный заказ не доказывает отсутствие serverHold или успешную проверку лицензии.

Ситуация	Действие
Заказ принят, регистрация ещё выполняется	Оставить локальный заказ в обработке, продолжать сверку.
Регистрация подтверждена	Сохранить реальные даты и контакты; показать результат покупателю.
Подтверждён отказ, например имя занято	Сохранить причину, сверить финансовый результат и применить свою политику возврата.
Таймаут HTTP	Повторить только исходный запрос с прежним ключом и байтами либо восстановить заказ по external_id.
Неизвестен результат EPP	Не создавать новый заказ. Передать UUID заказа/домена и request ID поддержке.
Домен зарегистрирован, но требуется ЭЦП	Выполнить отдельный поток подтверждения владельца.

Автоматическая сверка неизвестного результата не означает автоматическую повторную отправку регистрации. При неизвестном исходе средства могут оставаться в резерве до подтверждения.