Переход на новые методы CRM

Эта страница помогает перенести интеграцию с методов CRM предыдущей версии API на REST 3.0: найти аналог каждого метода, учесть, чего в REST 3.0 пока нет, и обновить формат запросов и ответов.

Порядок переходаПорядок перехода

1. Найдите аналоги методов, которые использует интеграция, по правилам из раздела Как найти аналог метода. Если задачи нет в REST 3.0, оставьте этот вызов в предыдущей версии: такие задачи перечислены в разделе Чего пока нет в REST 3.0
2. Замените адрес вызова: /rest/ на /rest/api/. Имя метода для сделок, лидов, контактов, компаний и предложений остается тем же, для смарт-процессов и счетов меняется на crm.<тип>.<действие>, например crm.smartprocess1038.add
3. Переименуйте поля в camelCase: TITLE → title, STAGE_ID → stageId. Названия полей каждого типа есть на страницах полей, например Поля сделки
4. Перечислите нужные поля в параметре select. Без него методы get и list возвращают только id
5. Обновите обработку ответа и ошибок: данные приходят в объекте result, ошибки — в объекте error с кодом и текстом. Формат описан в обзоре REST 3.0
6. Проверьте новые вызовы на тестовых данных до переключения рабочего сценария

Пример: создание сделкиПример: создание сделки

В предыдущей версии поля передаются в верхнем регистре, метод возвращает идентификатор числом.

curl -X POST \
-H "Content-Type: application/json" \
-d '{"FIELDS":{"TITLE":"Заявка на закупку","ASSIGNED_BY_ID":1,"OPPORTUNITY":150000,"CURRENCY_ID":"RUB"}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.deal.add

{
    "result": 9021
}

В REST 3.0 такой же вызов идет по адресу /rest/api/, поля передаются в camelCase, идентификатор приходит в объекте result.

curl -X POST \
-H "Content-Type: application/json" \
-d '{"fields":{"title":"Заявка на закупку","assignedById":1,"opportunity":150000,"currencyId":"RUB"}}' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/crm.deal.add

{
    "result": {
        "id": 9023
    }
}

Как найти аналог методаКак найти аналог метода

Методы сделок, лидов, контактов, компаний и предложений. Имя метода в REST 3.0 то же, меняется только адрес вызова. Например, crm.deal.add, crm.deal.get, crm.deal.list, crm.deal.update и crm.deal.delete есть в обеих версиях, как и методы add, get, list, update и delete лидов, контактов, компаний и предложений.

Универсальные методы crm.item.*. В REST 3.0 тип объекта входит в имя метода, поэтому параметр entityTypeId не нужен. Например, crm.item.add с entityTypeId: 2 становится методом crm.deal.add, а crm.item.list с entityTypeId: 1038 — методом crm.smartprocess1038.list. Товарные позиции элемента тоже получают тип в имени: crm.item.productrow.add для сделки становится crm.deal.productrow.add. Сегменты всех типов перечислены в обзоре CRM.

Остальные методы называются в REST 3.0 иначе. Они собраны в таблице. Для примера в таблице взяты методы сделки, а для реквизитов и адресов — методы компании. У других типов объектов вместо deal или company в имени стоит их сегмент: crm.lead.field.list, crm.contact.requisite.add.

Чего пока нет в REST 3.0Чего пока нет в REST 3.0

Для этих задач оставьте вызовы предыдущей версии по адресу /rest/.

Чем REST 3.0 отличается от предыдущей версииЧем REST 3.0 отличается от предыдущей версии

• Одна схема для всех типов. Методы crm.<тип>.* устроены одинаково для сделок, лидов, контактов, компаний, предложений, счетов и смарт-процессов. Отличаются только набор групп и поля типа
• Имена полей в camelCase. Стадия сделки — поле stageId, а не STAGE_ID. Пользовательские поля сохраняют имена вида UF_CRM_…
• Поля задаются явно. Без select методы crm.<тип>.get и crm.<тип>.list возвращают только id элемента. В select можно запросить поля связанных объектов через точку, например assignedBy.lastName или stage.name. У вложенных групп правила select свои — они описаны на страницах методов
• Новый формат фильтра и навигации. Параметры filter, order и pagination устроены по общим правилам REST 3.0. Метод crm.<тип>.list по умолчанию возвращает 50 элементов, максимум — 1000. У списочных методов вложенных групп фильтр, как правило, требует условия по владельцу, например ownerId, а лимит страницы может быть меньше
• Описание полей у каждой группы. У каждой группы методов есть свои field.get и field.list, например crm.deal.productrow.field.list возвращает поля товарной позиции

Формат параметров и ответов описан в обзоре REST 3.0: выбор полей и связанных объектов, фильтрация, сравнение со старой версией.