## Получить коды встраивания формы

`GET /v1/crm-forms/:id/embedding`

Получите код встраивания формы или публичную ссылку для размещения на сайте. Параметры запроса меняют выбранный вариант без сохранения настроек.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| `id` (path) | number | да | Положительный ID формы из [списка форм](/docs/entities/crm-forms/list) |
| `variant` (query) | string | нет | `inline`, `click`, `auto`, `link`. Без параметра — все настройки встраивания |
| `buttonText` (query) | string | нет | Подпись кнопки для запрошенной встройки. Значение проверяет Битрикс24 |
| `buttonType` (query) | string | нет | Тип кнопки, например `button` или `link`. Значение проверяет Битрикс24 |
| `delay` (query) | integer | нет | Задержка в секундах. Значение и сочетание с `variant` проверяет Битрикс24 |

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/crm-forms/59/embedding?variant=link" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/crm-forms/59/embedding?variant=link" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/59/embedding?variant=link', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/59/embedding?variant=link', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
```

## Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `success` | boolean | `true` при успехе |
| `data` | object | Объект встраивания из Битрикс24 без пересборки. Без `variant` — доступные варианты и настройки. Для `link` — `{variant, url}` |
| `data.formActive` | boolean | Активна ли форма |
| `data.resourcesReady` | boolean | Готовы ли ресурсы формы |
| `data.publicUrl` | string | Публичная ссылка на форму вместе с публичной подписью |
| `data.inline` | object | Форма внутри страницы |
| `data.click` | object | Форма, открываемая по нажатию |
| `data.auto` | object | Форма, открываемая через заданное время |
| `data.<variant>.code` | string / null | HTML-код для размещения на сайте или `null`, если ресурсы не готовы |
| `data.<variant>.previewUrl` | string | Ссылка на предварительный просмотр, если она передана. Отсутствующие поля и `null` сохраняются |
| `data.<variant>.settings` | object / null | Текущие настройки. См. [Обновить настройки встраивания](/docs/entities/crm-forms/embedding-update). Значения передаются как есть, включая `null` |
| `data.<variant>.options` | object / null | Допустимые значения настроек из Битрикс24, включая `null` |
| `data.<variant>.options.type` | string[] | `popup`, `panel` |
| `data.<variant>.options.position` | string[] | `left`, `center`, `right` |
| `data.<variant>.options.vertical` | string[] | `bottom`, `top` |
| `data.click.options.button.font` | string[] | `modern`, `classic`, `elegant` |
| `data.click.options.button.align` | string[] | `inline`, `left`, `center`, `right` |
| `data.auto.options.delay` | number[] | `3`, `5`, `7`, `10`, `15`, `20`, `25`, `30`, `40`, `60`, `120` |
| `data.variant` | string | Выбранный вариант, только при переданном `variant` |
| `data.code` | string / null | Код выбранного HTML-варианта, включая `null`, если он передан |
| `data.url` | string | Публичная ссылка при `variant=link` |
| `meta.redacted` | string[] | Пути с заменёнными учётными данными соединения. Такой ответ не является полной конфигурацией для обратного сохранения |

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

Ответ при `variant=link`. Публичный домен и подпись в примере условные.

```json
{
  "success": true,
  "data": {
    "variant": "link",
    "url": "https://example.bitrix24.ru/crm_form_tz6sk/?telemetry_sign=DUMMY_PUBLIC_SIGNATURE"
  }
}
```

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

400 — ID формы не является положительным целым числом:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "id must be a positive safe integer"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|---|---|---|
| 400 | `INVALID_PARAMS` | Некорректный ID формы или структура запроса |
| 400 | `INVALID_PARAMS` | Неизвестный параметр или некорректная структура запроса |
| 400 | `INVALID_PARAMS` | Битрикс24 отклонил параметр или сочетание параметров. Исходный код — в `error.b24Code`, уточнения по полям — в `error.validation`, если переданы |
| 409 | `CRM_FORM_REST_NOT_ENABLED` | REST-методы CRM-форм выключены на портале. Исходный код отсутствующего метода — в `error.b24Code` |
| 403 | `BITRIX_INSUFFICIENT_SCOPE` | Токену Битрикс24 не хватает скоупа. Исходный код — в `error.b24Code` |
| 404 | `ENTITY_NOT_FOUND` | Форма не найдена |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `crm` |
| 403 | `BITRIX_ACCESS_DENIED` | У пользователя нет прав доступа |
| 401 | `TOKEN_MISSING` | У API-ключа не настроены учётные данные |
| 502 | `BITRIX_UNAVAILABLE` | Некорректный ответ с данными встраивания |

Ошибки Битрикс24 содержат исходный `error.b24Code` и переданные уточнения по полям в `error.validation`. Общие ошибки API — [Ошибки](/docs/errors).

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

Если ресурсы не готовы, ответ остаётся успешным с `resourcesReady: false` и переданным значением `code: null`. Отсутствующие поля не заполняются. Публичные подписи сохраняются. Заменяются только учётные данные текущего соединения, пути перечисляются в `meta.redacted`.

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

- [Обновить настройки встраивания формы](/docs/entities/crm-forms/embedding-update)
- [Список форм](/docs/entities/crm-forms/list)