Интеграция 1С-Битрикс с системой Меркурий: автоматизация эВСД

Интеграция 1С-Битрикс с системой Меркурий — обязательное условие для легальной торговли продуктами животного происхождения. Каждый день через ФГИС проходят миллионы эВСД, и ручная обработка ведёт к задержкам и штрафам до $1.4k–1.9k. Мы автоматизируем обмен, используя REST API и асинхронные очереди, сокращая время приёмки одной партии в 5 раз. Оценим ваш проект за 2 дня — просто свяжитесь с нами.

Интеграция 1С-Битрикс с Меркурием

Меркурий предоставляет REST API (https://api.vetrf.ru/schema/platform/v2/). Авторизация — через API-ключ, который выдаётся после регистрации предприятия. Основные операции: получение входящих документов, погашение эВСД (extinguish), запрос статусов заявок. Важно учитывать асинхронность: каждый запрос создаёт заявку, которую нужно обработать отдельным вызовом. Согласно документации ФГИС Меркурий, на один API-ключ допускается до 10 запросов в минуту. Поэтому мы реализуем очередь с ретраями.

Типичный lifecycle документа:

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

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

Реализация клиента на PHP:

class MerkuryClient {
    private string $apiUrl = 'https://api.vetrf.ru/schema/platform/v2';
    private string $apiKey;
    private string $issuerId;

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

Хранение эВСД в Битрикс

Каждая партия товара на складе привязана к одному или нескольким эВСД. Мы храним их в отдельной ORM-таблице:

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.

Автоматизация погашения

Если погашать вручную, легко пропустить срок — тогда сертификат аннулируется, и товар считается нелегальным. Штрафы за оборот без эВСД — до $1.4k–1.9k. Автоматизация исключает человеческий фактор и укладывается в требования 54-ФЗ. Кроме того, Меркурий API работает асинхронно: запрос создаёт заявку, которую нужно обработать отдельным вызовом. Мы реализуем очередь с ретраями, чтобы ни один документ не потерялся.

Сравнение ручного и автоматизированного подхода

Приведённые данные показывают: автоматизация ускоряет процесс в 5 раз и снижает операционные риски.

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

Наш клиент — интернет-магазин мяса и молочной продукции от 15 фермерских хозяйств. Объём — ~250 заказов в неделю. До нас приёмка одной партии занимала 15 минут ручного ввода в Меркурий, а погашение при продаже не делали вовсе — рисковали.

Решение: автоматизировали приёмку (через админку Битрикс: кладовщик вводит ID прихода, система сама находит входящие эВСД от поставщика за последние сутки и предлагает погасить). Для отгрузки — двухшаговая модель: при оформлении заказа создаётся заявка на погашение, cron-обработчик каждые 2 минуты дёргает processTransaction. Синхронизация остатков раз в час.

Экономия времени на приёмке составила 80% — это около 40 часов в месяц. Дополнительно исключены штрафы за отсутствие погашений.

Синхронизация остатков

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

Что входит в интеграцию под ключ

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

Сроки: от 6 до 10 недель в зависимости от числа поставщиков и сложности учёта. У нас за плечами 5+ лет интеграций Битрикс с гос. системами, более 50 успешных проектов. Закажите аудит вашего проекта — получите план интеграции за 2 дня.