REST: crm.deal.add и обновление сделки

Сделка — центральная сущность CRM Битрикс24. Методы crm.deal.add и crm.deal.update покрывают весь жизненный цикл: от создания заявки до смены стадии и закрытия. Разберём обязательные поля, воронку, привязку контактов и типовые ошибки интеграций.

Семейство методов сделки

Работа со сделками строится вокруг набора однотипных методов. Их стоит знать целиком, чтобы не изобретать обходные пути.

Отдельно стоит crm.deal.contact.items.set и родственные ему методы для управления списком контактов сделки. Начинать интеграцию всегда полезно с вызова crm.deal.fields: он покажет реальный состав полей именно вашего портала, включая обязательные и пользовательские UF_CRM_*.

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

Формально обязательных полей у сделки нет — можно создать её с пустым телом, и Битрикс проставит значения по умолчанию. На практике всегда передают заголовок, сумму, воронку и ответственного:

POST /rest/1/xxxxxx/crm.deal.add.json

{
  "fields": {
    "TITLE": "Заявка с сайта №5140",
    "CATEGORY_ID": 0,
    "STAGE_ID": "NEW",
    "OPPORTUNITY": 125000,
    "CURRENCY_ID": "RUB",
    "COMPANY_ID": 44,
    "CONTACT_ID": 88,
    "ASSIGNED_BY_ID": 12,
    "SOURCE_ID": "WEB",
    "UF_CRM_1687000000": "Промо-2026"
  },
  "params": { "REGISTER_SONET_EVENT": "Y" }
}

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

Ключевые поля и воронка

Стадия и воронка связаны жёстко. Поле CATEGORY_ID задаёт направление (воронку), а STAGE_ID — стадию внутри него. Для воронки по умолчанию (CATEGORY_ID = 0) стадии называются короткими кодами NEW, PREPARATION, WON, LOSE.

• В неосновных воронках стадия кодируется как C<categoryId>:<code>, например C3:NEW;
• OPPORTUNITY — сумма, CURRENCY_ID — валюта (по умолчанию базовая валюта портала);
• IS_MANUAL_OPPORTUNITY = Y отключает автопересчёт суммы по товарам;
• BEGINDATE и CLOSEDATE — плановые даты старта и закрытия.

crm.deal.update: изменение и смена стадии

Обновление всегда точечное: передавайте только те поля, которые меняете. Перевод сделки на следующую стадию — это просто смена STAGE_ID:

// crm.deal.update
{
  "id": 145,
  "fields": {
    "STAGE_ID": "PREPARATION",
    "OPPORTUNITY": 130000
  },
  "params": { "REGISTER_SONET_EVENT": "Y" }
}

При переводе в стадию из группы «Успех» Битрикс сам проставит CLOSED = Y и заполнит дату закрытия. Смена стадии через API запускает связанные роботы и триггеры автоматизации так же, как ручное перетаскивание карточки в канбане.

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

У сделки одна компания (COMPANY_ID) и, начиная с многоконтактной модели, произвольное число контактов. Для одного контакта достаточно поля CONTACT_ID, для нескольких используйте отдельные методы:

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

// crm.deal.contact.items.set
{
  "id": 145,
  "items": [
    { "CONTACT_ID": 88, "IS_PRIMARY": "Y" },
    { "CONTACT_ID": 91 }
  ]
}

Флаг IS_PRIMARY помечает основной контакт — именно он показывается в шапке карточки.

Пакетные операции и события

Создавать сделки по одной в цикле — путь к упору в лимиты REST. Метод batch объединяет до 50 команд в один HTTP-запрос и умеет подставлять результаты предыдущих команд через $result.

// batch: создать сделку и сразу дело
{
  "halt": 0,
  "cmd": {
    "deal": "crm.deal.add?fields[TITLE]=Импорт&fields[CATEGORY_ID]=0",
    "act":  "crm.activity.todo.add?ownerId=$result[deal]&ownerTypeId=2"
  }
}

Для реакции на изменения в реальном времени подписывайтесь на события ONCRMDEALADD, ONCRMDEALUPDATE и ONCRMDEALDELETE через event.bind. Это надёжнее опроса crm.deal.list по расписанию.

Итог

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

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