REST: crm.dealcategory.stage

Направления сделок (воронки) в Битрикс24 — это отдельные пайплайны со своим набором стадий. Метод crm.dealcategory.stage.list возвращает стадии конкретного направления, что необходимо для корректной установки поля STAGE_ID при создании и перемещении сделок из внешних систем.

Направления, стадии и статусы

Чтобы не запутаться, разведём три понятия. Направление (dealcategory / category) — это воронка. Стадия — этап внутри воронки. Статус — запись в справочнике, которой стадия физически хранится в CRM.

Метод crm.dealcategory.stage.list

Метод принимает единственный обязательный параметр — id направления — и возвращает упорядоченный список стадий с их идентификаторами и цветами семафора (успех/провал/в работе).

POST /rest/1/xxxxxxxx/crm.dealcategory.stage.list.json
{ "id": 3 }

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

{
  "result": [
    { "STATUS_ID": "C3:NEW",       "NAME": "Новая",        "SORT": 10, "SEMANTICS": null },
    { "STATUS_ID": "C3:PREPARATION","NAME": "В работе",     "SORT": 20, "SEMANTICS": null },
    { "STATUS_ID": "C3:WON",       "NAME": "Сделка успешна","SORT": 30, "SEMANTICS": "S" }
  ]
}

Значение STATUS_ID из этого ответа и есть то, что нужно передавать в поле STAGE_ID сделки.

Как устроен идентификатор стадии

Идентификатор стадии зависит от направления и имеет префикс воронки. Это ключевой момент, из-за которого чаще всего ломаются интеграции.

• Для воронки по умолчанию (ID 0) стадии выглядят просто: NEW, PREPARATION, WON, LOSE;
• Для дополнительной воронки с ID 3 стадии получают префикс C3:, например C3:NEW;
• Поле SEMANTICS помечает финальные стадии: S — успех, F — провал.

Перемещение сделки по стадиям

Смена стадии — это обычное обновление поля STAGE_ID у сделки. Важно, чтобы у сделки был согласован CATEGORY_ID (направление) и STAGE_ID (стадия из этого направления).

POST /rest/1/xxxxxxxx/crm.deal.update.json
{
  "id": 340,
  "fields": { "CATEGORY_ID": 3, "STAGE_ID": "C3:PREPARATION" }
}

Если сделка переносится в другую воронку, меняйте CATEGORY_ID и STAGE_ID одновременно. Перемещение сделки на финальную стадию (SEMANTICS = S/F) может запускать роботов и триггеры автоматизации — учитывайте это при массовых обновлениях.

Отдельно проговорим создание сделки сразу в нужной воронке. Если при crm.deal.add указать только STAGE_ID без CATEGORY_ID, сделка попадёт в воронку по умолчанию, а стадия с префиксом другой воронки будет отвергнута. Поэтому в интеграциях, где заявки распределяются по нескольким направлениям, всегда передавайте оба поля вместе. При массовой миграции сделок из старой системы разумно сначала завести направления и зафиксировать соответствие «внешняя воронка → CATEGORY_ID», а уже затем — соответствие стадий, иначе часть сделок молча уедет в дефолтную воронку.

Воронка по умолчанию и вспомогательные методы

Чтобы узнать, какая воронка используется по умолчанию, есть отдельные методы:

• crm.dealcategory.default.get — параметры воронки по умолчанию;
• crm.dealcategory.status — служебный ENTITY_ID справочника статусов для направления (пригодится для прямой работы с crm.status.list);
• crm.dealcategory.add / update / delete — управление самими направлениями.

Связка выглядит так: crm.dealcategory.status отдаёт entityId вида DEAL_STAGE_3, который затем можно передать в crm.status.list и получить те же стадии на низком уровне справочника. Это удобно, когда нужна унифицированная работа со всеми справочниками CRM.

Кеширование и производительность

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

1. Один раз при старте синхронизации получите стадии всех нужных направлений и сложите в словарь CATEGORY_ID → { человекочитаемое имя → STATUS_ID };
2. Далее сопоставляйте статусы внешней системы с STATUS_ID из кеша;
3. Обновляйте кеш по расписанию или по событию изменения справочника.

Такой подход снижает число REST-вызовов и экономит лимиты API. Не забывайте, что все методы списка поддерживают постраничность, а массовые обновления сделок эффективнее выполнять через batch.

Стоит также предусмотреть сценарий, когда в справочнике появляется новая стадия, которой ещё нет во внешней системе. Хорошая интеграция не падает на неизвестном STATUS_ID, а логирует расхождение и, при необходимости, сигнализирует администратору. Аналогично при удалении стадии в Битрикс24 сделки на ней автоматически не переносятся — их нужно переводить заранее, иначе внешняя синхронизация будет получать ссылки на несуществующую стадию. Проверять актуальность справочника удобно по событию его изменения либо периодическим сравнением закешированного набора с ответом crm.dealcategory.stage.list.

Итог

Правильная работа со стадиями сделок сводится к трём вещам: получить актуальные стадии направления через crm.dealcategory.stage.list, использовать полный STATUS_ID с префиксом воронки и держать CATEGORY_ID согласованным со стадией. Игнорирование префикса — самая частая причина «пропавших» сделок в интеграциях.

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