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

HTTPS API для ваших программ: записи DNS (certbot и другие клиенты Let’s Encrypt, системы развёртывания, свои скрипты), раздел «Домены» — сроки, серверы имён, автопродление, проверка свободных доменов — и покупки с баланса: регистрация и продление доменов. Ответы — JSON.

Ключ доступа

Ключ создаётся в кабинете, в разделе «API-ключи». Ключ привязывается к выбранным доменам или ко всем доменам аккаунта, включая будущие, и даёт права в трёх разделах — DNS, «Домены» и покупки. Настройки ключа можно изменить в кабинете в любой момент — сам ключ при этом не меняется.

• «Только проверка SSL» — ключ видит, ставит и снимает только записи TXT с именем _acme-challenge: на самом домене (_acme-challenge или _acme-challenge.example.com — это одна запись) и на поддоменах (_acme-challenge.www). Остальных записей зоны ключ не видит и менять не может. Для certbot достаточно его.
• «Чтение DNS» — читать все записи, ничего не меняя.
• «Управление DNS» — читать, добавлять и удалять любые записи.
• «Домены: чтение» — список доменов, сроки, серверы имён и автопродление; проверка, свободен ли домен, и его цена.
• «Домены: управление» — то же, плюс смена серверов имён и включение и выключение автопродления.
• «Покупки: продление» — продлевать домены ключа с баланса аккаунта.
• «Покупки: регистрация и продление» — регистрировать новые домены и продлевать домены ключа с баланса.

«Полный доступ» в кабинете — это управление DNS и управление доменами сразу. Покупки к нему не относятся: право тратить деньги включается отдельно, с лимитами по желанию.

Ключ передаётся в заголовке Authorization: Bearer <ключ>. Ключ показывается один раз при создании; потерянный или засвеченный ключ перевыпустите в кабинете (кнопка «Перевыпустить»: новое значение, прежние права) или удалите.

curl -H "Authorization: Bearer rz_…" https://regzone.pro/api/v1/zones

HTTP/1.1 200 OK
{"scope":"acme","zones":[{"name":"example.com","status":"active"}]}

Ответ: scope — доступ ключа к DNS (acme, dns_read, dns_write или null, если у ключа его нет); zones — домены, доступные ключу, по алфавиту: name — имя домена (кириллические — в punycode), status — его состояние (active, pending, expired и др.). Записи можно менять только у домена со статусом active, у остальных ответ 409. Других полей в ответе нет.

Проверка ключа

curl -H "Authorization: Bearer rz_…" https://regzone.pro/api/v1/key

{"key":{"name":"certbot","scope":"acme","domainsAccess":null,"purchases":null,"allDomains":false,"domains":["example.com"],"allowedIps":["203.0.113.7"],"expiresAt":null}}

Запрос ничего не меняет и не требует ни одного права — так проверяют, что ключ вписан верно и что он может. scope, domainsAccess и purchases — права ключа (null — права нет); domains — домены, которых он касается; allDomains — ключ работает со всеми доменами аккаунта, включая будущие; allowedIps — адреса, с которых он работает (пусто — с любого); expiresAt — конец срока (ISO 8601) или null у бессрочного.

Адреса

Базовый адрес: https://regzone.pro/api/v1

Добавить запись

Тело: type, name, value, ttl (необязательно; по умолчанию 60 для _acme-challenge и 3600 для остальных), priority (обязательно для MX и SRV).

curl -X POST https://regzone.pro/api/v1/zones/example.com/records \
  -H "Authorization: Bearer rz_…" \
  -H "Content-Type: application/json" \
  -d '{"type":"TXT","name":"_acme-challenge","value":"<token>","ttl":60}'

HTTP/1.1 201 Created
{"record":{"id":"4Zt2…","type":"TXT","name":"_acme-challenge","value":"<token>","ttl":60,"priority":null},"created":true}

