Битрикс 24

Содержание:

• Действия
  • Получить список лидов
  • Получить лид по ID
  • Создать лид
  • Обновить (изменить) лид
  • Удалить лид
  • Получить список сделок
  • Получить сделку по ID
  • Создать сделку
  • Обновить (изменить) сделку
  • Удалить сделку
  • Привязать контакт к лиду
  • Привязать контакт к сделке
  • Получить список контактов
  • Получить контакт по ID
  • Создать контакт
  • Обновить (изменить) контакт
  • Удалить контакт
• Регулирование нагрузки на REST API Битрикс24
• Триггеры
  • Настройка исходящего вебхука в Битрикс24
  • Триггеры в APInita
• Подключение
  • Настройка входящего вебхука в Битрикс24
  • Создание подключения в APInita

Действия

Получить список лидов

Данное действие возвращает список существующих лидов. Возможно передать поля для фильтра (поиска).

Передаваемые значения:

• Сумма от;
• Сумма до;
• Дата создания от;
• Дата создания до;
• Статус только;
• Статус кроме;
• ID связанного контакта;
• Следующий пакет (при наличии ключа "next" в ответе на предыдущий запрос - передать полученное значение);
• Подключение (см. раздел "Подключение" ниже).

Получить лид по ID

Данное действие возвращает данные лида в виде массива.

Передаваемые значения:

• ID лида;
• Подключение (см. раздел "Подключение" ниже).

Создать лид

Данное действие создает новый лид.

Передаваемые значения:

• Название лида;
• Сумма;
• Комментарий;
• ID контакта (привязать существующий контакт к лиду);
• Имя;
• Телефон;
• E-mail;
• Подключение (см. раздел "Подключение" ниже).

Примечание: имя, телефон и E-mail являются полями лида и не создают сущность контакта.

Обновить (изменить) лид

Данное действие обновляет поля существующего лида. Пустые поля не передаются и не изменяют существующие значения.

Передаваемые значения:

• ID лида (обязательное);
• Название лида;
• Сумма;
• Комментарий;
• ID контакта (привязать существующий контакт к лиду);
• Имя;
• Телефон (добавится к имеющемуся);
• E-mail (добавится к имеющемуся);
• Подключение (см. раздел "Подключение" ниже).

Примечание: имя, телефон и E-mail являются полями лида и не создают сущность контакта.

Удалить лид

Данное действие производит удаление существующего лида.

Передаваемые значения:

• ID удаляемого лида;
• Подключение (см. раздел "Подключение" ниже).

Получить список сделок

Данное действие возвращает список существующих сделок. Возможно передать поля для фильтра (поиска).

Передаваемые значения:

• Сумма от;
• Сумма до;
• Дата создания от;
• Дата создания до;
• ID категории (воронки продаж);
• Стадия только;
• Стадия кроме;
• ID связанного контакта;
• Следующий пакет (при наличии ключа "next" в ответе на предыдущий запрос - передать полученное значение);
• Подключение (см. раздел "Подключение" ниже).

Получить сделку по ID

Данное действие возвращает данные сделки в виде массива.

Передаваемые значения:

• ID сделки;
• Подключение (см. раздел "Подключение" ниже).

Создать сделку

Данное действие создает новую сделку.

Передаваемые значения:

• Название сделки;
• Сумма;
• ID категории (воронки продаж), категория должна быть предварительно создана;
• Комментарий;
• ID контакта (привязать существующий контакт к сделке);
• Подключение (см. раздел "Подключение" ниже).

Обновить (изменить) сделку

Данное действие обновляет поля существующей сделки. Пустые поля не передаются и не изменяют существующие значения.

Передаваемые значения:

• ID сделки (обязательное);
• Название сделки;
• Сумма;
• ID категории (воронки продаж), категория должна быть предварительно создана;
• Комментарий;
• ID контакта (привязать существующий контакт к сделке);
• Подключение (см. раздел "Подключение" ниже).

Удалить сделку

Данное действие производит удаление существующей сделки.

Передаваемые значения:

• ID удаляемой сделки;
• Подключение (см. раздел "Подключение" ниже).

Привязать контакт к лиду

Данное действие привязывает существующий контакт к существующему лиду.

Передаваемые значения:

• ID лида;
• ID контакта;
• Подключение (см. раздел "Подключение" ниже).

Привязать контакт к сделке

Данное действие привязывает существующий контакт к существующей сделке.

Передаваемые значения:

• ID сделки;
• ID контакта;
• Подключение (см. раздел "Подключение" ниже).

Получить список контактов

