REST: работа со сделками (crm.deal)

Сделка (crm.deal) — центральная сущность продаж в Битрикс24. Через семейство методов crm.deal.* внешняя система создаёт продажи, двигает их по воронке, связывает с клиентами и наполняет товарами. Разберём практику работы с этими методами.

Обзор методов crm.deal

Сделка агрегирует вокруг себя клиента, товары, документы и активности, поэтому её API шире, чем у лида. Базовый набор повторяет CRUD-логику остальных сущностей, но у сделки есть уникальные под-семейства для товаров и привязок. На практике интеграция редко ограничивается созданием записи: обычно нужно ещё связать сделку с контактом, добавить товары и провести её по стадиям, поэтому важно заранее понимать всю карту методов.

Создание сделки: crm.deal.add

Минимально сделке нужны название и, как правило, стадия и сумма. Пример:

{ "fields": { "TITLE": "Заказ №1024", "CATEGORY_ID": 0, "STAGE_ID": "NEW", "OPPORTUNITY": 120000, "CURRENCY_ID": "RUB", "CONTACT_ID": 45, "COMPANY_ID": 12, "ASSIGNED_BY_ID": 1, "BEGINDATE": "2026-07-16" }, "params": { "REGISTER_SONET_EVENT": "Y" } }

Наиболее востребованные поля:

• TITLE — название (обязательное);
• CATEGORY_ID — направление (воронка); 0 — воронка по умолчанию;
• STAGE_ID — стадия внутри выбранного направления;
• OPPORTUNITY / CURRENCY_ID — сумма и валюта;
• CONTACT_ID, COMPANY_ID — клиент.

Если не передать STAGE_ID, сделка встанет на первую стадию выбранного направления. Не передав CATEGORY_ID, вы попадёте в воронку по умолчанию. Дату начала и ожидаемую дату закрытия задают поля BEGINDATE и CLOSEDATE; если их не указать, система проставит значения автоматически на основе настроек воронки.

Стадии и воронки сделки

Стадии сделок хранятся в справочнике статусов и зависят от направления. Чтобы получить стадии основной воронки: crm.status.list с фильтром { "filter": { "ENTITY_ID": "DEAL_STAGE" } }. Для направления N — ENTITY_ID равно DEAL_STAGE_N.

Каждая стадия несёт признак семантики SEMANTICS:

Список направлений отдаёт crm.category.list с параметром entityTypeId: 2 (тип «сделка»).

Выборка сделок и фильтры

Как и везде в CRM, crm.deal.list возвращает 50 записей и управляется через filter, select, order, start.

Пример выборки открытых сделок дороже 50 000 руб.:

{ "filter": { "CLOSED": "N", ">OPPORTUNITY": 50000, "CATEGORY_ID": 0 }, "select": ["ID","TITLE","STAGE_ID","OPPORTUNITY"], "order": { "OPPORTUNITY": "DESC" } }

Фильтр поддерживает вложенную логику: несколько условий объединяются по И, а массивы значений с префиксом @ дают выборку по нескольким стадиям сразу. Важно помнить, что по умолчанию crm.deal.list возвращает сделки только из воронки по умолчанию — чтобы получить сделки конкретного направления, явно указывайте CATEGORY_ID в фильтре.

Привязка контактов и компаний

Компания у сделки одна (COMPANY_ID), а контактов может быть несколько. Для множественной привязки контактов есть отдельное под-семейство:

• crm.deal.contact.add — добавить контакт к сделке;
• crm.deal.contact.items.get — получить список привязанных контактов;
• crm.deal.contact.items.set — заменить весь набор контактов;
• crm.deal.contact.delete — отвязать контакт.

Пример массовой установки контактов: crm.deal.contact.items.set с телом { "id": 1024, "items": [ { "CONTACT_ID": 45 }, { "CONTACT_ID": 46, "IS_PRIMARY": "Y" } ] }.

Флаг IS_PRIMARY помечает основной контакт, который отображается в карточке первым. Аналогичное под-семейство есть у компании (crm.deal.company.* отсутствует, зато компания задаётся полем COMPANY_ID напрямую). Если внешняя система шлёт клиента строкой, сначала найдите или создайте контакт, получите его ID, и только потом привязывайте к сделке — прямая передача имени в сделку клиента не создаст.

Массовые операции через batch

Когда нужно создать десятки сделок или обновить их пачкой, вместо отдельных HTTP-запросов используйте метод batch — до 50 команд за раз.

В batch можно ссылаться на результаты предыдущих команд через синтаксис $result[имя_команды]. Это позволяет в одном запросе создать контакт и тут же прикрепить к нему сделку.

Ответ batch содержит секции result_result, result_error и result_total, так что успех и ошибки каждой команды можно разобрать по отдельности. Это удобно для идемпотентной синхронизации: команды, завершившиеся ошибкой, вы повторяете, а успешные — пропускаете. Для по-настоящему больших миграций batch комбинируют с очередью на стороне интеграции, чтобы контролировать темп и не упираться в дневные лимиты портала.

Итог

Методы crm.deal.* дают полный контроль над продажами: создание, движение по стадиям выбранной воронки, привязка клиентов, наполнение товарами и массовые операции. Главное — правильно сопоставлять STAGE_ID с CATEGORY_ID и не упираться в лимиты при пакетной загрузке.

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