Для AI-агентов: markdown этой страницы — /docs-content/infra/domain/verify.md индекс документации — /llms.txt

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

POST /v1/infra/servers/:id/domain/verify

Проверяет обе DNS-записи привязанного домена и, если они верны, включает домен: приложение начинает отвечать по нему. Этим же вызовом возвращают в работу домен, отключённый после неудачной проверки.

Кому доступен вызов — Доступ.

Параметры

Параметр В Тип Обяз. Описание
Параметрid Вpath Типstring (UUID) Обяз.да ОписаниеID сервера. Источник — поле id из списка серверов

Тело запроса пустое.

Примеры

curl — личный ключ

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/domain/verify" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/domain/verify" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/domain/verify`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const body = await res.json()
if (body.success) {
  console.log(`Домен включён: ${body.data.domain.fqdn}`)
} else if (body.error.code === 'DOMAIN_VERIFICATION_FAILED') {
  // Показать, какая запись не прошла проверку
  for (const record of body.error.details.records) {
    if (record.status !== 'ok') console.log(`${record.type} ${record.host}: ${record.status}`)
  }
} else {
  throw new Error(body.error.code)
}

JavaScript — OAuth-приложение

javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/domain/verify`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue, когда обе записи верны и домен включён
Полеdata.domain.id Типstring (UUID) ОписаниеID привязки домена
Полеdata.domain.fqdn Типstring ОписаниеИмя домена в нижнем регистре
Полеdata.domain.isApex Типboolean Описаниеtrue — корневой домен, false — поддомен
Полеdata.domain.status Типstring ОписаниеСтатус домена, в этом ответе ACTIVE. Все значения — Статусы домена
Полеdata.domain.source Типstring ОписаниеПроисхождение домена. BYO — домен, которым владеете вы
Полеdata.domain.dnsMode Типstring ОписаниеКто ведёт DNS-записи. USER_DNS — вы, у своего DNS-провайдера
Полеdata.domain.verifiedAt Типstring | null ОписаниеВремя последней успешной проверки, ISO 8601
Полеdata.domain.lastVerifiedAt Типstring | null ОписаниеВремя последней проверки, успешной или нет, ISO 8601
Полеdata.domain.createdAt Типstring ОписаниеВремя привязки домена, ISO 8601
Полеdata.domain.certIssued Типboolean ОписаниеВыпущен ли сертификат для https
Полеdata.records Типarray ОписаниеРезультат по каждой записи: первой идёт TXT, второй — CNAME либо A
Полеdata.records[].type Типstring ОписаниеТип записи: TXT, CNAME или A
Полеdata.records[].host Типstring ОписаниеПолное имя записи
Полеdata.records[].status Типstring Описаниеok — запись верна, missing — не найдена, wrong — найдена с другим значением. В этом ответе у обеих записей ok
Полеdata.records[].found Типstring[] ОписаниеЗначения, которые проверка прочитала из DNS. У записи CNAME здесь могут стоять IP-адреса: так отвечает DNS-провайдер, который сам разворачивает CNAME в адреса

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

JSON
{
  "success": true,
  "data": {
    "domain": {
      "id": "bea9db66-411b-432e-a365-283a74f5714f",
      "fqdn": "app.example.com",
      "isApex": false,
      "status": "ACTIVE",
      "source": "BYO",
      "dnsMode": "USER_DNS",
      "verifiedAt": "2026-10-05T12:53:02.655Z",
      "lastVerifiedAt": "2026-10-05T12:53:02.653Z",
      "createdAt": "2026-10-05T12:53:02.616Z",
      "certIssued": false
    },
    "records": [
      {
        "type": "TXT",
        "host": "_vibecode-challenge.app.example.com",
        "status": "ok",
        "found": [
          "vibe-verify=f36ac31f213d1e3630c75f000b6631f5"
        ]
      },
      {
        "type": "CNAME",
        "host": "app.example.com",
        "status": "ok",
        "found": [
          "lb.bitrix24site.ru"
        ]
      }
    ]
  }
}

Пример ответа при ошибке

422 — запись TXT верна, но CNAME указывает на другой адрес:

JSON
{
  "success": false,
  "error": {
    "code": "DOMAIN_VERIFICATION_FAILED",
    "message": "Domain verification failed",
    "details": {
      "reason": "NOT_POINTING_TO_US",
      "records": [
        {
          "type": "TXT",
          "host": "_vibecode-challenge.app.example.com",
          "status": "ok",
          "found": [
            "vibe-verify=f36ac31f213d1e3630c75f000b6631f5"
          ]
        },
        {
          "type": "CNAME",
          "host": "app.example.com",
          "status": "wrong",
          "found": [
            "other.example.net"
          ]
        }
      ],
      "domain": {
        "id": "bea9db66-411b-432e-a365-283a74f5714f",
        "fqdn": "app.example.com",
        "isApex": false,
        "status": "FAILED",
        "source": "BYO",
        "dnsMode": "USER_DNS",
        "verifiedAt": null,
        "lastVerifiedAt": "2026-10-05T12:53:02.648Z",
        "createdAt": "2026-10-05T12:53:02.616Z",
        "certIssued": false
      },
      "hint": "Fix the records whose status is \"missing\" or \"wrong\" (see records), then repeat the check. A record that is already published is read from the authoritative name servers of the zone, so it is seen at once. If the check fails right after you edited DNS, the DNS provider has not published the change yet, or a resolver still returns the previous answer until the record TTL expires — for a name that did not exist before, that is the negative-cache TTL of the zone (SOA minimum, up to an hour). Repeating the check immediately returns the same result: wait a few minutes between attempts. The check is limited to 5 calls per minute."
    }
  }
}

