# Свой домен

Собственный домен для приложения на сервере: приложение отвечает не только по адресу, выданному платформой, но и по имени, которым владеете вы. Привязка идёт в два шага — вы получаете DNS-записи, создаёте их у своего DNS-провайдера и запускаете проверку. Сертификат для `https` платформа выпускает сама после проверки.

Скоуп: `vibe:infra`

## Операции

- [Привязать домен](./domain/attach.md) — `POST /v1/infra/servers/:id/domain`
- [Получить домен](./domain/get.md) — `GET /v1/infra/servers/:id/domain`
- [Проверить домен](./domain/verify.md) — `POST /v1/infra/servers/:id/domain/verify`
- [Отвязать домен](./domain/detach.md) — `DELETE /v1/infra/servers/:id/domain`

## Доступ

Операции выполняет только ключ, который управляет сервером. Любой другой ключ, включая второй ключ того же владельца, получает `404 SERVER_NOT_FOUND`. Идентификатор сервера — поле `id` из [списка серверов](/docs/infra/servers/list).

Привязка, проверка и отвязка требуют скоупа `vibe:infra`. Чтение состояния скоупа не требует.

Привязка и проверка доступны при трёх условиях, и каждое отвечает своим кодом `403`:

| Условие | Код отказа |
|---------|------------|
| Свои домены включены для владельца сервера | `CUSTOM_DOMAINS_DISABLED` |
| Регион аккаунта Битрикс24 поддерживает свои домены | `CUSTOM_DOMAINS_ZONE_UNSUPPORTED` |
| У аккаунта Битрикс24 коммерческий тариф | `CUSTOM_DOMAINS_REQUIRE_COMMERCIAL` |

Чтение и отвязка этих условий не проверяют: привязанный домен всегда можно прочитать и отвязать.

## DNS-записи

Ответы привязки и чтения несут массив `instructions` из двух записей:

| Запись | Назначение |
|--------|------------|
| `TXT` | Подтверждает, что домен ваш. Значение — `vibe-verify=…`, своё у каждой привязки |
| `CNAME` либо `A` | Направляет домен на платформу. Поддомен (`app.example.com`) получает `CNAME`, корневой домен (`example.com`) — `A` |

У каждой записи два имени. `host` — полное имя записи. `name` — то же имя относительно зоны `zone`: именно его ждёт поле «имя» в панели DNS-провайдера, для самой зоны это `@`. Если ввести в панели полное имя, провайдер допишет зону ещё раз, и проверка такую запись не найдёт.

На имени домена не должно быть записи `AAAA`: платформа принимает запросы только по IPv4.

## Статусы домена

| Статус | Что означает |
|--------|--------------|
| `PENDING_VERIFICATION` | Домен привязан, проверка ещё не запускалась |
| `VERIFYING` | Проверка идёт |
| `ACTIVE` | Записи верны, приложение отвечает по домену |
| `FAILED` | Последняя проверка не нашла нужных записей |
| `SUSPENDED` | Домен работал, но отключён: записи перестали указывать на платформу, аккаунт Битрикс24 деактивирован либо отвязка не завершилась |

Домен в статусе `FAILED` или `SUSPENDED` возвращается в `ACTIVE` той же [проверкой](./domain/verify.md) после исправления записей.

## Типовой сценарий

1. [`POST /domain`](./domain/attach.md) с именем домена — в ответе записи `instructions`.
2. Создать обе записи у DNS-провайдера, в поле «имя» подставляя `name`.
3. [`POST /domain/verify`](./domain/verify.md). Ответ `200` — домен в статусе `ACTIVE`. Ответ `422` — в `error.details.records` указано, какая запись не найдена или неверна. Повторять проверку сразу бессмысленно: изменение DNS публикуется не мгновенно, выждите несколько минут.
4. [`GET /domain`](./domain/get.md), пока `certIssued` не станет `true`, — с этого момента домен открывается по `https`.

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

- [Инфраструктура](/docs/infra)
- [Серверы](/docs/infra/servers)
- [Полный деплой приложения](/docs/infra/deploy/deploy)
- [Журнал изменений](/docs/changelog)