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

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

Генерація документів — рахунків, актів, договорів, накладних — зустрічається в кожному другому проєкті на Бітрікс. Стандартних інструментів для цього немає: ні в sale, ні в crm. Завдання зазвичай вирішують «на коліні» через phpWord або взагалі вручну. Модуль дає системний підхід: шаблони, змінні, версіонування, підписи.

Де це потрібно

Типові сценарії: автоматичний рахунок після оформлення замовлення в інтернет-магазині, договір при реєстрації користувача в B2B-розділі, акт виконаних робіт по закритій угоді CRM, комерційна пропозиція для менеджера. У кожному випадку документ має формуватися миттєво, містити актуальні дані і виглядати професійно.

Архітектура модуля

Модуль vendor.docgen із наступними таблицями:

• 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

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

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

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

Провайдери реєструються в налаштуваннях модуля та автоматично підставляються при генерації залежно від типу документа.

Генерація DOCX

Шаблони 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. Конвертація — найболючіше місце. Варіанти:

• LibreOffice у headless-режимі: libreoffice --headless --convert-to pdf file.docx — найкраща якість, потребує встановлення на сервер
• PhpSpreadsheet + mPDF — для документів на основі HTML-шаблонів, простіше керувати стилями
• DocRaptor / PDF Rocket — хмарні сервіси, не потребують ПЗ на сервері

Вибір конвертора — параметр у налаштуваннях модуля. За замовчуванням: mPDF для HTML-шаблонів, LibreOffice для DOCX.

HTML-шаблони

Альтернатива Word-шаблонам — HTML із CSS. Простіше підтримувати, немає проблем із кодуваннями. Шаблон зберігається прямо в b_vendor_docgen_template у полі html_template, змінні підставляються через простий пошук-заміну або через Twig:

$loader = new \Twig\Loader\ArrayLoader(['doc' => $template['HTML_TEMPLATE']]);
$twig = new \Twig\Environment($loader);
$html = $twig->render('doc', $variables);

// Конвертація в PDF через mPDF
$mpdf = new \Mpdf\Mpdf(['mode' => 'utf-8', 'format' => 'A4']);
$mpdf->WriteHTML($html);
$mpdf->Output($outputPath, 'F');

Зберігання та доступ

Готовий файл зберігається через \CFile::SaveFile() до таблиці b_file — стандартний механізм Бітрікс. Посилання для завантаження генерується через \CFile::GetPath(). У b_vendor_docgen_document зберігається file_id та метадані.

Доступ до документа перевіряється за належністю: користувач може завантажити документ, пов'язаний із його замовленням або профілем. Менеджери CRM — документи своїх угод. Адміністратори — всі.

Автоматична генерація за подіями

Документ можна генерувати автоматично при настанні події Бітрікс:

// В init.php або через обробник в інсталяторі модуля
AddEventHandler('sale', 'OnSaleOrderPaid', ['\Vendor\DocGen\EventHandler', 'onOrderPaid']);

// У класі обробника
public static function onOrderPaid(\Bitrix\Main\Event $event): void
{
    $orderId = $event->getParameter('id');
    DocGenerator::generate('invoice', 'sale_order', $orderId);
    // → автоматично прикріплює документ до замовлення та надсилає покупцю
}

Терміни розробки

Разом: 12 робочих днів. Складна верстка документів із колонтитулами, підписами та печатками — +2 дні.