CRM / Стадии и воронки | Битрикс дилетант

Общее понимание

Перед переносом карточек важно понять, из какой воронки взята стадия.

CATEGORY_ID и STAGE_ID

Поле	Что означает
`CATEGORY_ID`	Воронка или направление.
`STAGE_ID`	Стадия внутри воронки.
`STAGE_SEMANTIC_ID`	Смысловая группа стадии: в работе, успешная, провальная.

Для общей воронки сделок справочник стадий обычно DEAL_STAGE. Для воронки с ID 10 — DEAL_STAGE_10.

Стадии сделок

Сделки могут иметь несколько воронок. У каждой воронки свой набор стадий.

/**
 * Получает код справочника стадий сделки.
 */
function buildDealStageEntityId(int $category_id): string
{
    if ($category_id <= 0) {
        return 'DEAL_STAGE';
    }

    return 'DEAL_STAGE_' . $category_id;
}

$stage_entity_id = buildDealStageEntityId($category_id);

Стадии смарт-процессов

Для смарт-процессов удобнее получать стадии через фабрику. Так не нужно вручную собирать код справочника стадий.

Получение

Базовые способы получить воронки и стадии через PHP.

Получить воронки сделок

<?php

use Bitrix\Main\Loader;
use Bitrix\Crm\Category\DealCategory;

Loader::includeModule('crm');

/**
 * Получает список воронок сделок.
 */
function fetchDealCategories(): array
{
    $categories = [];

    $category_result = DealCategory::getList([
        'select' => [
            'ID',
            'NAME',
            'SORT',
            'IS_LOCKED',
        ],
        'order' => [
            'SORT' => 'ASC',
            'ID' => 'ASC',
        ],
    ]);

    while ($category = $category_result->fetch()) {
        $categories[] = $category;
    }

    return $categories;
}

$categories = fetchDealCategories();

print_r($categories);

Нулевая воронка — основная. В некоторых старых методах она может обрабатываться отдельно, поэтому её лучше учитывать явно.

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

<?php

use Bitrix\Main\Loader;
use Bitrix\Crm\Category\DealCategory;

Loader::includeModule('crm');

/**
 * Получает стадии воронки сделки.
 */
function fetchDealCategoryStages(int $category_id): array
{
    return DealCategory::getStageList($category_id);
}

$stages = fetchDealCategoryStages($category_id);

print_r($stages);

Получить стадии через StatusTable

Стадии CRM также можно читать из справочника статусов.

<?php

use Bitrix\Main\Loader;
use Bitrix\Crm\StatusTable;

Loader::includeModule('crm');

/**
 * Получает элементы справочника стадий.
 */
function fetchStageStatuses(string $entity_id): array
{
    $statuses = [];

    $status_result = StatusTable::getList([
        'select' => [
            'ID',
            'ENTITY_ID',
            'STATUS_ID',
            'NAME',
            'SORT',
            'SEMANTICS',
        ],
        'filter' => [
            '=ENTITY_ID' => $entity_id,
        ],
        'order' => [
            'SORT' => 'ASC',
        ],
    ]);

    while ($status = $status_result->fetch()) {
        $statuses[] = $status;
    }

    return $statuses;
}

$statuses = fetchStageStatuses('DEAL_STAGE');

print_r($statuses);

Изменение стадии

Стадию лучше менять через операцию фабрики, чтобы сработала CRM-логика.

Перевести сделку на стадию

<?php

use Bitrix\Main\Loader;
use Bitrix\Crm\Service;

const CRM_DEAL_TYPE_ID = \CCrmOwnerType::Deal;

Loader::includeModule('crm');

/**
 * Переводит сделку в другую воронку и стадию.
 */
function moveDealToCategoryStage(int $deal_id, int $category_id, string $stage_id): array
{
    $factory = Service\Container::getInstance()->getFactory(CRM_DEAL_TYPE_ID);

    if ($factory === null) {
        return [
            'is_success' => false,
            'error_messages' => ['Фабрика сделок не найдена'],
        ];
    }

    $deal_item = $factory->getItem($deal_id);

    if ($deal_item === null) {
        return [
            'is_success' => false,
            'error_messages' => ['Сделка не найдена'],
        ];
    }

    $deal_item->set('CATEGORY_ID', $category_id);
    $deal_item->setStageId($stage_id);

    $operation = $factory->getUpdateOperation($deal_item);
    $operation_result = $operation->launch();

    return [
        'is_success' => $operation_result->isSuccess(),
        'error_messages' => $operation_result->getErrorMessages(),
    ];
}

$result = moveDealToCategoryStage($deal_id, $category_id, $stage_id);

print_r($result);

Перевести элемент смарт-процесса

<?php

use Bitrix\Main\Loader;
use Bitrix\Crm\Service;

const SMART_PROCESS_ENTITY_TYPE_ID = 1044;

Loader::includeModule('crm');

/**
 * Переводит элемент смарт-процесса на стадию.
 */
function moveSmartProcessItemToStage(int $entity_type_id, int $item_id, string $stage_id): array
{
    $factory = Service\Container::getInstance()->getFactory($entity_type_id);

    if ($factory === null) {
        return [
            'is_success' => false,
            'error_messages' => ['Фабрика смарт-процесса не найдена'],
        ];
    }

    $item = $factory->getItem($item_id);

    if ($item === null) {
        return [
            'is_success' => false,
            'error_messages' => ['Элемент не найден'],
        ];
    }

    $item->setStageId($stage_id);

    $operation = $factory->getUpdateOperation($item);
    $operation_result = $operation->launch();

    return [
        'is_success' => $operation_result->isSuccess(),
        'error_messages' => $operation_result->getErrorMessages(),
    ];
}

$result = moveSmartProcessItemToStage(
    SMART_PROCESS_ENTITY_TYPE_ID,
    $item_id,
    $stage_id
);

print_r($result);