Для AI-агентов: markdown этой страницы — /docs-content/entities/crm-tracking/ad-account-connect.md индекс документации — /llms.txt

Метод в процессе раскатки — выходит в обновлении crm 26.2100.0. Доступен не на всех порталах Битрикс24. Если на вашем портале метод ещё не доступен, API вернёт 422 METHOD_NOT_YET_AVAILABLE — это не ошибка интеграции, а признак того, что обновление пока не приехало на портал.

Подключить рекламный кабинет

POST /v1/crm-tracking/sources/:id/ad-account

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

Требуется скоуп crm, ключ READWRITE, включённый флаг crm-tracking-v3 и доступность метода на портале Битрикс24.

Параметры

Параметр Тип Обяз. Описание
Параметрid (path) Типnumber Обяз.да ОписаниеПоложительный целочисленный ID источника из списка источников

Поля запроса (body)

Поле Тип Обяз. Описание
ПолеclientId Типstring Обяз.да ОписаниеID клиента из списка рекламных кабинетов
ПолеaccountId Типstring | null Обяз.нет ОписаниеID рекламного кабинета из списка рекламных кабинетов

Поля передаются в корне JSON. Параметры строки запроса и неизвестные поля тела не принимаются. Длину строк и требования рекламной системы проверяет Битрикс24.

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/crm-tracking/sources/2/ad-account" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clientId":"DUMMY_CLIENT"}'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/crm-tracking/sources/2/ad-account" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"clientId":"DUMMY_CLIENT"}'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-tracking/sources/2/ad-account', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ clientId: 'DUMMY_CLIENT' })
})
const { success, data } = await res.json()
console.log(data.sourceId)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-tracking/sources/2/ad-account', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ clientId: 'DUMMY_CLIENT' })
})
const { success, data } = await res.json()
console.log(data.sourceId)

Поля ответа

При успехе возвращается HTTP 200 с JSON.

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успехе
Полеdata Типobject ОписаниеНастройки подключения после изменения
Полеdata.sourceId Типnumber ОписаниеID источника из списка источников
Полеdata.provider Типstring ОписаниеКод рекламной системы
Полеdata.clientId Типstring | null ОписаниеID подключённого клиента из списка рекламных кабинетов или null
Полеdata.accountId Типstring | null ОписаниеID подключённого рекламного кабинета из списка рекламных кабинетов или null

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

Пример структуры ответа.

JSON 
{
  "success": true,
  "data": {
    "sourceId": 2,
    "provider": "google",
    "clientId": "DUMMY_CLIENT",
    "accountId": null
  }
}

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

400 — источник не поддерживает подключение рекламного кабинета:

JSON 
{
  "success": false,
  "error": {
    "code": "CRM_TRACKING_AD_PROVIDER_UNSUPPORTED",
    "message": "CRM_TRACKING_AD_PROVIDER_UNSUPPORTED"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодMISSING_REQUIRED_FIELDS ОписаниеНе передано поле clientId
HTTP400 КодINVALID_PARAMS ОписаниеНекорректный ID, неверный тип поля, неизвестное поле тела или тело не в форме объекта
HTTP400 КодUNKNOWN_FILTER_FIELD ОписаниеПередан параметр строки запроса
HTTP400 КодCRM_TRACKING_AD_PROVIDER_UNSUPPORTED ОписаниеИсточник не поддерживает эту рекламную операцию
HTTP403 КодSCOPE_DENIED ОписаниеНет скоупа crm
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч разрешает только чтение
HTTP404 КодENTITY_NOT_FOUND ОписаниеУказанный источник не найден
HTTP422 КодMETHOD_NOT_YET_AVAILABLE ОписаниеФлаг выключен или метод ещё недоступен на портале Битрикс24
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеПолучен некорректный ответ Битрикс24

Остальные коды и сообщения отказов Битрикс24 сохраняются. Общие ошибки API — Ошибки.

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