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

Інтеграція 1С-Бітрікс з системою ЄГАІС

ЄГАІС (Єдина державна автоматизована інформаційна система) — федеральна система обліку виробництва та обігу алкоголю. Інтернет-магазин, що продає алкоголь дистанційно, з 2021 року зобов'язаний фіксувати кожен продаж у ЄГАІС. Це означає: при створенні замовлення — списання товару з залишків ЄГАІС, при поверненні — зворотне зарахування. 1С-Бітрікс має взаємодіяти з ЄГАІС через УТМ (універсальний транспортний модуль) — локальне ПЗ, яке шифрує і підписує звернення до ЄГАІС.

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

ЄГАІС не надає хмарний REST API. Взаємодія тільки через УТМ, встановлений на локальному сервері підприємства. УТМ приймає XML-запити на порту 8080 (вхідні) та видає відповіді на порту 8080 (вихідні через чергу).

1С-Бітрікс → XML-запит → УТМ (localhost:8080)
                             ↓
                           ЄГАІС (Росалкогольрегулювання)
                             ↓
УТМ формує відповідь → Бітрікс polling черги відповідей

Схема асинхронна: запит відправлено → відповідь з'явиться у черзі через секунди або хвилини.

Структура XML для запиту списання

<!-- TTNQuery — запит на списання при реалізації -->
<?xml version="1.0" encoding="utf-8"?>
<ns:Documents xmlns:ns="urn:TNInformF2Reg:Documents"
             xmlns:oref="urn:TNInformF2:OrgInfo"
             version="2">
  <ns:Document>
    <ns:TTNInformF2Reg>
      <ns:Header>
        <ns:IsSSMark>0</ns:IsSSMark>
      </ns:Header>
      <ns:Content>
        <ns:Position>
          <ns:Identity>1</ns:Identity>
          <ns:ProductCode>0366700000002375890</ns:ProductCode>
          <ns:Quantity>1.000</ns:Quantity>
          <ns:InformF1RegId>TEST-TTN123456</ns:InformF1RegId>
          <ns:InformF2RegId>TEST-F2-123456</ns:InformF2RegId>
        </ns:Position>
      </ns:Content>
    </ns:TTNInformF2Reg>
  </ns:Document>
</ns:Documents>

PHP-клієнт для взаємодії з УТМ

class EgaisUtmClient
{
    private string $utmUrl;
    private string $orgRarId; // ідентифікатор організації у ЄГАІС

    public function __construct(string $utmUrl, string $orgRarId)
    {
        $this->utmUrl   = $utmUrl; // http://localhost:8080
        $this->orgRarId = $orgRarId;
    }

    public function sendDocument(string $xmlDocument): string
    {
        $response = file_get_contents(
            $this->utmUrl . '/opt/in/TTNInformF2Reg',
            false,
            stream_context_create([
                'http' => [
                    'method'  => 'POST',
                    'header'  => 'Content-Type: application/xml',
                    'content' => $xmlDocument,
                ]
            ])
        );

        // УТМ повертає ReplyId — ідентифікатор для відстеження відповіді
        $replyXml = simplexml_load_string($response);
        return (string)$replyXml->ReplyId;
    }

    public function getReplyQueue(): array
    {
        $response = file_get_contents($this->utmUrl . '/opt/out');
        // Парсимо чергу відповідей
        return $this->parseQueue($response);
    }

    public function getReply(string $replyId): ?array
    {
        $response = file_get_contents(
            $this->utmUrl . "/opt/out/TTNInformF2Reg/{$replyId}"
        );
        if (!$response) return null;

        $xml = simplexml_load_string($response);
        return [
            'result'  => (string)$xml->Result->Conclusion,
            'comment' => (string)$xml->Result->ConclusionDate,
            'egais_id' => (string)$xml->Result->AccisesHeader->EGAISQuntId,
        ];
    }
}

Обробка замовлень у Бітрікс

// Обробник події зміни статусу замовлення
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'sale', 'OnSaleStatusOrderChange',
    function (\Bitrix\Main\Event $event) {
        $order    = $event->getParameter('ENTITY');
        $statusId = $event->getParameter('VALUE');

        if ($statusId !== 'shipped') return; // відправка тільки при статусі «Відвантажено»

        $egaisItems = $this->getAlcoholItemsFromOrder($order);
        if (empty($egaisItems)) return;

        $client  = new EgaisUtmClient(EGAIS_UTM_URL, EGAIS_ORG_RAR_ID);
        $xml     = $this->buildActWriteOff($order, $egaisItems);
        $replyId = $client->sendDocument($xml);

        // Зберігаємо replyId для відстеження
        EgaisDocumentTable::add([
            'ORDER_ID'  => $order->getId(),
            'REPLY_ID'  => $replyId,
            'STATUS'    => 'pending',
            'SENT_AT'   => new \Bitrix\Main\Type\DateTime(),
        ]);
    }
);

Кейс: інтернет-магазин алкоголю

Онлайн-магазин виноводочних виробів, ~300 замовлень/день. Щоденне завдання: списання кожної реалізованої одиниці алкоголю з залишків ЄГАІС. При помилці списання — замовлення не можна вважати закритим з точки зору законодавства.

Проблеми проєкту:

1. УТМ встановлений на офісному Windows-комп'ютері, сайт — на хостингу. Прямого мережевого доступу немає.

2. Іноді УТМ не відповідав (перезавантаження, оновлення), і документи губилися.

3. ЄГАІС повертає AlcoCode — унікальний код кожної пляшки (для маркованого алкоголю), потрібно зберігати відповідність AlcoCode ↔ позиція замовлення.

Рішення:

1. VPN-тунель між хостингом і офісним сервером + Middleware на офісному сервері, який приймає запити з Бітрікс і передає в УТМ. Middleware на Node.js, працює як Windows-служба.

2. Черга завдань на стороні Бітрікс: непідтверджені документи повторно відправляються через 10 хвилин (до 5 спроб). При вичерпанні спроб — сповіщення адміністратору.

3. При отриманні підтвердження від ЄГАІС — зберігаємо EGAISQuntId у таблиці local_egais_alcocodes, зв'язок із позицією замовлення Бітрікс.

Повернення у ЄГАІС

При поверненні алкоголю — зворотна операція: постановка на баланс через документ WayBillAct. Тригер — подія повернення у Бітрікс (OnSaleRefund).

Залишки ЄГАІС у Бітрікс

Для синхронізації залишків на складі з даними ЄГАІС — періодичний запит до УТМ (RestBal) і порівняння з залишками у каталозі Бітрікс. Розбіжності — у лог для ревізії.

Склад робіт

• Налаштування УТМ, отримання ключів ЄГАІС (через РОСАЛКОГОЛЬРЕГУЛЮВАННЯ)
• Мережева зв'язка: VPN або Middleware-сервіс
• PHP-клієнт для УТМ: відправка документів, polling відповідей
• Генерація XML для актів списання, повернень
• Обробники подій Бітрікс: відвантаження, повернення
• Черга з повторними спробами, моніторинг помилок
• Таблиця історії ЄГАІС-документів у Бітрікс

Терміни: при наявності налаштованого УТМ і мережевого доступу — 4–6 тижнів. При необхідності налаштування інфраструктури — 8–12 тижнів.