Общая раскладка для всех сотрудников

POST /v1/crm/card-config/:entityTypeId/force-common

Удаляет личные раскладки карточки у всех сотрудников и оставляет только общую раскладку выбранной области. После вызова все сотрудники видят единый макет карточки. Метод не принимает scope и userId — по своей роли он действует на всех сразу.

Параметр пути

Параметр Тип Описание
entityTypeId number Тип CRM-объекта:
1 — лид
2 — сделка
3 — контакт
4 — компания
7 — предложение
31 — счёт
смарт-процесс — числовой ID типа из `GET /v1/smart-processes`, поле entityTypeId

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

Тело может быть пустым или {}. Уточнения области передаются по необходимости.

Поле Тип Обяз. Описание
dealCategoryId number нет Воронка сделок, только для сделок (entityTypeId=2). Источник: `GET /v1/categories/2`
categoryId number нет Воронка смарт-процесса, только для смарт-процессов. Источник: `GET /v1/categories/:entityTypeId`
leadCustomerType number нет Тип лида, только для лидов (entityTypeId=1): 1 — простой, 2 — повторный

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/crm/card-config/2/force-common" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "dealCategoryId": 9 }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/crm/card-config/2/force-common" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "dealCategoryId": 9 }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm/card-config/2/force-common', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ dealCategoryId: 9 }),
})

const { success, data } = await res.json()
console.log('Общая раскладка применена ко всем:', data.forced)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm/card-config/2/force-common', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ dealCategoryId: 9 }),
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Результат операции
data.entityTypeId number Тип объекта из пути
data.forced boolean Всегда true при успехе

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

JSON 
{
  "success": true,
  "data": {
    "entityTypeId": 2,
    "forced": true
  }
}

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

400 — недопустимое значение dealCategoryId:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_DEAL_CATEGORY_ID",
    "message": "dealCategoryId must be a positive integer."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_ENTITY_TYPE_ID entityTypeId в пути не является положительным целым числом
400 INVALID_DEAL_CATEGORY_ID dealCategoryId не является положительным целым числом
400 INVALID_CATEGORY_ID categoryId не является положительным целым числом
400 INVALID_LEAD_CUSTOMER_TYPE leadCustomerType не равен 1 или 2
502 CRM_CARD_CONFIG_FORCE_COMMON_FAILED Битрикс24 не подтвердил операцию — например, недостаточно прав или целевая область недоступна
422 BITRIX_ERROR Битрикс24 не распознал тип объекта. Сообщение — в error.message
403 WRITE_BLOCKED_READONLY_KEY Ключ приложения в режиме «только чтение» — запись заблокирована
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Метод удаляет личные раскладки всех сотрудников. Личные настройки карточки, сделанные сотрудниками для выбранной области, пропадают, и все переходят на общую раскладку. Действие рассчитано на первоначальное развёртывание единого макета карточки на портале.

scope и userId не принимаются. Метод по своей роли работает на всех сотрудников. Чтобы записать общую раскладку без удаления личных, используйте `PUT` со scope: "C".

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