# API ZRAZU — обзор для разработчиков

> Базовый адрес, вход по ключу, идемпотентность, формат ошибок и лимиты API ZRAZU — для своих скриптов, интеграций и ИИ-агентов.

URL: https://zrazu.com/ru/docs/api-overview/

API ZRAZU даёт скриптам и программам то, что вы делаете в кабинете: прочитать список доменов, зоны DNS и сертификаты, поставить домен на мониторинг. Работает по ключу, который вы выпускаете сами.

Отдельно есть [MCP для ИИ-агентов](https://zrazu.com/ru/docs/api-mcp.md): он открытый, без ключа, но только читает и показывает паспорт публичного домена.

## Что умеет API по ключу

Базовый адрес: `https://api.zrazu.com/v1`.

| Группа | Что можно |
| --- | --- |
| Ключ | `GET /v1/api-keys/current` — какие права, домены и срок у этого ключа |
| Домены | `GET /v1/domains` — список доменов организации со сроком, автопродлением и замками |
| Мониторинг | `GET /v1/monitoring`, `POST /v1/monitoring`, `DELETE /v1/monitoring/{name}` — читать, ставить и снимать имена |
| DNS | `GET /v1/dns/zones`, `GET /v1/dns/zones/{name}`; изменение записей и новые зоны — см. [домены и DNS через API](https://zrazu.com/ru/docs/api-domains-dns.md) |
| SSL | `GET /v1/ssl/catalog`, `GET /v1/ssl/certificates`, файлы сертификата, заказ и перевыпуск |
| Баланс | `GET /v1/balance` — баланс организации |

Что доступно именно вашему ключу, зависит от его прав: см. [ключи API](https://zrazu.com/ru/docs/api-keys.md).

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

## Вход по ключу

Ключ передают только в заголовке:

```sh
curl -H "Authorization: Bearer zr_live_..." https://api.zrazu.com/v1/api-keys/current
```

Ключ в адресе запроса (`?key=…`) отклоняется: адреса попадают в журналы серверов и браузеров. Ключ начинается с `zr_live_`. Ключ, вставленный в код страницы сайта, не сработает: API не принимает запросы со страниц чужих сайтов в браузере, и это намеренно.

## Безопасный повтор изменений

Каждый запрос, который что-то меняет (`POST`, `PUT`, `DELETE`), требует заголовка `Idempotency-Key` — произвольная строка до 120 символов, например UUID.

```sh
curl -X POST https://api.zrazu.com/v1/monitoring \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: 6f1d8c0e-5b2a-4c1f-9a3e-0d7b2e4a1c11" \
  -H "Content-Type: application/json" \
  -d '{"names": ["example.com.ua"]}'
```

- Повторный запрос с тем же ключом в течение 24 часов вернёт первый ответ с заголовком `Idempotent-Replayed: true` — второе изменение не выполняется.
- Тот же `Idempotency-Key` с другим телом запроса — ошибка `422`.
- Если первый запрос ещё выполняется, повтор получит `409` — попробуйте через мгновение.

Если ключ выпущен с отметкой «Изменения — только с моим подтверждением», изменение не выполняется сразу: API отвечает `202` и `plan_id`, а человек подтверждает план в кабинете в разделе «Планы».

## Формат ответов и ошибок

Списки отдаются страницами: `{"data": [...], "next": "…"}`. Чтобы получить следующую страницу, передайте `next` как параметр `after`; `limit` — до 500, по умолчанию 100.

Ошибка всегда одной формы:

```json
{ "error": { "code": "right_missing", "message": { "uk": "…", "en": "…" } } }
```

`code` стабилен — на него можно опираться в коде; текст в `message` может меняться.

| Код | HTTP | Что значит |
| --- | --- | --- |
| `key_required` | 401 | нет заголовка `Authorization: Bearer zr_…` |
| `key_invalid` | 401 | это не ключ ZRAZU или в нём ошибка |
| `key_unknown` | 401 | ключ не найден |
| `key_revoked`, `key_expired`, `key_idle` | 401 | ключ отозван, срок истёк или его не вызывали 90 дней |
| `key_in_query` | 400 | ключ передан в адресе запроса |
| `ip_not_allowed` | 403 | ключ не работает с этого IP-адреса |
| `right_missing` | 403 | у ключа нет нужного права |
| `out_of_scope` | 403 | имя вне доменов ключа |
| `not_found` | 404 | зона или сертификат не найдены |
| `idempotency_key_required` | 400 | нет заголовка `Idempotency-Key` |
| `idempotency_key_reused` | 422 | `Idempotency-Key` уже использован с другим запросом |
| `rate_limited` | 429 | слишком много вызовов; заголовок `Retry-After` — через сколько секунд повторить |

## Лимиты

| Что | Лимит |
| --- | --- |
| Один ключ | 120 вызовов в минуту и в 25 раз больше за час |
| Один IP-адрес | 240 вызовов в минуту |
| Изменяющие вызовы организации | 1000 в сутки — все ключи вместе |

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

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

- **`401 key_required`.** Добавьте заголовок `Authorization: Bearer zr_live_…` — именно `Bearer` и пробел перед ключом.
- **`401 key_unknown` или `key_invalid`.** Проверьте, что ключ скопирован полностью, без пробела в конце. Если ключ потеряли, выпустите новый: показать старый нельзя.
- **`403 right_missing`.** У ключа нет нужного права. Откройте `GET /v1/api-keys/current`, посмотрите `permissions`, при необходимости выпустите новый ключ с нужным правом.
- **`403 ip_not_allowed`.** Для ключа задан список IP-адресов, а запрос пришёл с другого. Добавьте адрес в кабинете или выпустите новый ключ.
- **`429 rate_limited`.** Уменьшите частоту запросов и соблюдайте `Retry-After`.
- **`400 idempotency_key_required`.** Добавьте заголовок `Idempotency-Key` к запросу, который меняет данные.

Цены на услуги — на [странице цен](https://zrazu.com/prices/).