Поля error.details этого отказа:

Поле Тип Описание
Полеerror.details.reason Типstring ОписаниеПервая непрошедшая запись. OWNERSHIP_TXT_MISSING — запись TXT не найдена или неверна, NOT_POINTING_TO_US — TXT верна, но домен не направлен на платформу
Полеerror.details.records Типarray ОписаниеРезультат по обеим записям, поля те же, что у data.records. Пока запись TXT не подтверждена, found пуст у обеих записей
Полеerror.details.records[].hint Типstring ОписаниеПриходит не у каждой записи. DOUBLED_ZONE — записи нет, но она нашлась под именем, к которому зона дописана дважды: в панели введено host вместо name, см. DNS-записи. HAS_AAAA — на имени домена есть запись AAAA, удалите её
Полеerror.details.domain Типobject ОписаниеДомен после проверки, поля те же, что у data.domain. Статус — FAILED
Полеerror.details.hint Типstring ОписаниеТекст на английском: что исправить и когда повторять проверку

Ошибки

HTTP Код Описание
HTTP400 КодFQDN_FORBIDDEN ОписаниеОбе записи верны, но имя домена не допускается: оно не должно содержать bitrix. Домен переходит в FAILED
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан: такой строки на платформе нет
HTTP403 КодINFRA_SCOPE_REQUIRED ОписаниеУ ключа нет скоупа vibe:infra. Проверяется раньше, чем поиск сервера
HTTP403 КодINFRA_FORBIDDEN_FOR_COWORK_KEY ОписаниеВызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — Проектный ключ для деплоя
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч в режиме «только чтение» — изменяющие операции ему закрыты
HTTP403 КодCUSTOM_DOMAINS_DISABLED ОписаниеСвои домены не включены для владельца сервера. Условия — Доступ
HTTP403 КодCUSTOM_DOMAINS_ZONE_UNSUPPORTED ОписаниеРегион аккаунта Битрикс24 не поддерживает свои домены
HTTP403 КодCUSTOM_DOMAINS_REQUIRE_COMMERCIAL ОписаниеУ аккаунта Битрикс24 нет коммерческого тарифа
HTTP404 КодSERVER_NOT_FOUND ОписаниеСервер не найден, удалён либо им управляет другой ключ
HTTP404 КодNO_DOMAIN ОписаниеК серверу не привязан домен. Проверяется раньше условий доступа с кодом 403
HTTP409 КодSERVER_HAS_NO_APP_HOST ОписаниеОбе записи верны, но у сервера ещё нет публичного адреса приложения. Статус домена не меняется. Разверните приложение и повторите проверку
HTTP409 КодDOMAIN_TAKEN_EXTERNAL ОписаниеОбе записи верны, но после привязки имя подключили к другому продукту Битрикс24. Домен переходит в FAILED. Отключите имя там и повторите проверку
HTTP422 КодDOMAIN_VERIFICATION_FAILED ОписаниеЗапись не найдена или неверна. Домен переходит в FAILED. Какая запись не прошла — в error.details.records
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит 5 запросов в минуту на этот эндпоинт. Лимит считается на владельца ключа, а не на отдельный ключ. Точное значение — в заголовке x-ratelimit-limit (потолок делится на реплики)
HTTP503 КодCUSTOM_DOMAIN_REGISTRY_UNAVAILABLE ОписаниеРеестр доменов не ответил, либо платформа не смогла прочитать адрес, с которым сравнивает записи. Статус домена остаётся прежним. Повторите вызов позже
HTTP503 Кодuser_self_deletion_pending ОписаниеВладелец ключа запросил удаление своего аккаунта на портале. Доступ вернётся после отмены удаления

Полный список общих ошибок API — Ошибки.

Известные особенности

  • Повторная проверка сразу после 422 вернёт тот же результат. Запись, которую DNS-провайдер уже опубликовал, проверка читает с авторитетных серверов зоны и видит сразу. Если отказ пришёл сразу после правки DNS, провайдер ещё не опубликовал изменение либо кэширующий DNS-сервер отдаёт прежний ответ, пока не истечёт время жизни записи (TTL). Для имени, которого раньше не существовало, это до часа. Делайте паузу в несколько минут между попытками.
  • Проверка работающего домена может его отключить. Вызов допустим и для домена в статусе ACTIVE. Если записи к этому моменту неверны, домен переходит в FAILED, и приложение перестаёт отвечать по нему до следующей успешной проверки.
  • Сертификат выпускается после ответа. Когда домен приходит в ACTIVE из другого статуса, certIssued равен false. Готовность https показывает GET /v1/infra/servers/:id/domain.

Смотрите также