Битрикс24: запуск бизнес-процессов через API

<?php
use Bitrix\Main\Loader;

Loader::includeModule('bizproc');
Loader::includeModule('crm');

$workflowTemplateId = 423;  // ID шаблона бизнес-процесса
$dealId = 962558;           // ID сделки

$errors = [];

$workflowId = \CBPDocument::StartWorkflow(
    $workflowTemplateId,
    ['crm', 'CCrmDocumentDeal', 'DEAL_' . $dealId],
    [
        // Параметры для процесса
        'phone' => '+79991234567',
    ],
    $errors
);

if (!empty($errors)) {
    foreach ($errors as $error) {
        echo "[{$error['code']}] {$error['message']}\n";
    }
} else {
    echo "Запущен процесс: {$workflowId}\n";
}

<?php

namespace Local\Bizproc;

use Bitrix\Main\Loader;

class WorkflowLauncher
{
    /**
     * Типы документов CRM
     */
    private const DOCUMENT_TYPES = [
        'deal' => ['crm', 'CCrmDocumentDeal', 'DEAL_'],
        'lead' => ['crm', 'CCrmDocumentLead', 'LEAD_'],
        'contact' => ['crm', 'CCrmDocumentContact', 'CONTACT_'],
        'company' => ['crm', 'CCrmDocumentCompany', 'COMPANY_'],
        'invoice' => ['crm', 'CCrmDocumentInvoice', 'INVOICE_'],
    ];

    public function __construct()
    {
        if (!Loader::includeModule('bizproc')) {
            throw new \RuntimeException('Модуль bizproc не установлен');
        }
        Loader::includeModule('crm');
    }

    /**
     * Запуск бизнес-процесса для сделки
     */
    public function startForDeal(int $templateId, int $dealId, array $params = []): WorkflowResult
    {
        return $this->start($templateId, 'deal', $dealId, $params);
    }

    /**
     * Запуск бизнес-процесса для лида
     */
    public function startForLead(int $templateId, int $leadId, array $params = []): WorkflowResult
    {
        return $this->start($templateId, 'lead', $leadId, $params);
    }

    /**
     * Запуск бизнес-процесса для контакта
     */
    public function startForContact(int $templateId, int $contactId, array $params = []): WorkflowResult
    {
        return $this->start($templateId, 'contact', $contactId, $params);
    }

    /**
     * Запуск бизнес-процесса для компании
     */
    public function startForCompany(int $templateId, int $companyId, array $params = []): WorkflowResult
    {
        return $this->start($templateId, 'company', $companyId, $params);
    }

    /**
     * Универсальный запуск процесса
     */
    public function start(int $templateId, string $entityType, int $entityId, array $params = []): WorkflowResult
    {
        if (!isset(self::DOCUMENT_TYPES[$entityType])) {
            throw new \InvalidArgumentException("Неизвестный тип сущности: {$entityType}");
        }

        $docType = self::DOCUMENT_TYPES[$entityType];
        $documentId = [$docType[0], $docType[1], $docType[2] . $entityId];

        $errors = [];
        
        $workflowId = \CBPDocument::StartWorkflow(
            $templateId,
            $documentId,
            $params,
            $errors
        );

        return new WorkflowResult($workflowId, $errors);
    }

    /**
     * Получение списка шаблонов БП для типа сущности
     */
    public function getTemplates(string $entityType): array
    {
        if (!isset(self::DOCUMENT_TYPES[$entityType])) {
            return [];
        }

        $docType = self::DOCUMENT_TYPES[$entityType];

        return \CBPWorkflowTemplateLoader::GetList(
            ['ID' => 'DESC'],
            [
                'DOCUMENT_TYPE' => $docType,
                'ACTIVE' => 'Y',
            ],
            false,
            false,
            ['ID', 'NAME', 'DESCRIPTION', 'MODIFIED']
        );
    }

    /**
     * Проверка статуса запущенного процесса
     */
    public function getWorkflowState(string $workflowId): ?array
    {
        $state = \CBPStateService::GetWorkflowState($workflowId);
        
        if (!$state) {
            return null;
        }

        return [
            'id' => $state['ID'],
            'template_id' => $state['WORKFLOW_TEMPLATE_ID'],
            'document_id' => $state['DOCUMENT_ID'],
            'state' => $state['STATE'],
            'state_title' => $state['STATE_TITLE'],
            'started' => $state['STARTED'],
            'modified' => $state['MODIFIED'],
        ];
    }

    /**
     * Остановка процесса
     */
    public function terminate(string $workflowId): bool
    {
        $errors = [];
        \CBPDocument::TerminateWorkflow($workflowId, [], $errors);
        
        return empty($errors);
    }
}

/**
 * Результат запуска процесса
 */
class WorkflowResult
{
    public readonly ?string $workflowId;
    public readonly array $errors;
    public readonly bool $success;

    public function __construct(?string $workflowId, array $errors)
    {
        $this->workflowId = $workflowId;
        $this->errors = $errors;
        $this->success = !empty($workflowId) && empty($errors);
    }

    public function getErrorMessages(): array
    {
        return array_map(
            fn($e) => "[{$e['code']}] {$e['message']}",
            $this->errors
        );
    }
}

<?php
use Bitrix\Main\EventManager;
use Local\Bizproc\WorkflowLauncher;

EventManager::getInstance()->addEventHandler(
    'crm',
    'OnAfterCrmDealAdd',
    function ($fields) {
        // Запускаем БП только для сделок из определённого источника
        if ($fields['SOURCE_ID'] !== 'WEB') {
            return;
        }

        $launcher = new WorkflowLauncher();
        
        $result = $launcher->startForDeal(
            423, // ID шаблона
            $fields['ID'],
            [
                'notify_manager' => true,
                'priority' => 'high',
            ]
        );

        if (!$result->success) {
            AddMessage2Log(
                "Ошибка запуска БП: " . implode(', ', $result->getErrorMessages()),
                'bizproc'
            );
        }
    }
);

<?php
// Обработчик входящего вебхука
$dealId = (int) $_POST['deal_id'];
$action = $_POST['action'] ?? '';

if ($action === 'approve') {
    $launcher = new WorkflowLauncher();
    
    $result = $launcher->startForDeal(
        450, // БП "Согласование"
        $dealId,
        [
            'approved_by' => $_POST['user_id'],
            'comment' => $_POST['comment'] ?? '',
        ]
    );

    echo json_encode([
        'success' => $result->success,
        'workflow_id' => $result->workflowId,
        'errors' => $result->getErrorMessages(),
    ]);
}

<?php
$launcher = new WorkflowLauncher();
$templates = $launcher->getTemplates('deal');

echo "Доступные бизнес-процессы для сделок:\n";
while ($template = $templates->Fetch()) {
    echo "  [{$template['ID']}] {$template['NAME']}\n";
}

$params = [
    'phone' => '+79991234567',        // Строка
    'amount' => 15000.50,             // Число
    'send_email' => true,             // Да/Нет
    'manager_ids' => [1, 5, 8],       // Множественное значение
    'deadline' => '2026-12-31',       // Дата
];