Інтеграція 1С-Бітрікс із системою ЕДО Діадок (Контур)

Інтеграція 1С-Бітрікс з системою ЕДО Діадок (Контур)

Діадок від СКБ Контур — найбільший оператор ЕДО в Росії. Юридично значущі рахунки-фактури, накладні, акти, УПД — все це підписується КЕП і передається через Діадок без дублювання паперових копій. Коли інтернет-магазин або B2B-платформа відправляє сотні документів на місяць, ручна робота у веб-інтерфейсі Діадока стає нестерпною — потрібна інтеграція з 1С-Бітрікс, яка автоматично створює і відправляє документи за подіями у системі.

Архітектура інтеграції

Діадок надає REST API (https://diadoc-api.kontur.ru/). Авторизація — через токен, що видається за логіном/паролем облікового запису Діадока або через сертифікат КЕП. Для серверної інтеграції використовується токен-авторизація.

Схема інтеграції:

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

Авторизація у Diadoc API

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 запит
    }
}

Генерація XML-документів

Діадок приймає документи у форматі XML за стандартом ФНП. Для УПД (універсальний передавальний документ) — формат згідно з Наказом ФНП ММВ-7-15/820.

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

        return $dom->saveXML();
    }
}

Валідація XML перед відправкою — обов'язкова. ФНП публікує XSD-схеми, які потрібно використовувати для перевірки структури документа.

Відправка документа через 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'];
}

Для підпису документа КЕП на сервері необхідний криптопровайдер — КриптоПро CSP або ViPNet CSP. Інтеграція через openssl_pkcs7_sign() із сертифікатом, встановленим на сервері.

Обробка статусів

Діадок повідомляє про зміну статусу документа двома способами: polling (GET /V3/GetNewEvents) і webhooks (push-сповіщення).

Polling для невеликого обсягу документів:

// Запускається cron кожні 5 хвилин
public function syncDocumentStatuses(): void
{
    $events = $this->client->request('GET',
        "/V3/GetNewEvents?boxId={$this->boxId}&afterEventId={$this->lastEventId}"
    );

    foreach ($events['Events'] as $event) {
        $docId   = $event['DocumentInfo']['DocumentId'];
        $status  = $event['DocumentInfo']['DocflowStatus']['PrimaryStatus']['StatusText'];
        $orderId = $this->getOrderIdByDocumentId($docId);

        if ($orderId) {
            $this->updateOrderStatus($orderId, $status);
        }

        $this->lastEventId = $event['EventId'];
    }
}

Кейс: автоматичний ЕДО для оптового постачальника

Дистриб'ютор косметики, ~800 B2B-замовлень на місяць. Кожне замовлення вимагало УПД. Співробітник вручну створював документ у Діадоку, 20–30 хвилин на замовлення сукупно на день.

Що автоматизували:

1. При зміні статусу замовлення на «Відвантажено» (OnSaleStatusOrder) — автоматична генерація та відправка УПД у Діадок. Реквізити контрагента беруться з властивостей замовлення Бітрікс (ІНН, КПП, BoxId Діадока).

2. Довідник контрагентів: при першому замовленні від нової юридичної особи — автоматичний пошук BoxId контрагента через GET /V3/GetOrganizationsByInnKpp. Якщо знайдено — зберігається у користувацьке поле покупця Бітрікс.

3. При підписанні УПД контрагентом — webhook від Діадока змінює статус замовлення на «Документи підписано». Менеджер бачить зміну у Бітрікс без входу у Діадок.

4. Сповіщення: якщо контрагент відхиляє документ із коментарем — менеджер отримує сповіщення у Бітрікс (CEventLog::Add()) з текстом причини відмови.

Зберігання історії документів у Бітрікс

Для відстеження всіх документів створюємо таблицю через D7:

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

Склад робіт

• Налаштування облікового запису Діадок, отримання API-ключів
• Встановлення КриптоПро CSP на сервері, завантаження сертифіката КЕП
• Розробка PHP-клієнта Diadoc API
• Генератор XML-документів (УПД, Акти) з валідацією за XSD
• Обробники подій Бітрікс (зміна статусу замовлення)
• Синхронізація статусів: polling або вебхуки
• Зберігання історії документів, відображення у замовленні у Бітрікс

Терміни: базова інтеграція (відправка УПД, статуси) — 3–5 тижнів. Повна інтеграція з кількома типами документів, довідником контрагентів і сповіщеннями — 6–10 тижнів.