REST 3.0: что нового

REST API Битрикс24 постепенно уходит от россыпи узких методов к единому универсальному интерфейсу. Ключевое направление — универсальные методы CRM crm.item.*, которые работают одинаково для сделок, лидов, контактов и смарт-процессов. Разберём, что меняется и как писать код «на вырост».

Почему API эволюционирует

Исторически в CRM для каждой сущности был свой набор методов: crm.deal.*, crm.lead.*, crm.contact.*, crm.company.*. Они похожи, но не идентичны — разные имена полей, нюансы поведения, дублирование логики в клиентском коде.

С появлением смарт-процессов (пользовательских типов CRM) такой подход перестал масштабироваться: для каждого нового типа сущности нельзя выпускать отдельный набор методов. Ответ — универсальный API, который работает с любой сущностью по её типу.

Универсальные методы crm.item

Семейство crm.item.* — единый CRUD для любой сущности CRM. Тип задаётся числовым параметром entityTypeId:

POST /rest/crm.item.add.json
{
  "entityTypeId": 2,
  "fields": {
    "title": "Сделка через универсальный API",
    "opportunity": 30000,
    "categoryId": 0
  }
}

Один и тот же метод создаёт сделку, лид или элемент смарт-процесса — меняется только entityTypeId. Это резко упрощает код, который работает с несколькими типами.

Единый стиль полей и camelCase

Универсальный API использует единообразные имена полей в camelCase (title, opportunity, assignedById) вместо разнородных UPPER_CASE старых методов. Это делает работу с разными сущностями предсказуемой.

• Единый набор системных полей — id, title, createdTime, updatedTime, assignedById и т. п.
• Пользовательские поля (userfield) доступны по их коду ufCrm....
• Метод crm.item.fields с параметром entityTypeId вернёт актуальную схему полей конкретного типа.

Перед интеграцией всегда запрашивайте crm.item.fields — состав полей зависит от настроек портала и созданных пользовательских полей.

Выборки: crm.item.list

Списочный метод crm.item.list заменяет разрозненные *.list и использует единый синтаксис фильтра, сортировки и выбора полей:

POST /rest/crm.item.list.json
{
  "entityTypeId": 2,
  "filter": { ">opportunity": 10000, "=categoryId": 0 },
  "select": ["id", "title", "opportunity", "stageId"],
  "order": { "id": "DESC" },
  "start": 0
}

Правила пагинации те же — 50 записей на страницу, навигация через start. Операторы фильтра (>, <, %, !) работают как в классическом API.

Batch и события остаются ядром

Универсальный API не отменяет базовых механизмов платформы — они по-прежнему обязательны для промышленных интеграций:

• batch — до 50 команд в одном запросе, включая универсальные методы; критично для массовых операций.
• События — offline-события (ONCRMDEALUPDATE и аналоги) и подписка через event.bind позволяют реагировать на изменения без опроса.
• Смарт-процессы — новые типы сущностей создаются в интерфейсе и сразу доступны через crm.item.* по их entityTypeId.

Как писать код на вырост

Практические рекомендации для новых интеграций:

1. Предпочитайте crm.item.* для CRM-сущностей — один код обслуживает сделки, лиды и смарт-процессы.
2. Не хардкодьте схему полей — запрашивайте её через crm.item.fields.
3. Оберните вызовы в слой абстракции, чтобы при переходе со старых методов не переписывать бизнес-логику.
4. Следите за документацией на apidocs.bitrix24.ru — набор методов и полей расширяется.

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

Итог

Развитие REST API Битрикс24 — это движение к универсальности: методы crm.item.* с параметром entityTypeId заменяют десятки узких методов и одинаково работают со сделками, лидами и смарт-процессами. Единый стиль полей в camelCase, запрос схемы через crm.item.fields и опора на batch и события — вот современный фундамент. Старые методы остаются, но новое стоит писать на универсальном слое.

Мы в B2Bsite проектируем интеграции с прицелом на развитие платформы: универсальный CRM API, слой абстракции над методами и аккуратный маппинг полей — чтобы решение не устаревало вместе со сменой поколений API.