• name — относительное имя (_acme-challenge, www, @ для самого домена) или полное (_acme-challenge.example.com).
• Повторный запрос с той же записью не создаёт копию: ответ 200 с "created": false и тем же идентификатором.
• На одном имени может быть несколько записей TXT одновременно — например, две для сертификата на example.com и *.example.com.
• Идентификатор выводится из самой записи: изменённая запись получает новый.
• Проверочную запись (TXT _acme-challenge), поставленную через API и не удалённую, мы снимаем сами через 6 ч — если программа упала, не убрав её за собой. Другие записи сами не удаляются никогда.

Список записей

curl -H "Authorization: Bearer rz_…" https://regzone.pro/api/v1/zones/example.com/records

{"zone":"example.com","records":[{"id":"4Zt2…","type":"TXT","name":"_acme-challenge","value":"<token>","ttl":60,"priority":null}]}

Ключ «Только проверка SSL» видит только записи _acme-challenge; по списку удобно найти и убрать оставшиеся проверочные записи.

Удалить запись

curl -X DELETE -H "Authorization: Bearer rz_…" https://regzone.pro/api/v1/zones/example.com/records/4Zt2…

HTTP/1.1 204 No Content

Удаляется ровно одна запись; другие записи TXT на том же имени остаются. Несуществующий идентификатор — 404.

Домены

Нужно право «Домены: чтение» или «Домены: управление».

curl -H "Authorization: Bearer rz_…" https://regzone.pro/api/v1/domains

{"domains":[{"name":"example.com","status":"active","expiresAt":"2027-10-02T00:00:00.000Z","autoRenew":true,"nameservers":["ns1.regzone.pro","ns2.regzone.pro"],"dns":"platform"}]}

expiresAt — окончание срока (ISO 8601) или null, пока домен регистрируется; dns — platform, если зону обслуживают серверы имён по умолчанию, иначе other.

Серверы имён

curl -X PUT https://regzone.pro/api/v1/domains/example.com/nameservers \
  -H "Authorization: Bearer rz_…" \
  -H "Content-Type: application/json" \
  -d '{"nameservers":["ns1.example.net","ns2.example.net"]}'

{"domain":{"name":"example.com",…,"nameservers":["ns1.example.net","ns2.example.net"],"dns":"other"}}

Нужно право «Домены: управление». От 2 до 13 имён. Серверы имён по умолчанию так не ставятся (ответ 409 platform_nameservers): возврат на них — кнопкой в кабинете, она переносит записи зоны. Свои серверы для такого домена — можно: домен уйдёт с DNS по умолчанию так же, как из кабинета. В ответе — домен после изменения.

Автопродление

curl -X PUT https://regzone.pro/api/v1/domains/example.com/auto-renew \
  -H "Authorization: Bearer rz_…" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

Нужно право «Домены: управление». Автопродление списывает деньги с баланса за 14 дней до окончания срока; через API его только включают и выключают.

Свободен ли домен

curl -H "Authorization: Bearer rz_…" "https://regzone.pro/api/v1/availability?domain=example.org"

{"domain":"example.org","available":true,"premium":false,"sold":true,"price":{"minor":113480,"currency":"RUB"},"renewPrice":{"minor":113480,"currency":"RUB"}}

Нужно право «Домены: чтение». Одно полное имя за запрос. Цены — в копейках (minor) и в валюте баланса; premium — премиум-домен с особой ценой; sold: false — эту зону мы не продаём. Проверок — не больше 40 в минуту.

Покупки

Нужно право «Покупки: продление» или «Покупки: регистрация и продление». Деньги списываются с баланса аккаунта — пополните его в кабинете заранее. Адрес почты аккаунта должен быть подтверждён.

• Каждая покупка — с заголовком Idempotency-Key: уникальная строка от 8 до 100 символов (например, UUID). Повтор запроса с тем же значением — после обрыва связи или таймаута — второй раз денег не спишет, а вернёт ответ первого запроса с "replayed": true. Без заголовка — ответ 400.
• У ключа могут быть лимиты: сколько он тратит за любые 24 часа и сколько стоит одна покупка. По умолчанию лимитов нет; их задают и меняют в кабинете. Покупка сверх лимита — ответ 403, и денег не списывается.
• О каждой покупке ключом владельцу аккаунта приходит письмо: что куплено, за сколько и каким ключом. Письма выключаются в настройках ключа.
• Цены, сроки зон и проверки — те же, что при покупке в кабинете. Сумма — в копейках (minor), за весь срок.

