Admin API: домены

Через API доступны те же действия, что и в разделе панели Домены: добавить домен, поменять его настройки, запустить проверку, собрать домены в группы и направить их на ноду. Все методы требуют токен с доступом Полный доступ (full). Авторизация описана на странице Admin API: обзор и авторизация, формат ответов и ошибок — на странице Формат запросов, ответов и ошибок.

Объект домена

Блок health

Что означает каждое сообщение этапа — на странице Проверка домена.

Домены

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

GET /api/v1/domains

Возвращает все домены команды. Параметров и постраничности нет.

Ответ — код 200 и массив объектов домена. Недавно добавленные идут первыми. Если доменов нет, приходит пустой массив [].

Добавить домены

POST /api/v1/domains

Добавляет один или несколько доменов с одинаковыми настройками.

Ответ — код 201 и объект с массивом items: добавленные домены. Поля group_name, index_campaign, campaign_count и health в этом ответе не заполнены — читайте их запросом списка.

Имена приводятся к нижнему регистру. Домен, который уже есть в трекере, пропускается без ошибки и в items не попадает.

При cloudflare: true трекер проверяет, куда указывает DNS домена. Если домен указывает не на сеть Cloudflare, он не добавляется. Если DNS ещё не отвечает, домен добавляется со статусом pending. Подробнее — на странице Работа с Cloudflare.

Ошибки:

Пример запроса:

curl -X POST https://panel.example.com/api/v1/domains \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"name":"track.example.com","new_group":"Nutra PL","no_index":true}'

Пример ответа:

{
  "items": [
    {
      "id": "3f2a9c1e-5b7d-4e8f-a1b2-c3d4e5f6a7b8",
      "name": "track.example.com",
      "ssl_status": "pending",
      "dns_status": "pending",
      "cloudflare": false,
      "group_id": "9d8c7b6a-1f2e-4d3c-b5a4-0e9f8d7c6b5a",
      "group_name": null,
      "no_index": true,
      "index_campaign_id": null,
      "index_campaign": null,
      "campaign_count": 0,
      "proxy_node_id": null,
      "blocked": false
    }
  ]
}

Изменить домен

PUT /api/v1/domains/{id}

Меняет настройки домена с ID из пути. Меняются только переданные поля. Имя домена изменить нельзя.

Значения null и пустая строка в group_id и index_campaign_id ничего не меняют. Чтобы снять значение, передайте clear_group или clear_index.

Ответ — код 200 и объект домена после изменения.

Если домен после изменения считается доменом за Cloudflare, трекер снова проверяет его DNS. Когда домен указывает не на сеть Cloudflare, запрос отклоняется целиком и ни одно поле не меняется.

Ошибки:

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

POST /api/v1/domains/{id}/verify

Запускает проверку DNS, HTTP, HTTPS и сертификата и ждёт её окончания. Тело не нужно.

Ответ — код 200 и объект с двумя полями: dns_status и health. Формат health — в разделе Блок health. dns_status здесь — pending, если этап dns не в состоянии ok, иначе значение health.proxy: proxied или direct.

Ошибки:

Удалить домен

DELETE /api/v1/domains/{id}

Удаляет домен. В корзину домен не попадает. Кампании, которые его использовали, остаются без домена.

Ответ — код 204 без тела. Если домена с таким ID нет — 404 с кодом not_found, если ID — не UUID — 400 с кодом bad_request.

Группы доменов

Группы определяют, какие домены видят баеры и верстальщики. Подробнее — на странице Группы доменов и доступ баеров.

Список групп

GET /api/v1/domain-groups

Ответ — код 200 и массив групп, отсортированный по названию.

Создать группу

POST /api/v1/domain-groups

Ответ — код 201 и объект группы с пустым shared_to и domain_count, равным 0. Если name пустое или тело не разобрано — 422 с кодом validation и сообщением name is required.

Удалить группу

DELETE /api/v1/domain-groups/{id}

Удаляет группу. Домены остаются в трекере без группы, доступ пользователей к ним через эту группу пропадает.

Ответ — код 204 без тела. Если группы нет — 404 с кодом not_found, если ID — не UUID — 400 с кодом bad_request.

Открыть группу пользователям

POST /api/v1/domain-groups/{id}/share

Задаёт список пользователей, которым видна группа и её домены. Список заменяется целиком.

ID, которых нет в команде, пропускаются без ошибки. ID пользователей отдаёт метод списка на странице Admin API: пользователи.

Ответ — код 204 без тела.

Ошибки: 400 с кодом bad_request — тело не разобрано или ID — не UUID; 404 с кодом not_found — группы нет.

Пример запроса:

curl -X POST https://panel.example.com/api/v1/domain-groups/9d8c7b6a-1f2e-4d3c-b5a4-0e9f8d7c6b5a/share \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"user_ids":["1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"]}'

Направление на proxy-сервер

Оба метода выставляют проксированную A-запись домена на адрес ноды через аккаунт Cloudflare, добавленный в трекер, и запоминают привязку. Нода должна быть в статусе ready. Подготовка описана на страницах Proxy-серверы и Работа с Cloudflare, методы нод и аккаунтов — на странице Admin API: proxy-серверы и Cloudflare.

Направить домен на ноду

POST /api/v1/domains/{id}/route

Направляет домен с ID из пути на ноду.

Ответ — код 200 и объект: ok — true, node_ip — адрес ноды.

Ошибки:

Направить несколько доменов

POST /api/v1/domains/route-bulk

Направляет на одну ноду до 500 доменов за запрос.

Ответ — код 200, даже если часть доменов направить не удалось. Проверяйте массив failed.

Ошибки те же, что у предыдущего метода, кроме cf_error: причины по каждому домену приходят в failed. Коды 400 и 404 относятся только к ноде: домен с неверным или незнакомым ID попадает в failed. Код validation возвращается также при пустом domain_ids и при списке длиннее 500 ID.