שילוב 1C-Bitrix עם Diadoc EDI (Kontur)

אנו הופכים לאוטומטי את החלפת המסמכים בעלי חשיבות משפטית בין 1C-Bitrix ומערכת Diadoc EDI (SKB Kontur). עם ניסיון רב, אנו מגדירים אינטגרציות עבור חנויות מקוונות ופלטפורמות B2B: חשבוניות, תעודות משלוח, אישורי ביצוע ו-UPD נחתמים עם חתימה אלקטרונית מוסמכת (CES) ומועברים ללא עבודה ידנית. כשכל דקה חשובה, האוטומציה מחזירה את ההשקעה תוך 2–3 חודשים.

כאב טיפוסי: מנהלים מבזבזים עד 30 דקות ביום על יצירת מסמכים ידנית ב-Diadoc. שגיאות בפרטים מובילות להחזרות ועיכובים בתשלומים. אנו פותרים בעיות אלה: אנו מגדירים יצירת XML אוטומטית לפי תקני רשות המסים הפדרלית, חתימת CES בצד השרת ומעקב אחר סטטוסים. הלקוח מקבל זרימת מסמכים שקופה ללא שלבים מיותרים.

באמצעות אינטגרציה, זמן עיבוד ה-EDI מצטמצם ל-2 דקות ביום, ושיעור השגיאות יורד מ-5% ל-0.5%. במאמר זה אנו מכסים את הארכיטקטורה, הקוד ומקרה יישום אמיתי.

שילוב 1C-Bitrix עם Diadoc

