Как правильно форматировать массив полей в Bitrix24 вебхук

Правильное форматирование массива полей в Bitrix24 вебхуках требует использования двойных квадратных скобок для передачи нескольких значений. Основной синтаксис для передачи массива полей: fields[[название_поля]]=значение или через JSON-структуру с объектом fields, содержащим пары “ключ-значение”.

Содержание

• Основной синтаксис полей вебхука
• Форматирование в интерфейсе Bitrix24
• Примеры правильного оформления
• Распространенные ошибки и их решения
• Практические примеры кода
• Рекомендации по тестированию

Основной синтаксис полей вебхука

При работе с вебхуками Bitrix24 существует два основных способа форматирования полей:

1. URL-параметры с двойными скобками

Согласно официальной документации Bitrix24, при передаче массива полей через URL-параметры используется синтаксис с двойными квадратными скобками:

fields[[TITLE]]=Название лида
fields[[COMPANY_NAME]]=Название компании
fields[[PHONE][0][VALUE]]=+79001234567

Каждое поле обрамляется двойными скобками [[ ]] чтобы Bitrix24 правильно интерпретировал структуру данных.

2. JSON-формат с объектом fields

Для программной интеграции используется JSON-формат:

{
  "fields": {
    "TITLE": "Название лида",
    "COMPANY_NAME": "Название компании",
    "PHONE": [{
      "VALUE": "+79001234567",
      "VALUE_TYPE": "WORK"
    }]
  }
}

Важно: Для сложных полей, таких как телефон или email, требуется вложенная структура с указанием типа значения.

Форматирование в интерфейсе Bitrix24

Настройка параметров в интерфейсе

1. В разделе “Вебхуки” выберите входящий вебхук
2. В параметрах (Params) для каждого поля используйте следующий формат:
   • Ключ: [[название_поля]]
   • Значение: значение поля

Пример настройки в интерфейсе

Примеры правильного оформления

Пример 1: Простые поля

fields[[TITLE]]=Название лида
fields[[COMPANY_NAME]]=Название компании
fields[[COMMENTS]]=Комментарий к сделке

Пример 2: Поле с телефоном

Для телефонных номеров требуется структура с типом значения:

fields[[PHONE][0][VALUE]]=+79001234567
fields[[PHONE][0][VALUE_TYPE]]=WORK
fields[[PHONE][1][VALUE]]=+79009876543
fields[[PHONE][1][VALUE_TYPE]]=MOBILE

Пример 3: Поле с email

fields[[EMAIL][0][VALUE]]=user@example.com
fields[[EMAIL][0][VALUE_TYPE]]=WORK

Пример 4: Массив пользователей

fields[[ACCOMPLICES][0]]=1
fields[[ACCOMPLICES][1]]=3

Распространенные ошибки и их решения

Ошибка 1: Неправильное количество скобок

Неправильно:

fields[ TITLE ] = значение  // одинарные скобки

Правильно:

fields[[ TITLE ]] = значение  // двойные скобки

Ошибка 2: Отсутствие структуры для сложных полей

Неправильно:

fields[PHONE] = +79001234567  // без структуры типа

Правильно:

fields[[PHONE][0][VALUE]] = +79001234567
fields[[PHONE][0][VALUE_TYPE]] = WORK

Ошибка 3: Неправильная кодировка URL

При передаче через URL убедитесь, что специальные символы правильно закодированы:

fields[[COMMENTS]] = Текст%20с%20пробелами

Практические примеры кода

Пример на PHP

<?php
// Формирование данных для вебхука
$queryData = http_build_query(array(
    'fields' => array(
        "TITLE" => "Лид с сайта",
        "COMPANY_NAME" => "Тестовая компания",
        "PHONE" => array(
            array(
                "VALUE" => "+79001234567",
                "VALUE_TYPE" => "WORK"
            )
        )
    )
));

// URL вебхука
$queryUrl = "https://ваш-портал.bitrix24.com/rest/ваш-токен/crm.lead.add.json";

// Отправка запроса
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_SSL_VERIFYPEER => 0,
    CURLOPT_POST => 1,
    CURLOPT_HEADER => 0,
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => $queryUrl,
    CURLOPT_POSTFIELDS => $queryData,
));
$result = curl_exec($curl);
curl_close($curl);
?>

Пример на JavaScript (fetch)

const webhookUrl = 'https://ваш-портал.bitrix24.com/rest/ваш-токен/crm.lead.add.json';

const data = {
    fields: {
        TITLE: "Лид из формы",
        COMPANY_NAME: "Компания клиента",
        PHONE: [{
            VALUE: "+79001234567",
            VALUE_TYPE: "WORK"
        }]
    }
};

fetch(webhookUrl, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => console.log(result));

Рекомендации по тестированию

1. Используйте тестовый интерфейс

Bitrix24 предоставляет интерфейс для тестирования вебхуков:

• Зайдите в настройки вебхука
• Нажмите “Тестировать”
• Заполните поля в правильном формате

2. Пошаговая проверка

1. Сначала протестируйте простые поля (TITLE, COMPANY_NAME)
2. Затем добавьте сложные поля (PHONE, EMAIL)
3. Проверьте работу с массивами пользователей

3. Логирование ошибок

Включите логирование для отслеживания ошибок:

// Пример логирования в PHP
file_put_contents('webhook_log.txt', date('Y-m-d H:i:s') . " - " . $result . PHP_EOL, FILE_APPEND);

4. Валидация данных

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

Источники

1. Create webhooks and apps in Bitrix24 - Официальная документация по форматированию полей с использованием fields[[field]]
2. Inbound and outbound webhooks - Bitrix24 Helpdesk - Подробное руководство по работе с вебхуками
3. Bitrix sending and receiving webhooks / ChatApp - Практические примеры форматирования полей
4. Working with a lead in Bitrix24 using the API - Примеры кода для работы с вебхуками
5. Bitrix24 - Webhook how to get data phone in array - Stack Overflow обсуждение правильной структуры телефонных полей

Заключение

Правильное форматирование массива полей в Bitrix24 вебхуках требует внимания к деталям:

• Всегда используйте двойные квадратные скобки [[ ]] для простых полей
• Для сложных полей (телефон, email) используйте вложенную структуру с указанием типа значения
• Тестируйте сложные поля пошагово, начиная с простых
• Используйте официальную документацию Bitrix24 как основной источник информации

Следуя этим правилам, вы сможете избежать большинства ошибок при передаче данных через вебхуки Bitrix24 и обеспечить стабильную работу интеграций.