יצירת מסמכים אוטומטית עבור Bitrix: מודול מותאם אישית

ייעול יצירת מסמכים ב-1C-Bitrix

תרחיש טיפוסי: מפעיל CRM מבלה 10 דקות ביצירת חשבונית ב-Word, מעתיק נתונים מההזמנה—עושה טעות בשער המע"מ, והמסמך נשלח ללקוח. או שחנות מסחר אלקטרוני מייצרת מאות תעודות משלוח ביום באמצעות phpWord, וכשהלוגו משתנה, יש לערוך כל תבנית בנפרד. 54-FZ דורש פיסקליזציה, ושגיאות בפרטים מובילות לקנסות של עד €1,000. אנו מפתחים מודול ל-Bitrix הפותר בעיות אלה באופן שיטתי: תבניות, משתנים, גרסאות, יצירה אוטומטית על בסיס אירועים.

בעיות שאנו פותרים

• שגיאות במסמכים: ת"ז שגוי, סכום לא נכון, שער מע"מ חסר. הזנה ידנית מובילה ל-30% שגיאות—אוטומציה מפחיתה את שיעור השגיאות לפחות מ-1%. המודול מבטל את הגורם האנושי: נתונים נשלפים ישירות מההזמנה או מהעסקה דרך ספקים.
• יצירה איטית: מנהל מבלה 5–10 דקות לכל מסמך. עם 200 הזמנות ביום, זה מעל 30 שעות עבודה—אוטומציה מפחיתה את היצירה ל-200–500 אלפיות השנייה למסמך, חיסכון של 95% בזמן. זה מתורגם להפחתה ממוצעת בעלויות עבודה ידנית של €2,000 לחודש.
• תבניות לא אחידות: מסמכי Word ממחלקות שונות משתמשים בגופנים, שוליים, כותרות עליונות/תחתונות שונים. המודול מרכז תבניות עם גרסאות—שינויים חלים מיד על כל המסמכים החדשים.
• אי-עמידה בדרישות: שדות חובה חסרים (KPP, OKTMO, קוד 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 עדיף על החלפה פשוטה

החלפה פשוטה של 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()), ]; } } נשברת עם נתונים מקוננים וטבלאות. 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 מהדר למטמון—הביצועים שווים להחלפה ידנית, אך תחזוקת התבניות קלה פי עשרות. פרטים נוספים ב-תיעוד Twig וב-ויקיפדיה.

כיצד להגדיר תבניות DOCX ו-HTML

לתבניות Word אנו משתמשים ב-str_replace עם שכפול שורות בטבלה:

$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. ההמרה היא החלק הכואב ביותר. השוואת שיטות:

בחירת הממיר היא פרמטר בהגדרות המודול. ברירת מחדל: mPDF לתבניות HTML, LibreOffice ל-DOCX. עוד על mPDF ו-LibreOffice. קראו על פורמט PDF ב-ויקיפדיה.

תבניות HTML

חלופה ל-Word—HTML עם CSS. קל יותר לתחזוקה, ללא בעיות קידוד. התבנית נשמרת ב-<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> בשדה PhpWord. המרה דרך Twig ו-mPDF:

$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');

mPDF תומך בכותרות עליונות/תחתונות, חתימות, חותמות, קודי QR.

כיצד להבטיח אבטחה ואוטומציה

אחסון וגישה

קבצים שנוצרו נשמרים דרך $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); לטבלת b_vendor_docgen_template. קישור הורדה—html_template. מטא-נתונים נשמרים ב-$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'); . זכויות גישה: משתמשים מורידים רק את המסמכים שלהם, מנהלי CRM מורידים מסמכים של העסקאות שלהם, מנהלים מורידים הכל.

יצירה אוטומטית דרך אירועים

ניתן ליצור מסמכים בעת התרחשות אירוע:

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);
    }
}

באופן דומה, ניתן להתחבר לסגירת עסקה, רישום משתמש, העלאת מוצר.

מה כלול בעבודה

כתוצאה מכך, אתם מקבלים:

• תיעוד: תיעוד טכני מלא על ספקי נתונים, סכמת משתנים ויכולת הרחבה.
• גישה: גישה למאגר קוד המקור ולממשק הניהול לתבניות.
• הדרכה: שעה אחת של הדרכה מקוונת לעובדים על שימוש במודול וניהול תבניות.
• תמיכה: 30 ימי תמיכה לאחר המסירה לתיקון באגים ושאלות.
• תוצרים:
  • מודול עובד עם טבלאות ORM ומתקין.
  • סט תבניות (3–5) למסמכים טיפוסיים.
  • תיעוד על ספקי נתונים ויכולת הרחבה.

תהליך

1. ניתוח: אנו לומדים תהליכים עסקיים ודרישות מסמכים.
2. עיצוב: ארכיטקטורת מודול, סכמת משתנים, בחירת ממיר.
3. פיתוח: יישום המודול, יצירת תבניות.
4. אינטגרציה: הגדרת אירועים ויצירה אוטומטית.
5. בדיקות: עד 3 איטרציות של עריכות על השרת שלכם.
6. פריסה והדרכה: מסירת תיעוד, הדרכת עובדים.

לוח זמנים משוער

עיצוב מסמכים מורכב עם כותרות עליונות/תחתונות, חתימות וחותמות מוסיף +2 ימים.

ההשקעה במודול מתחילה מ-€1,500 ומחזירה את עצמה תוך 2–3 חודשים, תוך חיסכון של עד €2,000 לחודש בעלויות עבודה ידנית.

שגיאות טיפוסיות במהלך היישום

• התעלמות מאימות: אם שדות חובה לא נבדקים, ניתן ליצור מסמך עם פרטים ריקים. המודול שלנו מאמת את סכמת ה-JSON לפני היצירה.
• בחירת ממיר שגויה: mPDF אינו תומך בטבלאות מורכבות עם תאים מאוחדים—במקרים כאלה יש צורך ב-LibreOffice. אנו עוזרים לבחור את האפשרות האופטימלית.
• חוסר במטמון: בכל קריאה, המודול קורא את התבנית מהמסד נתונים. אנו ממליצים להפעיל מטמון דרך \CFile::SaveFile().

ניסיון ואחריות

10+ שנים בפיתוח Bitrix, מעל 50 פרויקטים באוטומציית מסמכים. אנו עובדים עם תבניות בכל היקף—מחשבוניות פשוטות ועד חוזים רב-עמודיים עם קודי QR וחתימות דיגיטליות. מומחי 1C-Bitrix מוסמכים. אנו עומדים בלוחות זמנים: 95% מהפרויקטים נמסרים בזמן. צרו קשר כדי לדון בפרויקט שלכם—תקבלו מפרט ברור, לוח זמנים ותמחור אישי. הזמינו פיתוח מודול וחסלו שגיאות מסמכים לנצח.