Diadoc מספק REST API (https://diadoc-api.kontur.ru/). האימות הוא באמצעות טוקן שהונפק באמצעות שם משתמש/סיסמה של חשבון Diadoc או באמצעות תעודת CES. עבור אינטגרציה בשרת, נעשה שימוש באימות מבוסס טוקן.

סכימת האינטגרציה:

Битрикс (событие: заказ оплачен) → PHP-обработчик → Генерация XML-документа (УПД/Акт) → POST /v1/organizations/{orgId}/messages (Диадок API) → Диадок доставляет контрагенту → Webhook от Диадока: статус подписания → Обновление статуса в Битрикс 

יישום אוטומציה חוסך עד $2.7k–3.9k בשנה על מילוי מסמכים ידני. העלות הממוצעת של שגיאת פרטים אחת היא $14–20, והאוטומציה מבטלת עד 90% משגיאות כאלה.

הגדרת אימות ל-API של Diadoc

class DiadokClient {
    private string $apiKey;
    private string $token;
    private string $baseUrl = 'https://diadoc-api.kontur.ru';

    public function __construct(string $apiKey, string $login, string $password) {
        $this->apiKey = $apiKey;
        $this->token = $this->authenticate($login, $password);
    }

    private function authenticate(string $login, string $password): string {
        $response = $this->request('POST', '/V3/Authenticate', [
            'login' => $login,
            'password' => $password,
        ], false);
        return $response; // возвращает токен-строку
    }

    public function request(string $method, string $path, array $data = [], bool $auth = true): mixed {
        $headers = ['DiadocAuth ddauth_api_client_id=' . $this->apiKey];
        if ($auth) {
            $headers[] = 'Authorization: DiadocAuth ddauth_api_client_id=' . $this->apiKey . ', ddauth_token=' . $this->token;
        }
        // ... curl/Guzzle запрос
    }
}

מסמכים הניתנים לאוטומציה

עם האינטגרציה, ניתן לשלוח UPD, אישורי ביצוע, חשבוניות ותעודות משלוח. כל המסמכים נוצרים לפי תקני רשות המסים הפדרלית, במיוחד מסמך ההעברה האוניברסלי לפי צו רשות המסים הפדרלית MMV-7-15/820. טפסי XML מותאמים אישית נתמכים גם אם הם תואמים לסכימות XSD של Diadoc.

אימות XSD מפחית את שיעור השגיאות פי עשרה

Diadoc מקבל מסמכים בפורמט XML לפי תקני רשות המסים הפדרלית. עבור UPD, הפורמט הוא לפי צו רשות המסים הפדרלית MMV-7-15/820. אימות סכימת XSD הוא חובה: אם המבנה אינו תואם, Diadoc מחזיר שגיאה 400. אנו משתמשים ב-Битрикс (событие: заказ оплачен) → PHP-обработчик → Генерация XML-документа (УПД/Акт) → POST /v1/organizations/{orgId}/messages (Диадок API) → Диадок доставляет контрагенту → Webhook от Диадока: статус подписания → Обновление статуса в Битрикс לפני השליחה.

class UPDGenerator {
    public function generateFromOrder(\Bitrix\Sale\Order $order): string {
        $dom = new \DOMDocument('1.0', 'UTF-8');
        $root = $dom->createElement('Файл');
        $root->setAttribute('ИдФайл', $this->generateFileId($order));
        $root->setAttribute('ВерсПрог', 'BitrixIntegration 1.0');
        $root->setAttribute('ВерсФорм', '5.02');
        // Сведения об участниках
        $svUch = $dom->createElement('СвУчДокОбор');
        $svSender = $dom->createElement('СвОЭДОтпр');
        $svSender->setAttribute('НаимОрг', $this->senderName);
        $svSender->setAttribute('ИННЮЛ', $this->senderInn);
        $svSender->setAttribute('ИдЭДО', $this->senderEdoId);
        $svUch->appendChild($svSender);
        $root->appendChild($svUch);
        // Документ
        $doc = $dom->createElement('Документ');
        $doc->setAttribute('КНД', '1115125');
        $doc->setAttribute('ФункцДок', 'ДОП'); // ДОП = передача результатов работ/услуг
        $doc->setAttribute('НомерДок', $order->getId());
        $doc->setAttribute('ДатаДок', date('d.m.Y'));
        $doc->setAttribute('Сумма', number_format($order->getPrice(), 2, '.', ''));
        $doc->setAttribute('СумНал', $this->calculateVat($order));
        // Строки таблицы (позиции заказа)
        $this->appendOrderItems($dom, $doc, $order);
        $root->appendChild($doc);
        $dom->appendChild($root);
        $schemaPath = __DIR__ . '/schemas/utd820_05_01_02_hyphen.xsd';
        if (!$dom->schemaValidate($schemaPath)) {
            throw new \RuntimeException('XML не прошёл валидацию по XSD');
        }
        return $dom->saveXML();
    }
}

שליחת מסמך דרך API

public function sendUPD(\Bitrix\Sale\Order $order, string $recipientOrgId): string {
    $xml = (new UPDGenerator())->generateFromOrder($order);
    // Загрузка документа
    $uploadResult = $this->client->request('POST', "/V3/PostMessagePatchDraft?boxId={$this->boxId}", [
        'FromBoxId' => $this->boxId,
        'ToBoxId' => $recipientOrgId,
        'DocumentAttachments' => [[
            'SignedContent' => [
                'Content' => base64_encode($xml),
                'Signature' => $this->sign($xml), // подпись КЭП
            ],
            'TypeNamedId' => 'UniversalTransferDocument',
            'Function' => 'ДОП',
            'Version' => 'utd820_05_01_02_hyphen',
        ]],
    ]);
    return $uploadResult['MessageId'];
}

כדי לחתום על מסמך עם CES על השרת, נדרש ספק קריפטוגרפי — CryptoPro CSP או ViPNet CSP. האינטגרציה משתמשת ב-class DiadokClient { private string $apiKey; private string $token; private string $baseUrl = 'https://diadoc-api.kontur.ru'; public function __construct(string $apiKey, string $login, string $password) { $this->apiKey = $apiKey; $this->token = $this->authenticate($login, $password); } private function authenticate(string $login, string $password): string { $response = $this->request('POST', '/V3/Authenticate', [ 'login' => $login, 'password' => $password, ], false); return $response; // возвращает токен-строку } public function request(string $method, string $path, array $data = [], bool $auth = true): mixed { $headers = ['DiadocAuth ddauth_api_client_id=' . $this->apiKey]; if ($auth) { $headers[] = 'Authorization: DiadocAuth ddauth_api_client_id=' . $this->apiKey . ', ddauth_token=' . $this->token; } // ... curl/Guzzle запрос } } עם תעודה המותקנת על השרת.

Webhooks במקום Polling

Diadoc מודיע על שינויי סטטוס מסמכים באמצעות שתי שיטות: polling (DOMDocument::schemaValidate()) ו-webhooks (הודעות push). אנו ממליצים על webhooks — הם יעילים יותר ומפחיתים את עומס השרת.

Polling עבור נפח מסמכים קטן מתבצע דרך cron כל 5 דקות. Webhooks, לעומת זאת, מספקים עדכוני סטטוס מיידיים ללא עומס על השרת.

מקרה בוחן: EDI אוטומטי עבור ספק סיטונאי

מפיץ קוסמטיקה עם כ-800 הזמנות B2B בחודש. כל הזמנה דרשה UPD. עובד יצר את המסמך ידנית ב-Diadoc, ולקח 20–30 דקות ביום במצטבר.

פעולות אוטומטיות:

1. כאשר סטטוס ההזמנה משתנה ל"נשלח" (class UPDGenerator { public function generateFromOrder(\Bitrix\Sale\Order $order): string { $dom = new \DOMDocument('1.0', 'UTF-8'); $root = $dom->createElement('Файл'); $root->setAttribute('ИдФайл', $this->generateFileId($order)); $root->setAttribute('ВерсПрог', 'BitrixIntegration 1.0'); $root->setAttribute('ВерсФорм', '5.02'); // Сведения об участниках $svUch = $dom->createElement('СвУчДокОбор'); $svSender = $dom->createElement('СвОЭДОтпр'); $svSender->setAttribute('НаимОрг', $this->senderName); $svSender->setAttribute('ИННЮЛ', $this->senderInn); $svSender->setAttribute('ИдЭДО', $this->senderEdoId); $svUch->appendChild($svSender); $root->appendChild($svUch); // Документ $doc = $dom->createElement('Документ'); $doc->setAttribute('КНД', '1115125'); $doc->setAttribute('ФункцДок', 'ДОП'); // ДОП = передача результатов работ/услуг $doc->setAttribute('НомерДок', $order->getId()); $doc->setAttribute('ДатаДок', date('d.m.Y')); $doc->setAttribute('Сумма', number_format($order->getPrice(), 2, '.', '')); $doc->setAttribute('СумНал', $this->calculateVat($order)); // Строки таблицы (позиции заказа) $this->appendOrderItems($dom, $doc, $order); $root->appendChild($doc); $dom->appendChild($root); $schemaPath = __DIR__ . '/schemas/utd820_05_01_02_hyphen.xsd'; if (!$dom->schemaValidate($schemaPath)) { throw new \RuntimeException('XML не прошёл валидацию по XSD'); } return $dom->saveXML(); } } ) — יצירה ושליחה אוטומטית של UPD ל-Diadoc. פרטי הצד שכנגד (ח.פ., מ.ס., Diadoc BoxId) נלקחים ממאפייני ההזמנה ב-Bitrix.

2. ספריית צד שכנגד: בהזמנה הראשונה מישות משפטית חדשה — חיפוש אוטומטי של BoxId של הצד שכנגד דרך public function sendUPD(\Bitrix\Sale\Order $order, string $recipientOrgId): string { $xml = (new UPDGenerator())->generateFromOrder($order); // Загрузка документа $uploadResult = $this->client->request('POST', "/V3/PostMessagePatchDraft?boxId={$this->boxId}", [ 'FromBoxId' => $this->boxId, 'ToBoxId' => $recipientOrgId, 'DocumentAttachments' => [[ 'SignedContent' => [ 'Content' => base64_encode($xml), 'Signature' => $this->sign($xml), // подпись КЭП ], 'TypeNamedId' => 'UniversalTransferDocument', 'Function' => 'ДОП', 'Version' => 'utd820_05_01_02_hyphen', ]], ] ); return $uploadResult['MessageId']; } . אם נמצא, הוא נשמר בשדה מותאם אישית של הקונה ב-Bitrix.

3. כאשר הצד שכנגד חותם על ה-UPD — webhook מ-Diadoc משנה את סטטוס ההזמנה ל"מסמכים נחתמו". המנהל רואה את השינוי ב-Bitrix ללא פתיחת Diadoc.

4. הודעה: אם הצד שכנגד דוחה מסמך עם הערה — המנהל מקבל הודעה ב-Bitrix (openssl_pkcs7_sign()) עם טקסט סיבת הדחייה.

בקשו ייעוץ — ננתח את זרימת המסמכים שלכם ונציע פתרון אופטימלי.

אחסון היסטוריית מסמכים

כדי לעקוב אחר כל המסמכים, אנו יוצרים טבלה באמצעות D7 ORM:

class DiadokDocumentTable extends \Bitrix\Main\ORM\Data\DataManager
{
    public static function getTableName(): string
    {
        return 'local_diadok_documents';
    }

    public static function getMap(): array
    {
        return [
            new \Bitrix\Main\ORM\Fields\IntegerField('ID', ['primary' => true, 'autocomplete' => true]),
            new \Bitrix\Main\ORM\Fields\IntegerField('ORDER_ID'),
            new \Bitrix\Main\ORM\Fields\StringField('DIADOK_MESSAGE_ID'),
            new \Bitrix\Main\ORM\Fields\StringField('DOCUMENT_TYPE'), // UPD, ACT, INVOICE
            new \Bitrix\Main\ORM\Fields\StringField('STATUS'), // sent, signed, rejected
            new \Bitrix\Main\ORM\Fields\DatetimeField('CREATED_AT'),
            new \Bitrix\Main\ORM\Fields\DatetimeField('SIGNED_AT'),
        ];
    }
}

מה כלול

• הגדרת חשבון Diadoc, קבלת מפתחות API
• התקנת ספק קריפטוגרפי על השרת, העלאת תעודת CES
• פיתוח לקוח PHP עבור API של Diadoc
• מחולל מסמכי XML (UPD, אישורי ביצוע) עם אימות XSD
• מטפלי אירועים ב-Bitrix (שינוי סטטוס הזמנה)
• סנכרון סטטוסים: polling או webhooks
• אחסון היסטוריית מסמכים, הצגה בהזמנת Bitrix
• הדרכת צוות, תיעוד, תמיכה ל-3 חודשים

לוחות זמנים: אינטגרציה בסיסית (שליחת UPD, סטטוסים) — 3–5 שבועות. אינטגרציה מלאה עם סוגי מסמכים מרובים, ספריית צד שכנגד והודעות — 6–10 שבועות.

צרו קשר — נגדיר אינטגרציה לעסק שלכם. פנו אלינו להערכת פרויקט — ננתח את זרימת המסמכים שלכם ונציע את הפתרון האופטימלי.