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

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

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

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

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

Актуальная версия APIАктуальная версия API

Сделка — один из типов объектов CRM, поэтому ею управляют универсальные методы crm.item.* с entityTypeId = 2. Методы crm.deal.* остаются только для поддержки существующих интеграций.

В универсальных методах имена полей записываются в camelCase: TITLE превращается в title, ASSIGNED_BY_ID — в assignedById. Часть полей называется иначе: стадия STAGE_ID приходит в поле stageId, воронка CATEGORY_ID — в categoryId, а множественное поле CONTACT_IDS — в contactIds. Точный состав полей возвращает метод crm.item.fields с entityTypeId = 2.

Как начать работуКак начать работу

Порядок для новой разработки — на универсальных методах.

1. Получите описание полей сделки методом crm.item.fields с entityTypeId = 2 — он вернет системные и пользовательские поля с их типами
2. Узнайте доступные воронки методом crm.category.list с параметром entityTypeId = 2, а их стадии — методом crm.status.list с фильтром ENTITY_ID = DEAL_STAGE для воронки по умолчанию или DEAL_STAGE_<id воронки> для остальных
3. Создайте сделку методом crm.item.add: передайте entityTypeId = 2, название title, воронку categoryId, стадию stageId, сумму opportunity с валютой currencyId и клиента — компанию companyId или контакты contactIds
4. Добавьте товарные позиции группой методов crm.item.productrow.* с ownerType = D
5. Ведите сделку по стадиям и между воронками методом crm.item.update
6. Подпишитесь на события сделок, чтобы получать уведомления об изменениях в приложение

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

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

Товары. Товарные позиции сделки создает, изменяет и удаляет группа методов crm.item.productrow.*. Сделку в них указывают парой ownerType = D и ownerId с идентификатором сделки.

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

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

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

У каждой воронки свой набор стадий, ими управляет группа методов справочников CRM — crm.status.*. Стадии разных воронок лежат в разных справочниках: у воронки по умолчанию ENTITY_ID равен DEAL_STAGE, у остальных — DEAL_STAGE_<идентификатор воронки>, например DEAL_STAGE_5.

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

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

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

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

• entityTypeId — 2 для сделки
• id — идентификатор сделки, которую перемещаете
• categoryId — идентификатор воронки, куда перемещаете сделку. Получить можно методом crm.category.list
• stageId — идентификатор стадии в новой воронке. Получить можно методом 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>

from b24pysdk.errors import BitrixAPIError, BitrixSDKException

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}")

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();
}

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>';

Перемещение сделки вызывает событие onCrmDealMoveToCategory, а не onCrmDealUpdate. Пример запроса и разбор ответа есть на странице метода crm.item.update.

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

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

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

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

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

ВиджетыВиджеты

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

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

• использовать специальные места встраивания, например создать свою вкладку
• создать пользовательское поле, в которое загружается интерфейс вашего приложения

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

Однотипные сделки могут создаваться автоматически по шаблону с заданным периодом и количеством повторений. Шаблонами управляет группа методов crm.deal.recurring.*. Инструмент доступен не на всех тарифах Битрикс24, подробности — на странице регулярных сделок.

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

Scope: crm

Кто может выполнять метод: в зависимости от метода — методы сделок проверяют права доступа к сделкам, а создание, изменение и удаление пользовательских полей доступно только администратору CRM. Подписаться на события может любой пользователь

ОсновныеОсновные

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

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

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

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