Эффективная интеграция и кастомизация функционала в Битрикс24 часто требует работы на уровне API. Сегодня мы подробно рассмотрим «Счета: Подробное руководство». Вы узнаете экспертные методики работы с битрикс и научитесь избегать типичных ошибок начинающих разработчиков.

Счета

[TOC]

>В Битрикс24 счёт — финальный этап процесса продаж. Когда сделка заключена, мы создаём счет и выставляем его клиенту для оплаты.

В данный момент, в Б24 существуют только «Новые счета», основанные на механизме смарт-процессов, в то время как «старые счета» уже не используются и говорить о них нецелесообразно. С другой же стороны — рассуждать контекстно-независимо о новых счетах тоже не имеет смысла, поскольку они основаны на механизме смарт-процессов. Здесь мы поговорим о различиях в работе между смарт-процессами и счетами и посмотрим несколько примеров использования унифицированного api.

Основное

С технической точки зрения счета являются сущностью основанной на смарт-процессах, однако все же нельзя сказать что это одно и то же. Мы будем исходить из позиции, что новые счета — это особый зафиксированный тип смарт-процесса со своими допущениями.

В работе со смарт-процессами все начинается с фабрики и чтобы получить фабрику, необходимо знать идентификатор типа сущности с которой мы хотим продолжить работу. Для счетов это \CCrmOwnerType::SmartInvoice или 31 (цифровое значение).

>Важно отметить что если для каких-то разработок вы используете динамическое определение сущности, то \CCrmOwnerType::isPossibleDynamicTypeId, который говорит о предположительном смарт-процессе вернет вам false. Так что если вы не обработаете эту ситуацию сами вы будете неприятно удивлены.

Говоря об идентификаторах сущностей надо сказать что счета получили полный набор уникальных значений:

• Идентификатор типа сущности (ENTITY_TYPE_ID) — \CCrmOwnerType::SmartInvoice (31)
• Идентификатор типа сущности для корзины (SPD) — \CCrmOwnerType::SuspendedSmartInvoice (32)
• Строковый код типа сущности (ENTITY_NAME) — \CCrmOwnerType::SmartInvoiceName (SMART_INVOICE)
• Строковый код типа сущности для корзины (ENTITY_NAME_SPD) — \CCrmOwnerType::SuspendedSmartInvoiceName (SUS_SMART_INVOICE)
• Короткое обозначения типа (ABBR) — \CCrmOwnerTypeAbbr::SmartInvoice (SI)
• Идентификатор для пользовательских полей (ENTITY_ID) — \Bitrix\Crm\Service\Factory\SmartInvoice::USER_FIELD_ENTITY_ID (CRM_SMART_INVOICE)
• Идентификатор для пользовательских полей в корзине (ENTITY_ID) — \Bitrix\Crm\Service\Factory\SmartInvoice::SUSPENDED_USER_FIELD_ENTITY_ID (CRM_SMART_INVOICE_SPD)
• Идентификатор ENTITY_ID для стадий формируется как SMART_INVOICE_STAGE_{categoryId}
• Префикс поля STATUS_ID для стадий формируется также, как для смарт-процессов — DT31_{categoryId}

Различия

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

Что касается направлений, то они в данный момент не используют направления. Несмотря на то что технически направления существуют и поддерживаются механикой смарт-процессов использовать их не следует. При работе подразумевайте что счета это элементам смарт-процесса, у которого в интерфейсе отключены направления.

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

Поскольку счета несут в себе бизнес-функцию и «наследуют» возможности старых счетов разработчики битрикса расширили класс-наследник DataManager дополнительными полями (через ORMв runtime).

При этом добавлены некоторые дополнительные поля:

• ACCOUNT_NUMBER — номер счета
• COMMENTS — html-поле с комментариями

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

Небольшой пример работы со счетами: создадим счет с определенными параметрами.

Плательщик: «ООО Ромашка» (ID:111),
Наше юр.лицо: «ООО Фьюжн» (ID:400), по реквизитам юридического лица (ID:444)
Дата выставления счета: 17 ноября 2022
Дата оплаты: до 24 ноября 2022
Сделка: «Продажа пестиков и тычинок в ООО Ромашка» (ID:555)

Товары:

• «Пестик» (1шт, 100.0 руб./шт.) (ID:222)
• «Тычинка» (2шт, 150.0 р/шт.) (ID:333)

Пример создания такого счета может выглядеть так:

use \Bitrix\Main,
	\Bitrix\Crm,
	\Bitrix\Crm\Service;

Main\Loader::requireModule('crm');

$factory = Service\Container::getInstance()
	->getFactory( \CCrmOwnerType::SmartInvoice );

$invoice = $factory->createItem([
	'BEGINDATE'       => '17.10.2022',
	'CLOSEDATE'       => '22.10.2022',
	'PARENT_ID_2'     => 555,
	'COMPANY_ID'      => 111,
	'MYCOMPANY_ID'    => 400,
	'MC_REQUISITE_ID' => 444,
	'COMMENTS'        => 'html comment here!',
]);

$productParseResult = $invoice->setProductRowsFromArrays([
	[
		'PRODUCT_NAME' => 'Пестик',
		'PRODUCT_ID' => '222',
		'PRICE' => 100,
		'QUANTITY' => 1,
	],
	[
		'PRODUCT_NAME' => 'Тычинка',
		'PRODUCT_ID' => '333',
		'PRICE' => 150,
		'QUANTITY' => 2,
	],
]);

if ( !$productParseResult->isSuccess() )
{
	// Something wrong with products - no add invoice
	return null;
}

$operation = $factory->getAddOperation($invoice);
$operationResult = $operation->launch();

if ( $operationResult->isSuccess() )
{
	// Invoice added. ID: $invoice->getId()
}
else
{
	var_dump($operationResult->getErrors());
}