Баланс и лимиты

curl -H "Authorization: Bearer rz_…" https://regzone.pro/api/v1/balance

{"balance":{"minor":500000,"currency":"RUB"},"key":{"purchases":"register","dailyLimit":{"minor":300000,"currency":"RUB"},"purchaseLimit":null,"spentLast24h":{"minor":113480,"currency":"RUB"},"remainingLast24h":{"minor":186520,"currency":"RUB"}}}

dailyLimit и purchaseLimit — лимиты ключа (null — без лимита); spentLast24h — сколько ключ потратил за последние 24 часа; remainingLast24h — сколько ещё можно потратить (null — без лимита).

Контакты

curl -H "Authorization: Bearer rz_…" https://regzone.pro/api/v1/contacts

{"contacts":[{"id":"8f0c…","label":"Основной","name":"Иван Петров","country":"RU","default":true}]}

Нужно право «Покупки: регистрация и продление». Контакты заводятся в кабинете; через API отдаются только номер, подпись, имя и страна.

Зарегистрировать домен

curl -X POST https://regzone.pro/api/v1/domains \
  -H "Authorization: Bearer rz_…" \
  -H "Idempotency-Key: 3b1f6c2e-7a4d-4f0e-9c1a-5d2b8e6f0a11" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.org","years":1,"contact":"8f0c…","autoRenew":true}'

HTTP/1.1 202 Accepted
{"order":{"id":"c41e…","status":"processing"},"domain":"example.org","years":1,"charged":{"minor":113480,"currency":"RUB"},"replayed":false}

Тело: domain — одно полное имя; years — срок в годах (по умолчанию 1; у .ru и .рф — только 1); contact — номер контакта-владельца (по умолчанию — основной контакт); autoRenew — продлевать ли домен автоматически с баланса (по умолчанию false). Ответ 202: заказ оплачен, регистрация идёт — обычно минуту. Ход регистрации — в GET /orders/{id}; готовый домен появится в GET /domains, если ключ работает со всеми доменами аккаунта. Для зон с дополнительными данными (.ru, .рф, .us, .it) их заполняют в контакте в кабинете.

Продлить домен

curl -X POST https://regzone.pro/api/v1/domains/example.com/renew \
  -H "Authorization: Bearer rz_…" \
  -H "Idempotency-Key: renew-example.com-2027" \
  -H "Content-Type: application/json" \
  -d '{"years":1}'

{"domain":{"name":"example.com","status":"active","expiresAt":"2028-10-02T00:00:00.000Z",…},"years":1,"charged":{"minor":113480,"currency":"RUB"},"replayed":false}

Тело: years — срок в годах (по умолчанию 1; тело можно не передавать). Продлеваются только домены ключа. В ответе — домен с новым сроком. Если реестр зоны ещё не принимает продление (у .ru и .рф — за два месяца до окончания), ответ 409 renewal_not_open с датой.

Заказ

curl -H "Authorization: Bearer rz_…" https://regzone.pro/api/v1/orders/c41e…

{"order":{"id":"c41e…","status":"completed","total":{"minor":113480,"currency":"RUB"},"placedAt":"2026-10-03T09:15:00.000Z","items":[{"domain":"example.org","years":1}]}}

Ключ видит только свои заказы. status: processing — оплачен, регистрация идёт; completed — домен зарегистрирован; failed или refunded — не получилось, деньги вернулись на баланс.

Ограничения

• До 120 запросов в минуту на ключ; сверх — ответ 429.
• Ответы несут заголовки X-RateLimit-Limit и X-RateLimit-Remaining; ответ 429 — заголовок Retry-After с числом секунд, через которое можно повторить.
• TTL — от 60 секунд до 7 суток.
• Новая запись появляется на публичных серверах имён за 1–2 минуты (для доменов на серверах имён по умолчанию).
• В зоне — не больше 200 записей.
• Ключ работает только с доменами, к которым привязан (или со всеми доменами аккаунта), и только пока они в вашем аккаунте. Переданный другому клиенту домен уходит от ключа сразу.