Данное действие возвращает список существующих контактов. Возможно передать поля для фильтра (поиска).

Передаваемые значения:

• Имя;
• Фамилия;
• Отчество;
• Телефон;
• E-mail;
• Следующий пакет (при наличии ключа "next" в ответе на предыдущий запрос - передать полученное значение);
• Подключение (см. раздел "Подключение" ниже).

Получить контакт по ID

Данное действие возвращает данные контакта в виде массива.

Передаваемые значения:

• ID контакта;
• Подключение (см. раздел "Подключение" ниже).

Создать контакт

Данное действие создает новый контакт.

Передаваемые значения:

• Имя;
• Фамилия;
• Отчество;
• Телефон;
• E-mail;
• Подключение (см. раздел "Подключение" ниже).

Обновить (изменить) контакт

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

Передаваемые значения:

• ID контакта (обязательное);
• Имя;
• Фамилия;
• Отчество;
• Телефон (добавится к имеющемуся);
• E-mail (добавится к имеющемуся);
• Подключение (см. раздел "Подключение" ниже).

Удалить контакт

Данное действие производит удаление существующего контакта.

Передаваемые значения:

• ID удаляемого контакта;
• Подключение (см. раздел "Подключение" ниже).

Регулирование нагрузки на REST API Битрикс24

При разработке сценария интеграции, возможно, потребуется учесть, что облачный сервис Битрикс24 устанавливает лимиты на интенсивность запросов и ресурсоемкость выполняемых запросов.

Кратко об ограничении на интенсивность запросов: если выполняется больше 2 (для тарифа Энтерпрайз - 5) запросов в секунду, каждый запрос увеличивает значение счетчика. Как только значение счетчика превышает пороговое значение 50 (для тарифа Энтерпрайз - 250), каждый следующий входящий запрос блокируется. Приложение в ответ получает статус 429 с кодом ошибки QUERY_LIMIT_EXCEEDED. При отсутствии запросов счетчик уменьшается каждую секунду.

Кратко об ограничении на ресурсоемкость: данные о времени выполнения запросов к каждому отдельному методу суммируются. При превышении общего времени выполнения запросов сверх 480 секунд в рамках прошедших 10 минут данный отдельный метод блокируется для всех приложений и вебхуков данного портала.

Подробнее о работе ограничений можно узнать в документации Битрикс24.

Триггеры

Настройка исходящего вебхука в Битрикс24

Чтобы получать события об изменениях в Битрикс24, необходимо в настройках вашего аккаунта создать исходящий вебхук.

В разделе "Приложения -> Разработчикам" выберем пункт "Другое":

Далее выберем "Исходящий вебхук". Откроется окно создания/редактирования вебхука, где нужно выбрать события и вставить URL-адрес:

В поле "URL вашего обработчика" вставить URL, скопированный при создании в сценарии APInita общего модуля Webhook или триггера для сервиса Битрикс24.

Триггеры в APInita

Доступны следующие модули триггера:

• Лид создан;
• Лид обновлен;
• Лид создан или обновлен (совмещает 2 предыдущих);
• Сделка создана;
• Сделка обновлена;
• Сделка создана или обновлена (совмещает 2 предыдущих);
• Контакт создан;
• Контакт обновлен;
• Контакт создан или обновлен (совмещает 2 предыдущих).

Входящие данные содержат тип события в ключе "data.event" и ID созданной/обновленной сущности в ключе "data.FIELDS.ID".

Подключение

Настройка входящего вебхука в Битрикс24

Чтобы вносить изменения в систему Битрикс24 по API, необходимо в настройках аккаунта создать входящий вебхук с соответствующими правами. В разделе "Приложения -> Разработчикам" выберем пункт "Другое":

Далее выберем "Входящий вебхук". Откроется окно создания/редактирования, где нужно выбрать необходимые права (CRM), а также получить 3 значения:

URL-адрес в поле "Вебхук для вызова rest api" содержит следующие значения:

• user_subdomain - адрес вашего Битрикс24;
• webhook_secret - секретный код. С помощью этого кода можно просматривать, изменять и удалять данные в Битрикс24;
• user_id - идентификатор пользователя, который создал вебхук.

Скопируем эти значения в блокнот для настройки подключения в APInita (далее в инструкции).

Созданный вебхук находится в разделе "Интеграции":

Создание подключения в APInita

Создадим новое подключение:

Тип подключения: Custom;

user_subdomain, webhook_secret, user_id - значения, скопированные при создании входящего вебхука в системе Битрикс24.

Созданное подключение в дальнейшем доступно для выбора из редактора модуля в сценарии APInita.