Per gli agenti AI: markdown di questa pagina — /docs-content-en/entities/crm-traces.md indice della documentazione — /llms.txt
Gli articoli della documentazione sono attualmente disponibili solo in inglese.
Sales-intelligence traces
A trace records a site visitor's journey and acquisition source. Create a lead with POST /v1/leads, then pass its id in entities when creating a trace.
Bitrix24 API: crm.tracking.trace.add, crm.tracking.trace.delete
Scope: crm. A READWRITE key is required.
Create a trace
POST /v1/crm-traces
Bitrix24 method: crm.tracking.trace.add. Scope crm, READWRITE key.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| trace | object or string | Yes | A JSON trace object or a string containing a JSON object. Arrays and scalars are refused. |
| entities | array | No | CRM bindings. An omitted or empty array legally leaves the trace unbound. |
| entities[].type | string | Yes | LEAD, DEAL, CONTACT, COMPANY or QUOTE. |
| entities[].id | number or string | Yes | A positive safe integer id of an existing record. |
A trace object is serialized without renaming its keys. b24Tracker.guest.getTrace() returns a ready-to-use string. Bitrix24 reads url, gid, device.isMobile, pages.list with [url, timestamp, title] tuples, tags.ts, tags.list with UTM tags, previous.list, and channels with code and value. The ref key supplies the referrer, and client supplies the analytics client identifier. The minimal object may be empty.
curl -X POST 'https://vibecode.bitrix24.com/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}]}'Response
HTTP 201. data.id is the numeric id of the created trace.
{"success":true,"data":{"id":42}}Errors
| HTTP | Code | Reason |
|---|---|---|
| 400 | MISSING_REQUIRED_FIELDS | Missing trace. |
| 400 | INVALID_PARAMS | Invalid JSON, scalar, array or binding. |
| 403 | SCOPE_DENIED | Missing crm scope. |
| 403 | WRITE_BLOCKED_READONLY_KEY | The key prohibits writes. |
| 403 | BITRIX_ACCESS_DENIED | Bitrix24 refuses record read or update access. |
| 404 | ENTITY_NOT_FOUND | CRM record absent during the pre-read. |
| 422 | BITRIX_ERROR | Bitrix24 business refusal with its original message. |
| 502 | BITRIX_UNAVAILABLE | Invalid Bitrix24 response. |
The pre-read happens before trace creation. Bitrix24 checks update access when adding the trace. The record may disappear between validation and creation.