Первый вызов метода API

Первый вызов метода — момент, когда абстрактный REST API превращается в работающую интеграцию. Покажем на практике: как проверить доступ методом profile, создать сделку через crm.deal.add, разобрать ответ и понять, что пошло не так при ошибке.

Что нужно перед первым вызовом

Для первого запроса достаточно входящего вебхука с правом crm. Если его ещё нет — создайте в разделе «Разработчикам». Понадобится:

• URL вебхука вида https://портал.bitrix24.ru/rest/1/КОД/;
• имя метода, которое подставляется в URL;
• инструмент — curl, Postman или любой HTTP-клиент вашего языка.

Начинать всегда стоит с метода, который ничего не меняет. Идеальный кандидат — profile: он возвращает данные текущего пользователя и подтверждает, что доступ настроен.

Безопасный первый вызов: profile

Вызовем profile обычным GET-запросом:

curl "https://mycompany.bitrix24.ru/rest/1/xr9s7k3q0abcd12e/profile.json"

// Ответ
{
  "result": {
    "ID": "1",
    "NAME": "Иван",
    "LAST_NAME": "Петров",
    "ADMIN": true
  },
  "time": { "duration": 0.08 }
}

Получили result с данными — значит, вебхук и права в порядке. Если вместо этого пришла ошибка авторизации, проверьте правильность URL и кода вебхука.

GET, POST и передача параметров

Методы можно вызывать двумя способами. Простые запросы удобны через GET, но для вложенных структур (массивы полей) надёжнее POST с JSON.

В GET массивы кодируются квадратными скобками: ?filter[STAGE_ID]=NEW&select[]=ID&select[]=TITLE. В JSON — обычными массивами и объектами, что читаемее для сложных запросов.

Создаём сделку: crm.deal.add

Теперь изменим данные — создадим сделку методом crm.deal.add:

curl -X POST \
  "https://mycompany.bitrix24.ru/rest/1/xr9s7k3q0abcd12e/crm.deal.add.json" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "TITLE": "Первая сделка через API",
      "OPPORTUNITY": 25000,
      "CURRENCY_ID": "RUB",
      "STAGE_ID": "NEW"
    }
  }'

// Ответ
{ "result": 342, "time": { "duration": 0.34 } }

Число в result — ID новой сделки. Чтобы узнать доступные поля заранее, вызовите crm.deal.fields — метод вернёт описание всех полей с типами и признаком обязательности.

Тот же вызов на PHP

В боевом коде запрос обычно оборачивают в HTTP-клиент. Минимальный пример на PHP через cURL:

$webhook = 'https://mycompany.bitrix24.ru/rest/1/xr9s7k3q0abcd12e/';
$data = ['fields' => ['TITLE' => 'Сделка из PHP', 'OPPORTUNITY' => 5000]];

$ch = curl_init($webhook . 'crm.deal.add.json');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);

if (isset($response['error'])) {
    // разбор ошибки
} else {
    $dealId = $response['result'];
}

Разбор типовых ошибок

Первые вызовы часто спотыкаются об одни и те же ошибки:

Универсальный приём диагностики: сначала вызвать scope.json и имя_метода.fields, а уже потом отправлять данные. Это экономит часы на отладке.

Итог

Первый вызов метода Битрикс24 сводится к простой схеме: собрать URL из вебхука и имени метода, отправить GET или POST, проверить error и прочитать result. Начинайте с безопасного profile, затем переходите к crm.deal.add, а перед сложными запросами сверяйтесь с *.fields. Это фундамент, на котором строится любая интеграция.

Когда за первым вызовом стоит реальный бизнес-процесс — обмен заказами, синхронизация с 1С, воронка лидов — мы в B2Bsite доводим его до промышленного уровня: обработка ошибок, повторы, очереди и мониторинг.