Ошибки

Ошибка — код HTTP и тело с машинным кодом (code), пояснением (message) и номером запроса (request_id):

HTTP/1.1 409 Conflict
X-Request-Id: req_5b1c0e7a9d2f4c68b3a1e0d97f246c15

{"error":{"code":"zone_not_active","message":"The domain is not active: its status is \"pending\". Records can be managed once it is \"active\".","details":{"status":"pending"},"request_id":"req_5b1c0e7a9d2f4c68b3a1e0d97f246c15"}}

Каждый ответ несёт заголовок X-Request-Id, а ошибка — то же значение в поле request_id. Пришлите его в поддержку: по нему мы находим запрос в журнале.

У части ошибок есть поле details с тем, что именно не так: у zone_not_active — status (текущий статус домена), у zone_not_served — nameservers (серверы имён, записанные у нас за доменом) и expected_nameservers (серверы, для которых API меняет записи), у ip_not_allowed — ip (адрес, с которого пришёл запрос).

Wildcard-сертификат через certbot

Два скрипта для certbot: первый ставит проверочную запись, второй убирает её после проверки. Замените example.com своим доменом.

#!/bin/sh
# /etc/letsencrypt/regzone-auth.sh — certbot --manual-auth-hook
set -eu
KEY=$(cat /etc/letsencrypt/regzone.key)
ZONE="example.com"
ID_FILE="/var/tmp/regzone-$CERTBOT_DOMAIN-$CERTBOT_VALIDATION.id"

curl -fsS -X POST "https://regzone.pro/api/v1/zones/$ZONE/records" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d "{\"type\":\"TXT\",\"name\":\"_acme-challenge.$CERTBOT_DOMAIN\",\"value\":\"$CERTBOT_VALIDATION\",\"ttl\":60}" \
  | sed -n 's/.*"id":"\([^"]*\)".*/\1/p' > "$ID_FILE"

# The record reaches the public nameservers within 1–2 minutes.
sleep 90

#!/bin/sh
# /etc/letsencrypt/regzone-cleanup.sh — certbot --manual-cleanup-hook
set -eu
KEY=$(cat /etc/letsencrypt/regzone.key)
ZONE="example.com"
ID_FILE="/var/tmp/regzone-$CERTBOT_DOMAIN-$CERTBOT_VALIDATION.id"

if [ -s "$ID_FILE" ]; then
  curl -fsS -X DELETE "https://regzone.pro/api/v1/zones/$ZONE/records/$(cat "$ID_FILE")" \
    -H "Authorization: Bearer $KEY"
  rm -f "$ID_FILE"
fi

Сохраните ключ в файл, выпустите сертификат — продление пойдёт с теми же скриптами:

printf '%s' 'rz_…' > /etc/letsencrypt/regzone.key
chmod 600 /etc/letsencrypt/regzone.key
chmod 700 /etc/letsencrypt/regzone-auth.sh /etc/letsencrypt/regzone-cleanup.sh

certbot certonly --manual --preferred-challenges dns \
  --manual-auth-hook /etc/letsencrypt/regzone-auth.sh \
  --manual-cleanup-hook /etc/letsencrypt/regzone-cleanup.sh \
  -d example.com -d '*.example.com'

# Renewal re-uses the same hooks:
certbot renew

Ключу хватает права «Только проверка SSL». Сертификат на example.com и *.example.com требует две записи TXT на одном имени — API это поддерживает.

Безопасность

• Ключ — как пароль: храните в файле с правами 600 и не передавайте в адресе запроса.
• Выдавайте ключу минимальное право и только нужные домены.
• О каждом новом ключе и о расширении прав ключа приходит письмо владельцу аккаунта; ключ удаляется в кабинете в один клик и сразу перестаёт работать.
• Ключу, который покупает, задайте лимит трат — тогда даже утёкший ключ не потратит больше него.
• Впишите в ключ адреса сервера, с которого он работает: с другого адреса даже утёкший ключ получит отказ.
• За 7 дней до конца срока ключа владельцу аккаунта приходит письмо. Срок не продлевается — выпустите новый ключ.