# Домены и DNS через API — примеры

> Примеры запросов к API ZRAZU: список доменов, мониторинг, чтение зоны DNS, изменение записей, новая зона и проверка делегирования.

URL: https://zrazu.com/ru/docs/api-domains-dns/

Во всех примерах ключ-заглушка `zr_live_...`. Подставьте свой ключ из [кабинета](https://vse.zrazu.com/team/api-keys/). Общие правила (вход, повтор, ошибки, лимиты) — в [обзоре API](https://zrazu.com/ru/docs/api-overview.md).

## Список доменов

Нужно право `domain.read`.

```sh
curl -H "Authorization: Bearer zr_live_..." "https://api.zrazu.com/v1/domains?limit=100"
```

В ответе для каждого домена: `name`, `expires_at`, `autorenew`, `transfer_lock`, `contact_lock`, `frozen`. Если страниц больше, передайте `next` из ответа как `after`.

## Мониторинг

Права `monitor.read` и `monitor.edit`.

```sh
# состояние мониторинга
curl -H "Authorization: Bearer zr_live_..." https://api.zrazu.com/v1/monitoring

# поставить под наблюдение до 100 имён за вызов
curl -X POST https://api.zrazu.com/v1/monitoring \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"names": ["example.com.ua", "example.net"]}'

# снять с наблюдения
curl -X DELETE https://api.zrazu.com/v1/monitoring/example.net \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: $(uuidgen)"
```

В ответе на добавление поле `skipped` перечисляет строки, которые не удалось принять, с причиной: опечатка не пропадает молча.

## Прочитать зону DNS

Нужно право `dns.read`.

```sh
# список зон
curl -H "Authorization: Bearer zr_live_..." https://api.zrazu.com/v1/dns/zones

# записи одной зоны
curl -H "Authorization: Bearer zr_live_..." https://api.zrazu.com/v1/dns/zones/example.com.ua
```

Ответ на второй запрос:

```json
{
  "name": "example.com.ua",
  "serial": 12,
  "records": [
    { "name": "@", "type": "A", "ttl": 300, "content": "203.0.113.10", "prio": null },
    { "name": "www", "type": "CNAME", "ttl": 300, "content": "example.com.ua.", "prio": null }
  ]
}
```

Имена записей — относительно зоны: `@` для самой зоны, `www` для `www.example.com.ua`. `serial` понадобится для изменения.

## Изменить записи зоны

Нужно право `dns.edit`. Порядок: прочитали зону, изменили список, отправили его целиком вместе с `base_serial` — номером, который вы прочитали.

```sh
curl -X PUT https://api.zrazu.com/v1/dns/zones/example.com.ua \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "base_serial": 12,
    "summary": "новый сервер сайта",
    "records": [
      { "name": "@", "type": "A", "ttl": 300, "content": "203.0.113.20" },
      { "name": "www", "type": "CNAME", "ttl": 300, "content": "example.com.ua." }
    ]
  }'
```

- В списке должны быть **все** записи зоны, а не только изменённые: что не отправлено, будет удалено.
- Записей в зоне — до 500.
- Если зону изменили между вашим чтением и записью, ответ `409`: прочитайте зону снова и повторите.
- Перед записью зона проверяется так же, как в кабинете: ошибка в записи — `409` без изменений, предупреждения возвращаются в поле `warnings`.
- После изменения владельцам и администраторам приходит письмо, а изменение остаётся в истории зоны с названием ключа. Не более 60 изменений в час на ключ.

## Новая зона и проверка делегирования

Нужно право `dns.zone_create` — только для ключа на все зоны организации.

```sh
curl -X POST https://api.zrazu.com/v1/dns/zones \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com.ua", "import_current": true}'
```

- Для домена, зарегистрированного в ZRAZU, зона включается на наших серверах имён. С `import_current: true` записи, которые сейчас отвечают у прежнего провайдера, переносятся.
- Для домена у другого регистратора создаётся заявка. Укажите у регистратора серверы имён из ответа, затем запустите проверку:

```sh
curl -X POST https://api.zrazu.com/v1/dns/zones/example.com.ua/verify \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: $(uuidgen)"
```

Ответ `202` означает, что проверка запущена. Запросите `GET /v1/dns/zones` позже, чтобы увидеть статус.

## Если не получилось

- **`403 right_missing`.** У ключа нет нужного права — см. [ключи API](https://zrazu.com/ru/docs/api-keys.md).
- **`403 out_of_scope`.** Домен вне списка доменов ключа.
- **`404 not_found`.** Зоны нет, она не ваша или не входит в домены ключа — ответ одинаковый.
- **`409` при `PUT`.** Зону изменили после вашего чтения или запись содержит ошибку. Прочитайте зону снова и повторите с новым `base_serial`.
- **`503 dns_closed`.** DNS ZRAZU временно не принимает изменений; повторите позже.
- **`409 zone_exists`.** Зона для этого домена уже создана.
- **`429`.** Слишком много изменений: подождите `Retry-After` секунд.