Розробка модуля генерації документів 1С-Бітрікс під ключ

Розробка модуля генерації документів 1С-Бітрікс

Типова ситуація: оператор CRM витрачає 10 хвилин на формування рахунку в Word, копіюючи дані із замовлення — помиляється в ставці ПДВ, і документ іде клієнту. Або інтернет-магазин генерує сотні накладних на день через phpWord, а при зміні логотипу правити кожну. Законодавство вимагає правильної фіскалізації, помилка в реквізитах — штраф до 50 000 грн. Ми розробляємо модуль для Бітрікс, який системно вирішує ці проблеми: шаблони, змінні, версіонування, автоматична генерація за подіями.

Які проблеми вирішує автоматизація документів?

• Помилки в документах: не той ІПН, невірна сума, пропущена ставка ПДВ. Ручне введення призводить до 30% помилок. Автоматизація з модулем зменшує кількість помилок у документах в 5 разів: дані тягнуться безпосередньо із замовлення або угоди через провайдери.
• Повільна генерація: менеджер витрачає 5–10 хвилин на один документ. При 200 замовленнях на день це понад 30 годин роботи. При середній ставці менеджера 300 грн/год це економія до 9 000 грн на місяць. Наприклад, компанія з 10 менеджерами може заощадити до 30 000 грн на місяць на ручному формуванні документів. Автоматизація зводить генерацію до 200–500 мс на документ — в 100 разів швидше ручного формування.
• Неузгодженість шаблонів: у Word-документах різних відділів різні шрифти, відступи, колонтитули. Модуль централізує шаблони з версіонуванням — зміни застосовуються одразу до всіх нових документів.
• Невідповідність вимогам: відсутність обов'язкових полів (КПП, ОКТМО, QR-код для податкової). Налаштування змінних та валідація шаблонів виключають такі пропуски.

Як працює модуль генерації документів?

Модуль vendor.docgen використовує чотири ORM-таблиці:

• b_vendor_docgen_template — шаблони документів: id, name, type (order/contract/act/offer), format (docx/pdf), template_file, variables_schema, version, is_active
• b_vendor_docgen_document — згенеровані документи: id, template_id, entity_type, entity_id, file_id (у b_file), status, generated_at, generated_by
• b_vendor_docgen_variable — зареєстровані змінні: name, source_class, description

Кожен шаблон містить JSON-схему змінних — модуль валідує, що всі обов'язкові поля присутні.

Система змінних

Змінні обгорнуті в {{....}}. Підстановка виконується через провайдери даних, які реєструються в налаштуваннях модуля. Приклад провайдера для замовлення:

class OrderVariableProvider implements VariableProviderInterface { public function getVariables(int $entityId): array { $order = \Bitrix\Sale\Order::load($entityId); $props = $order->getPropertyCollection(); return [ 'ORDER_NUMBER' => $order->getField('ACCOUNT_NUMBER'), 'ORDER_DATE' => $order->getDateInsert()->format('d.m.Y'), 'ORDER_SUM' => number_format($order->getPrice(), 2, ',', ' '), 'ORDER_CURRENCY' => $order->getCurrency(), 'CLIENT_NAME' => $props->getPayerName(), 'CLIENT_INN' => $props->getUserProp('INN')?->getValue(), 'CLIENT_ADDRESS' => $props->getAddress(), 'ITEMS_TABLE' => $this->buildItemsTable($order->getBasket()), ]; } } 

Провайдерів можна писати під будь-які сутності: угоди CRM, ліди, користувацькі профілі. Типовий шаблон містить 20–30 змінних, модуль не обмежує кількість.

Переваги Twig перед простою заміною

Проста заміна str_replace ламається при вкладених даних і таблицях. Twig дає цикли, умови, фільтри. Приклад HTML-шаблону:

<h1>Рахунок № {{ORDER_NUMBER}}</h1> <table> {% for item in ITEMS %} <tr> <td>{{ item.name }}</td> <td>{{ item.quantity }}</td> <td>{{ item.price|number_format(2, ',', ' ') }}</td> </tr> {% endfor %} </table> 

Twig компілюється в кеш — продуктивність на рівні ручної заміни, а підтримувати шаблони в 10 разів простіше. Детальніше — у документації Twig та Wikipedia.

Налаштування шаблонів DOCX та HTML

Для Word-шаблонів використовуємо PhpWord з клонуванням рядків таблиць:

$templateProcessor = new \PhpOffice\PhpWord\TemplateProcessor($templatePath); foreach ($variables as $name => $value) { if (is_array($value)) { $templateProcessor->cloneRow('ITEM_NAME', count($value)); foreach ($value as $i => $item) { $templateProcessor->setValue("ITEM_NAME#{$i}", $item['name']); $templateProcessor->setValue("ITEM_QTY#{$i}", $item['quantity']); $templateProcessor->setValue("ITEM_PRICE#{$i}", $item['price']); } } else { $templateProcessor->setValue($name, htmlspecialchars($value)); } } $outputPath = '/upload/vendor_docgen/' . uniqid() . '.docx'; $templateProcessor->saveAs($outputPath); 

Як обрати конвертер PDF?

DOCX генерується швидко, але клієнт часто хоче PDF. Конвертація — найболісніше місце. Порівняння способів:

$loader = new \Twig\Loader\ArrayLoader(['doc' => $template['HTML_TEMPLATE']]); $twig = new \Twig\Environment($loader); $html = $twig->render('doc', $variables); $mpdf = new \Mpdf\Mpdf(['mode' => 'utf-8', 'format' => 'A4']); $mpdf->WriteHTML($html); $mpdf->Output($outputPath, 'F'); 

AddEventHandler('sale', 'OnSaleOrderPaid', ['\Vendor\DocGen\EventHandler', 'onOrderPaid']); class EventHandler { public static function onOrderPaid(\Bitrix\Main\Event $event): void { $orderId = $event->getParameter('id'); DocGenerator::generate('invoice', 'sale_order', $orderId); } }