# Домени й DNS через API — приклади

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

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

Усі приклади — з ключем-заглушкою `zr_live_...`. Підставте свій ключ із [кабінету](https://vse.zrazu.com/team/api-keys/). Загальні правила (вхід, повтор, помилки, ліміти) — в [огляді API](https://zrazu.com/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/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` секунд.