Для AI-агентов: markdown этой страницы — /docs-content/entities/crm-traces.md индекс документации — /llms.txt
Следы сквозной аналитики
След хранит путь посетителя сайта и источник обращения. Создайте лид через POST /v1/leads, затем передайте его id в entities при создании следа.
Битрикс24 API: crm.tracking.trace.add, crm.tracking.trace.delete
Скоуп: crm. Требуется ключ READWRITE.
Создать след
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 — клиентский идентификатор аналитики. Минимальный объект может быть пустым.
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 созданного следа.
{"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 проверяет право изменения при добавлении. Запись может исчезнуть между проверкой и добавлением.