Para agentes de IA: markdown desta página — /docs-content-en/entities/crm-traces.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Sales-intelligence traces

A trace stores a site visitor's journey and acquisition source and is bound to CRM leads, deals, contacts, companies or quotes.

Bitrix24 API: crm.tracking.trace.add, crm.tracking.trace.delete Scope: crm

Create a trace

POST /v1/crm-traces

Creates a sales-intelligence trace and binds it to CRM records. Call it after creating a lead or another record to save where the visitor came from.

Request fields (body)

Field Type Required Description
Fieldtrace Typeobject | string Requiredyes DescriptionA trace object or a string containing a JSON object. An array, a number, null and a string without a JSON object are rejected with 400 INVALID_PARAMS
Fieldentities Typearray Requiredno DescriptionBindings to CRM records. Without the array or with an empty array, an unbound trace is created
Fieldentities[].type Typestring Requiredyes DescriptionRecord type: LEAD, DEAL, CONTACT, COMPANY or QUOTE
Fieldentities[].id Typenumber | string Requiredyes DescriptionID of an existing record — a positive integer; a string of digits is also accepted. List: GET /v1/leads, GET /v1/deals, GET /v1/contacts, GET /v1/companies, GET /v1/quotes

A trace object is passed without renaming its keys; a string is passed as is. The site tracker b24Tracker.guest.getTrace() returns a ready-to-use string. Sales intelligence uses the following trace keys: url, ref — the address the visitor came from, client — the analytics client identifier, gid, device.isMobile, pages.list with [url, timestamp, title] triples, tags.ts, tags.list with UTM tags, previous.list, channels with the code and value fields. The object may be empty: {"trace": {}} creates a trace.

Examples

curl — personal key

Terminal 
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",
      "ref": "https://example.com/news",
      "tags": { "list": { "utm_source": "newsletter", "utm_campaign": "autumn" } }
    },
    "entities": [{ "type": "LEAD", "id": 123 }]
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-traces" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trace": {
      "url": "https://example.com/form",
      "ref": "https://example.com/news",
      "tags": { "list": { "utm_source": "newsletter", "utm_campaign": "autumn" } }
    },
    "entities": [{ "type": "LEAD", "id": 123 }]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-traces', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    trace: {
      url: 'https://example.com/form',
      ref: 'https://example.com/news',
      tags: { list: { utm_source: 'newsletter', utm_campaign: 'autumn' } },
    },
    entities: [{ type: 'LEAD', id: 123 }],
  }),
})

const { data } = await res.json()
console.log('Trace ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-traces', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    trace: {
      url: 'https://example.com/form',
      ref: 'https://example.com/news',
      tags: { list: { utm_source: 'newsletter', utm_campaign: 'autumn' } },
    },
    entities: [{ type: 'LEAD', id: 123 }],
  }),
})

const { data } = await res.json()
console.log('Trace ID:', data.id)

Response fields

HTTP status 201 Created.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe created trace
Fielddata.id Typenumber DescriptionTrace identifier. Needed for deletion

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 2025
  }
}

Error response example

404 — a CRM record from entities was not found, the trace was not created:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe body has no trace, or the body is not a JSON object
HTTP400 CodeINVALID_PARAMS Descriptiontrace is neither an object nor a string with a JSON object, the body root or an entities element has an extra key, entities is not an array, entities[].type is unknown, or entities[].id is not a positive integer
HTTP404 CodeENTITY_NOT_FOUND DescriptionA CRM record from entities was not found. The trace is not created
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo permission to read or update a CRM record from entities
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the trace creation. The error text is returned in error.message
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 returned an invalid response to the record read or to the trace creation
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the crm scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key works in read-only mode
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Records are checked before creation. All records from entities are read before the trace is created; duplicate records are read only once. If at least one record is not found or not accessible, the trace is not created. Permission to update a record is checked when the trace is created. The check does not protect against a record being deleted between the read and the trace creation.

See also