Сделки в CRM: обзор методов

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Сделка — один из ключевых объектов CRM, в ней:

  • можно управлять процессом продажи товара или услуги, включая отслеживание этапов и прием онлайн-платежей
  • ведется диалог с клиентом: звонки, письма, чаты открытых линий
  • вы можете просмотреть историю работы: дела, записи таймлайна

Быстрый переход: все методы и события

Пользовательская документация: сделки в Битрикс24

Связь сделок с другими объектами CRM

Клиент. Поле в карточке сделки, состоящее из связанных с ней компании и контактов. Все дела звонков, писем, чатов с контактом или компанией будут сохранены в карточке активной сделки. Компания в поле одна, обращение к ней происходит напрямую через поле сделки COMPANY_ID. Контактов может быть указано несколько, взаимодействие с ними ведется через отдельную группу методов crm.deal.contact.*.

Товары. Добавление, изменение, удаление товарных позиций в сделках возможно через группу методов crm.item.productrow.*.

Оплаты. Добавление, изменение, удаление документов оплаты в сделках возможно через группу методов crm.item.payment.*.

Воронки и стадии сделок

Для сделок можно создавать различные воронки продаж и управлять ими через группу методов crm.category.* entityTypeId сделки = 2.

В каждой воронке будут свои стадии. Ими можно управлять через группу методов справочников CRM — crm.status.*. ENTITY_ID статусов сделок оригинальный у каждого направления — DEAL_STAGE_xx.

Получить историю движения сделки по стадиям можно через метод crm.stagehistory.list.

Как изменить воронку сделки

Метод crm.deal.update может изменить только стадию сделки внутри текущей воронки. Если передать STAGE_ID, который не принадлежит текущей воронке, ничего не изменится.

Чтобы переместить сделку на стадию в другую воронку, используйте метод crm.item.update с параметрами:

  • entityTypeId2 для сделки,
  • idid сделки, которую перемещаете,
  • categoryIdid воронки, куда перемещаете сделку. Получить можно методом crm.category.list
  • stageIdid стадии в новой воронке. Получить можно методом crm.status.list
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"entityTypeId":2,"id":233,"fields":{"STAGE_ID":"EXECUTING","categoryId":0}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.item.update
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"entityTypeId":2,"id":233,"fields":{"STAGE_ID":"EXECUTING","categoryId":0},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.item.update
        
// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame, ISODate } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        // crm.item.update (rest-v2) returns the updated element under `item`; fields per
        // ../universal/crm-item-update.md
        // Shape of the payload returned in result (the `item` object below)
        type CrmItemUpdateResult = {
          item: {
            id: number
            entityTypeId: number
            title: string
            categoryId: number
            stageId: string
            assignedById: number
            opened: string
            opportunity: number
            currencyId: string
            createdTime: ISODate
            updatedTime: ISODate
          }
        }
        
        try {
          const response = await $b24.actions.v2.call.make<CrmItemUpdateResult>({
            method: 'crm.item.update',
            params: {
              entityTypeId: 2,
              id: 233,
              fields: {
                STAGE_ID: 'EXECUTING',
                categoryId: 0,
              },
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Updated item:', result.item.id, result.item.stageId)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }
        
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function updateDealStage() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'crm.item.update',
                params: {
                  entityTypeId: 2,
                  id: 233,
                  fields: {
                    STAGE_ID: 'EXECUTING',
                    categoryId: 0,
                  },
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Updated item:', result.item.id, result.item.stageId)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', updateDealStage)
        </script>
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'crm.item.update',
                    [
                        'entityTypeId' => 2,
                        'id' => 233,
                        'fields' => [
                            'STAGE_ID' => 'EXECUTING',
                            'categoryId' => 0
                        ]
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
            processData($result);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error updating item: ' . $e->getMessage();
        }
        
from b24pysdk.client import BaseClient
        from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        client: BaseClient
        
        try:
            bitrix_response = client.crm.item.update(
                bitrix_id=233,
                fields={
                    "STAGE_ID": "EXECUTING",
                    "categoryId": 0,
                },
                entity_type_id=2,
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Ошибка Bitrix API",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Ошибка Bitrix SDK: {error.message}")
        except Exception as error:
            print(f"Непредвиденная ошибка: {error}")
        
BX24.callMethod(
            "crm.item.update",
            {
                entityTypeId: 2,
                id: 233,
                fields:
                {
                    "STAGE_ID": "EXECUTING",
                    "categoryId": 0
                },
            },
            (result) => {
                result.error()
                    ? console.error(result.error())
                    : console.info(result.data());
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'crm.item.update',
            [
                'entityTypeId' => 2,
                'id' => 233,
                'fields' => [
                    'STAGE_ID' => 'EXECUTING',
                    'categoryId' => 0
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';
        

Карточка сделки

Основное рабочее пространство в сделке — это вкладка Общее ее карточки. Она состоит из двух частей:

  • левая, в ней располагаются поля с информацией. Если системных полей недостаточно, вы можете создать собственные пользовательские поля. Они позволяют хранить информацию в различных форматах данных: строка, число, ссылка, адрес и другие . Для создания, изменения, получения или удаления пользовательских полей сделок используется группа методов crm.deal.userfield.*

  • правая, в ней располагается таймлайн сделки. В нем можно создавать, редактировать, фильтровать, удалять дела CRM — группа методов crm.activity.*, и записи таймлайна — группа методов crm.timeline.*

Параметрами карточки сделки можно управлять в зависимости от воронки через группу методов crm.deal.details.configuration.*.

Виджеты

В карточку сделки можно встроить приложение. Благодаря встраиванию можно будет использовать приложение и не покидать карточку сделки.

Есть два сценария встройки:

Регулярные сделки

Автоматическое создание однотипных регулярных сделок по шаблонам. Для управлениям шаблонами используется группа методов crm.deal.recurring.*.

Обзор методов и событий

Scope: crm

Кто может выполнять метод: в зависимости от метода

Основные

Метод

Описание

crm.deal.add

Создает новую сделку

crm.deal.update

Изменяет сделку

crm.deal.get

Возвращает сделку по идентификатору

crm.deal.list

Возвращает список сделок по фильтру

crm.deal.delete

Удаляет сделку и все связанные с ней объекты

crm.deal.fields

Возвращает описание полей сделки

crm.deal.productrows.set

Добавляет товары в сделку

crm.deal.productrows.get

Возвращает товары сделки

Событие

Вызывается

onCrmDealAdd

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

onCrmDealUpdate

При изменении сделки

onCrmDealDelete

При удалении сделки

onCrmDealMoveToCategory

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

Регулярные сделки

Метод

Описание

crm.deal.recurring.add

Создает новую регулярную сделку

crm.deal.recurring.fields

Возвращает список полей шаблона регулярной сделки

crm.deal.recurring.expose

Создает новую сделку из шаблона

crm.deal.recurring.update

Изменяет существующие настройки для шаблона регулярной сделки

crm.deal.recurring.get

Получает поля настройки шаблона регулярной сделки по Id

crm.deal.recurring.list

Получает список настроек шаблонов регулярных сделок

crm.deal.recurring.delete

Удаляет существующие настройки для шаблона регулярной сделки

Событие

Вызывается

onCrmDealRecurringAdd

При создании новой регулярной сделки

onCrmDealRecurringUpdate

При изменении регулярной сделки

onCrmDealRecurringDelete

При удалении регулярной сделки

onCrmDealRecurringExpose

При создании новой сделки из регулярной сделки

Пользовательские поля

Метод

Описание

crm.deal.userfield.add

Создает новое пользовательское поле для сделок

crm.deal.userfield.update

Изменяет существующее пользовательское поле сделок

crm.deal.userfield.get

Получает пользовательское поле сделок по Id

crm.deal.userfield.list

Получает списка пользовательских полей сделок

crm.deal.userfield.delete

Удаляет пользовательское поле сделок

Событие

Вызывается

onCrmDealUserFieldAdd

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

onCrmDealUserFieldUpdate

При изменении пользовательского поля

onCrmDealUserFieldDelete

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

onCrmDealUserFieldSetEnumValues

При изменении набора значений для пользовательского поля списочного типа

Контакты сделки

Метод

Описание

crm.deal.contact.add

Добавляет контакт к сделке

crm.deal.contact.items.set

Добавляет несколько контактов к сделке

crm.deal.contact.fields

Возвращает поля связи сделка-контакт

crm.deal.contact.items.get

Получает набор контактов, связанных со сделкой

crm.deal.contact.delete

Удаляет контакт из указанной сделки

crm.deal.contact.items.delete

Удаляет набор контактов, связанных с указанной сделкой

Управление карточками сделок

Метод

Описание

crm.deal.details.configuration.get

Получает настройки карточки сделок

crm.deal.details.configuration.reset

Сбрасывает настроек карточки сделок

crm.deal.details.configuration.set

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

crm.deal.details.configuration.forceCommonScopeForAll

Принудительно устанавливает общую карточку сделок для всех пользователей

Предыдущая