1C-Bitrix Integration with Mercury System: eVSD Automation

1C-Bitrix Integration with Mercury System: eVSD Automation

Integrating 1C-Bitrix with the Mercury system is mandatory for legal trade in animal products. Every day, millions of eVSDs pass through FSIS, and manual processing leads to delays and fines of up to $1.4k–1.9k. We automate the exchange using REST API and asynchronous queues, reducing the receiving time for a single batch by 5 times. We'll evaluate your project in 2 days — just contact us.

Integration of 1C-Bitrix with Mercury

Mercury provides a REST API (https://api.vetrf.ru/schema/platform/v2/). Authorization is via an API key issued after enterprise registration. Main operations: retrieving incoming documents, extinguishing eVSD, and checking application statuses. It's important to consider asynchronicity: each request creates an application that must be processed with a separate call. According to FSIS Mercury documentation, up to 10 requests per minute are allowed per API key. Therefore, we implement a queue with retries.

Typical document lifecycle:

Supplier → shipped goods with eVSD to Mercury → Store receives goods → extinguishes incoming eVSD (acceptVetDocument) → Warehouse storage: accounting unit with eVSD ID → Order placed → sale to individual → Write-off via transfer receipt transaction (transferReceiptTransaction) 

When selling to an end consumer (individual), a new eVSD is not required — you only need to extinguish the document for the sold quantity.

PHP client implementation:

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 request with header 'apiKey: {KEY}'
    }
}

Storing eVSD in Bitrix

Each batch of goods in the warehouse is linked to one or more eVSDs. We store them in a separate ORM table:

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'), // product in catalog
            new \Bitrix\Main\ORM\Fields\StringField('VET_DOC_ID'), // UUID of document in Mercury
            new \Bitrix\Main\ORM\Fields\StringField('ENTERPRISE_GUID'), // enterprise GUID
            new \Bitrix\Main\ORM\Fields\FloatField('QUANTITY'), // warehouse stock
            new \Bitrix\Main\ORM\Fields\StringField('UNIT'), // unit: kg, piece
            new \Bitrix\Main\ORM\Fields\StringField('STATUS'), // 'active', 'extinguished'
            new \Bitrix\Main\ORM\Fields\DatetimeField('EXPIRE_DATE'), // expiration date
        ];
    }
}

When a batch arrives, a record is created with the eVSD ID and quantity. Upon sale, the quantity decreases; when depleted, the status changes to extinguished.

Automating Extinguishing

If you extinguish manually, you can easily miss a deadline — then the certificate is revoked, and the goods become illegal. Fines for trading without an eVSD are up to $1.4k–1.9k. Automation eliminates human error and complies with 54-FZ requirements. Additionally, the Mercury API works asynchronously: a request creates an application that must be processed with a separate call. We implement a queue with retries to ensure no document is lost.

Comparison: Manual vs. Automated Approach

The data shows: automation speeds up the process by 5 times and reduces operational risks.

Case Study: Farm Products Store

Our client is an online store selling meat and dairy products from 15 farms. Volume: ~250 orders per week. Before us, receiving a single batch took 15 minutes of manual entry into Mercury, and extinguishing on sale was not done at all — risky.

Solution: we automated receiving (via Bitrix admin panel: the warehouse worker enters the receipt ID, the system automatically finds incoming eVSDs from the supplier in the last 24 hours and suggests extinguishing). For shipping, we use a two-step model: when an order is placed, an extinguishing request is created; a cron handler runs every 2 minutes calling processTransaction. Stock synchronization runs every hour.

Time savings on receiving: 80% — about 40 hours per month. Additionally, fines for missing extinguishments are eliminated.

Stock Synchronization

Periodic reconciliation is mandatory. Stock in the local_merkury_vet_docs table is compared with enterprise stock in Mercury (GET /enterprises/{guid}/stockEntries). Discrepancies are logged and notify the administrator. This is an extra safeguard against desynchronization.

What's Included in Turnkey Integration

• Registration in Mercury, obtaining an API key (we guide you through every step)
• PHP client development: work with incoming documents, extinguishing, application processing
• eVSD storage table in Bitrix linked to products
• Receiving interface in the admin section (fast, with hints)
• Automatic extinguishing on shipment with queue and automatic retries
• Scheduled stock synchronization (cron), discrepancy monitoring
• Operational documentation, staff training, post-launch support

Timeline: 6 to 10 weeks depending on the number of suppliers and accounting complexity. We have over 5 years of Bitrix integration with government systems and more than 50 successful projects. Order an audit of your project — get an integration plan in 2 days.