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

Ми автоматизуємо обмін юридично значущими документами між 1С-Бітрікс і системою ЕДО Діадок (СКБ Контур). Понад 7 років налаштовуємо інтеграції для інтернет-магазинів і B2B-платформ: рахунки-фактури, накладні, акти, УПД підписуються КЕП і передаються без ручної роботи. Коли кожна хвилина на рахунку — автоматизація окупається за 2–3 місяці.

Типовий біль — менеджери витрачають до 30 хвилин на день на ручне створення документів у Діадоку. Помилки в реквізитах призводять до повернень і затримок оплат.

Ми вирішуємо ці проблеми: налаштовуємо автоматичну генерацію XML за стандартом ФНС, підписання КЕП на сервері та моніторинг статусів. Замовник отримує прозорий документообіг без зайвих рухів.

Завдяки інтеграції скорочується час оформлення ЕДО до 2 хвилин на день, а відсоток помилок падає з 5% до 0.5%. У цій статті розберемо архітектуру, код і кейс реального впровадження.

Інтеграція 1С-Битрикс з Діадок

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

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

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

Впровадження автоматизації дозволяє заощадити кошти на ручному заповненні документів протягом року. Середня вартість однієї помилки в реквізитах розраховується після аудиту, а при автоматизації виключається до 90% таких помилок.

Налаштування авторизації в Діадок 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 запит
    }
}

Документи, що автоматизуються

За допомогою інтеграції ви можете надсилати УПД, акти, рахунки-фактури та накладні. Усі документи формуються за стандартами ФНС, зокрема Універсальний передавальний документ відповідно до Наказу ФНС ММВ-7-15/820. Також підтримується надсилання довільних XML-форм, якщо вони відповідають XSD-схемам Діадока.

Валідація за XSD знижує відсоток помилок у 10 разів

Діадок приймає документи у форматі XML за стандартом ФНС. Для УПД — формат відповідно до Наказу ФНС ММВ-7-15/820. Валідація за XSD-схемами обов'язкова: якщо структура не відповідає, Діадок поверне помилку 400. Ми використовуємо DOMDocument::schemaValidate() перед надсиланням.

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

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

Webhooks замість polling

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

Polling для невеликого обсягу документів запускається cron раз на 5 хвилин. Webhooks же забезпечують миттєве оновлення статусів без навантаження на сервер.

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

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

Автоматизовані операції:

1. При зміні статусу замовлення на "Відвантажено" (OnSaleStatusOrder) — автоматична генерація та відправка УПД у Діадок. Реквізити контрагента беруться з властивостей замовлення Бітрікс (ІНН, КПП, BoxId Діадока).
2. Довідник контрагентів: при першому замовленні від нової юрособи — автоматичний пошук BoxId контрагента через GET /V3/GetOrganizationsByInnKpp. Якщо знайдено — зберігається в користувацьке поле покупця Бітрікс.
3. При підписанні УПД контрагентом — webhook від Діадока змінює статус замовлення на "Документи підписані". Менеджер бачить зміну в Бітрікс без заходу в Діадок.
4. Нотифікація: якщо контрагент відхиляє документ з коментарем — менеджер отримує повідомлення в Бітрікс (CEventLog::Add()) з текстом причини відмови.

Замовте консультацію — ми проаналізуємо ваш документообіг і запропонуємо оптимальне рішення.

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

Для відстеження всіх документів створюємо таблицю через 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'),
        ];
    }
}

Що входить у роботу

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

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

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