# Создать след

`POST /v1/crm-traces`

Метод Битрикс24: `crm.tracking.trace.add`. Скоуп `crm`, ключ READWRITE.

## Тело запроса

| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| trace | object или string | Да | JSON-объект следа либо строка, содержащая JSON-объект. Массивы и скаляры отклоняются. |
| entities | array | Нет | Привязки к CRM. Без массива или с пустым массивом след законно остаётся непривязанным. |
| entities[].type | string | Да | LEAD, DEAL, CONTACT, COMPANY или QUOTE. |
| entities[].id | number или string | Да | Положительное безопасное целое id существующей записи. |

Объект trace сериализуется без переименования ключей. Трекер `b24Tracker.guest.getTrace()` выдаёт готовую строку. Исходники Битрикс24 читают `url`, `gid`, `device.isMobile`, `pages.list` с тройками `[url, timestamp, title]`, `tags.ts`, `tags.list` с UTM-метками, `previous.list`, `channels` с `code` и `value`. Ключ `ref` задаёт реферер, `client` — клиентский идентификатор аналитики. Минимальный объект может быть пустым.

```bash
curl -X POST 'https://vibecode.bitrix24.tech/v1/crm-traces'   -H 'X-Api-Key: YOUR_API_KEY' -H 'Content-Type: application/json'   -d '{"trace":{"url":"https://example.com/form","tags":{"list":{"utm_source":"newsletter"}}},"entities":[{"type":"LEAD","id":123}]}'
```

## Ответ

HTTP 201. `data.id` — числовой id созданного следа.

```json
{"success":true,"data":{"id":42}}
```

## Ошибки

| HTTP | Код | Причина |
|---|---|---|
| 400 | MISSING_REQUIRED_FIELDS | Отсутствует trace. |
| 400 | INVALID_PARAMS | Невалидный JSON, скаляр, массив или неправильная привязка. |
| 403 | SCOPE_DENIED | Нет скоупа crm. |
| 403 | WRITE_BLOCKED_READONLY_KEY | Ключ запрещает запись. |
| 403 | BITRIX_ACCESS_DENIED | Битрикс24 запрещает чтение или изменение записи. |
| 404 | ENTITY_NOT_FOUND | CRM-запись не найдена при предчтении. |
| 422 | BITRIX_ERROR | Бизнес-отказ Битрикс24, текст сохранён. |
| 502 | BITRIX_UNAVAILABLE | Некорректный ответ Битрикс24. |

Предчтение выполняется до создания следа. Битрикс24 проверяет право изменения при добавлении. Запись может исчезнуть между проверкой и добавлением.

[Все операции](../crm-traces.md) · [Удалить след](./delete.md)