Конфигурируемые дела

Конфигурируемое дело — запись в таймлайне CRM-сущности с собственным оформлением: иконкой, заголовком, блоками тела и кнопками. Внешний вид задаёт структура layout. Подходит для интеграций, которые показывают в таймлайне сделки, лида, контакта или компании карточку звонка, заявки, доставки или другого внешнего события.

Раздел содержит только создание, чтение и обновление. Удаление и список — через общий API дел: `DELETE /v1/activities/:id` и `GET /v1/activities`.

Битрикс24 API: crm.activity.configurable.* Скоуп: crm

Создать дело

POST /v1/activity-configurable

Создаёт конфигурируемое дело в таймлайне CRM-сущности. Набор полей дела задаёт fields, внешний вид — layout.

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

Поле Тип Обяз. Описание
ownerTypeId number да Тип CRM-сущности:
1 — лид
2 — сделка
3 — контакт
4 — компания
7 — предложение
31 — счёт
≥128 — смарт-процесс, id типа — в `GET /v1/smart-processes`
ownerId number да ID сущности, в таймлайне которой создаётся дело
fields object да Поля дела
fields.typeId string нет Тип дела. По умолчанию CONFIGURABLE. Свой тип регистрируется в Битрикс24 как конфигурируемый в контексте того же приложения
fields.completed boolean нет Дело закрыто. Принимает true/false, 1/0, Y/N
fields.deadline string нет Крайний срок исполнения, ISO 8601. Несовместим с fields.isIncomingChannel
fields.pingOffsets number[] нет Смещения в минутах относительно fields.deadline, в которые формируются напоминания
fields.isIncomingChannel boolean нет Дело создано из входящего канала. Принимает true/false, 1/0, Y/N
fields.responsibleId number нет ID ответственного сотрудника. Список: GET /v1/users
fields.badgeCode string нет Код значка дела на канбане
fields.originatorId string нет ID внешнего источника данных
fields.originId string нет ID записи во внешнем источнике
layout object да Оформление дела в таймлайне
layout.icon.code string да Код иконки дела
layout.header.title string да Заголовок дела
layout.body.logo.code string да Код логотипа в теле. Тело без logo Битрикс24 отклоняет
layout.body.blocks object нет Именованные блоки тела
layout.footer.buttons object нет Кнопки футера

Блок в layout.body.blocks имеет type и properties. Основные типы блоков:

  • text — значение
  • link — ссылка с действием
  • lineOfBlocks — строка из вложенных блоков
  • withTitle — блок с подписью

Действие у ссылок и кнопок задаёт поле type:

  • redirect — переход по адресу из поля uri
  • openRestApp — открытие приложения с параметрами actionParams
  • restEvent — событие приложению по id, для пунктов меню

Примеры

Примеры приведены только для OAuth-приложения.

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/activity-configurable \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerTypeId": 1,
    "ownerId": 999,
    "fields": { "typeId": "CONFIGURABLE", "completed": true, "responsibleId": 1, "badgeCode": "CUSTOM" },
    "layout": {
      "icon": { "code": "call-completed" },
      "header": { "title": "Входящий звонок" },
      "body": {
        "logo": { "code": "call-incoming" },
        "blocks": {
          "phone": { "type": "text", "properties": { "value": "+7 999 888 7777" } }
        }
      },
      "footer": {
        "buttons": {
          "startCall": {
            "title": "О клиенте",
            "type": "primary",
            "action": { "type": "openRestApp", "actionParams": { "clientId": 456 } }
          }
        }
      }
    }
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/activity-configurable', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ownerTypeId: 1,
    ownerId: 999,
    fields: { typeId: 'CONFIGURABLE', completed: true, responsibleId: 1, badgeCode: 'CUSTOM' },
    layout: {
      icon: { code: 'call-completed' },
      header: { title: 'Входящий звонок' },
      body: {
        logo: { code: 'call-incoming' },
        blocks: {
          phone: { type: 'text', properties: { value: '+7 999 888 7777' } },
        },
      },
      footer: {
        buttons: {
          startCall: {
            title: 'О клиенте',
            type: 'primary',
            action: { type: 'openRestApp', actionParams: { clientId: 456 } },
          },
        },
      },
    },
  }),
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.activity.id number ID созданного дела

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

JSON 
{
  "success": true,
  "data": { "activity": { "id": 8053 } }
}

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

422 — не заполнен logo в теле:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Поле logo в BodyDto должно быть заполнено."
  }
}

Ошибки

HTTP Код Описание
400 VALIDATION_ERROR Не передан ownerTypeId, ownerId, fields или layout
422 BITRIX_ERROR Битрикс24 отклонил запрос: пустой layout, не заполнен layout.body.logo, вызов вне контекста приложения, входящее дело с deadline
403 SCOPE_DENIED Ключу не хватает скоупа crm
401 TOKEN_MISSING Ключ авторизации передан без токена сессии в заголовке Authorization: Bearer

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

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

Только в контексте приложения. Нужен ключ авторизации vibe_app_* с токеном сессии в заголовке Authorization: Bearer. Персональный API-ключ vibe_api_* Битрикс24 отклоняет с ERROR_WRONG_CONTEXT.

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