Інтеграція 1С-Бітрікс із системою Меркурій

Інтеграція 1С-Бітрікс з системою Меркурій

Меркурій — федеральна державна інформаційна система ветеринарної сертифікації (ФГІС). Підприємства, що працюють з продукцією тваринного походження (м'ясо, риба, молочні продукти, яйця), зобов'язані оформляти електронні ветеринарні супровідні документи (еВСД) при кожному переміщенні товару. Інтернет-магазин, що приймає замовлення на такі товари, стикається із завданням: при надходженні товару на склад та при відвантаженні потрібно гасити вхідні еВСД та оформляти вихідні через систему Меркурій.

Архітектура взаємодії

Меркурій надає REST API (https://api.vetrf.ru/schema/platform/v2/). Авторизація — через API-ключ, що видається Россільгоспнаглядом після реєстрації підприємства в системі.

Постачальник → відвантажив товар з еВСД у Меркурій
  → Магазин отримує товар → гасить вхідний еВСД (acceptVetDocument)
    → Зберігання на складі: облікова одиниця з ID еВСД
      → Замовлення оформлено → продаж фізичній особі
        → Списання через транзакцію повернення (transferReceiptTransaction)

При продажу кінцевому споживачу-фізичній особі оформляти новий еВСД не потрібно — достатньо погасити документ в частині проданої кількості.

PHP-клієнт для Mercury API

class MerkuryClient
{
    private string $apiUrl = 'https://api.vetrf.ru/schema/platform/v2';
    private string $apiKey;
    private string $issuerId; // ID підприємства в Меркурій

    public function __construct(string $apiKey, string $issuerId)
    {
        $this->apiKey   = $apiKey;
        $this->issuerId = $issuerId;
    }

    public function getIncomingDocuments(string $enterpriseGuid): array
    {
        return $this->request('GET',
            "/enterprises/{$enterpriseGuid}/vetDocuments",
            ['status' => 'CONFIRMED', 'type' => 'INCOMING']
        );
    }

    public function extinguishDocument(
        string $enterpriseGuid,
        string $vetDocId,
        float  $quantity,
        string $unit
    ): string {
        $response = $this->request('POST',
            "/enterprises/{$enterpriseGuid}/vetDocuments/{$vetDocId}/extinguish",
            [
                'returnedQuantity' => $quantity,
                'returnedUnit'     => $unit,
                'operatorId'       => $this->issuerId,
            ]
        );
        return $response['application']['applicationId'];
    }

    public function processTransaction(
        string $enterpriseGuid,
        string $transactionId
    ): array {
        return $this->request('POST',
            "/enterprises/{$enterpriseGuid}/applications/{$transactionId}/process"
        );
    }

    private function request(string $method, string $path, array $params = []): array
    {
        // ... HTTP-запит із заголовком 'apiKey: {KEY}'
    }
}

Зберігання еВСД в 1С-Бітрікс

Кожна партія товару на складі відповідає одному або кільком еВСД. Таблиця:

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

    public static function getMap(): array
    {
        return [
            new \Bitrix\Main\ORM\Fields\IntegerField('ID',          ['primary' => true, 'autocomplete' => true]),
            new \Bitrix\Main\ORM\Fields\IntegerField('PRODUCT_ID'),  // товар у каталозі
            new \Bitrix\Main\ORM\Fields\StringField('VET_DOC_ID'),   // UUID документа в Меркурій
            new \Bitrix\Main\ORM\Fields\StringField('ENTERPRISE_GUID'), // GUID підприємства
            new \Bitrix\Main\ORM\Fields\FloatField('QUANTITY'),      // залишок на складі
            new \Bitrix\Main\ORM\Fields\StringField('UNIT'),         // од. вим.: kg, piece
            new \Bitrix\Main\ORM\Fields\StringField('STATUS'),       // 'active', 'extinguished'
            new \Bitrix\Main\ORM\Fields\DatetimeField('EXPIRE_DATE'), // термін придатності
        ];
    }
}

При надходженні партії товару — створюється запис з ID еВСД та кількістю. При продажу — кількість зменшується, при вичерпанні — статус змінюється на extinguished.

Погашення еВСД при відвантаженні

public function handleOrderShipped(\Bitrix\Sale\Order $order): void
{
    $basket = $order->getBasket();
    foreach ($basket as $item) {
        $productId = $item->getProductId();
        $quantity  = $item->getQuantity();

        // Знаходимо активний еВСД для товару
        $vetDoc = VetDocumentTable::getList([
            'filter' => ['PRODUCT_ID' => $productId, 'STATUS' => 'active'],
            'order'  => ['EXPIRE_DATE' => 'ASC'], // спочатку найближчі до закінчення
            'limit'  => 1,
        ])->fetch();

        if (!$vetDoc) {
            \Bitrix\Main\Diag\Debug::writeToFile(
                "Немає еВСД для товару {$productId}",
                '[MERKURY ERROR]', '/local/logs/merkury.log'
            );
            continue;
        }

        $appId = $this->merkury->extinguishDocument(
            $vetDoc['ENTERPRISE_GUID'],
            $vetDoc['VET_DOC_ID'],
            $quantity,
            $vetDoc['UNIT']
        );

        // Обробляємо транзакцію
        $this->merkury->processTransaction($vetDoc['ENTERPRISE_GUID'], $appId);

        // Оновлюємо залишок у локальній таблиці
        $newQty = $vetDoc['QUANTITY'] - $quantity;
        VetDocumentTable::update($vetDoc['ID'], [
            'QUANTITY' => max(0, $newQty),
            'STATUS'   => $newQty <= 0 ? 'extinguished' : 'active',
        ]);
    }
}

Кейс: магазин фермерських продуктів

Інтернет-магазин м'яса та молочної продукції від фермерських господарств. ~250 замовлень/тиждень. Товари надходять від 15 постачальників, кожна партія — з окремим еВСД. Завдання: автоматизувати приймання (погашення вхідних еВСД) та відвантаження (списання при продажу).

Особливості:

Mercury API працює асинхронно: запит на погашення створює «заявку» (application), яку потрібно обробити окремим викликом. Іноді заявки обробляються кілька хвилин — система Меркурій навантажена.

Реалізовано двокрокову модель: при відвантаженні створюється заявка, яка записується в чергу; cron-обробник кожні 2 хвилини викликає processTransaction для заявок, що очікують.

Приймання товару: комірник через адміністративний розділ 1С-Бітрікс вводить ID приходу з накладної постачальника → система автоматично запитує список вхідних еВСД від цього постачальника за останні добу → комірник підтверджує відповідність партій → Меркурій фіксує приймання.

Синхронізація залишків

Періодична звірка: залишки в таблиці local_merkury_vet_docs порівнюються із залишками підприємства в Меркурій (GET /enterprises/{guid}/stockEntries). Розбіжності — до журналу та повідомлення адміністратору.

Склад робіт

• Реєстрація в Меркурії, отримання API-ключа (через Россільгоспнагляд)
• Розробка PHP-клієнта: вхідні документи, погашення, звірка
• Таблиця зберігання еВСД в 1С-Бітрікс
• Інтерфейс приймання в адміністративному розділі
• Автопогашення при відвантаженні з чергою повторних спроб
• Синхронізація залишків (cron), моніторинг розбіжностей

Терміни: 6–10 тижнів залежно від кількості постачальників та складності складського обліку.