Integrating 1C-Bitrix with EGAIS: Setup, Cases, and Timelines
An alcohol write-off error in EGAIS is a common cause of license suspension for online stores. Every unrecorded sale risks a fine of up to 300,000 RUB. We specialize in end-to-end integration of 1C-Bitrix with EGAIS: we automate data transmission for sales, returns, and stock balances. We guarantee every transaction is logged—eliminating fines. In our practice, we have completed over 50 projects for alcohol online stores.
EGAIS is the federal system for alcohol accounting. An online store selling alcohol remotely must record every sale. 1C-Bitrix must interact with EGAIS through the Universal Transport Module (UTM)—local software that encrypts and signs requests to EGAIS.
Manual alcohol write-offs take up to 2 hours per day and are prone to errors. With an operator salary of 1,000 RUB/hour, that's 60,000 RUB in monthly extra costs. Automation pays off in 1-2 months by eliminating fines and saving time.
What Is UTM and Why Do You Need It?
UTM—Universal Transport Module, developed by Rosalkogolregulirovanie. It is a local Windows or Linux application that receives XML requests from the site, encrypts them with a JaCarta crypto key, and sends them to EGAIS. UTM receives responses asynchronously and places them in a queue for retrieval. Without UTM, direct integration with EGAIS is impossible.
Integration Architecture
EGAIS does not provide a cloud REST API. Interaction is only through UTM installed on a local server. UTM receives XML requests on port 8080 and returns responses via a queue.
1C-Bitrix → XML request → UTM (localhost:8080)
↓
EGAIS (Rosalkogolregulirovanie)
↓
UTM generates response → Bitrix polls response queue
The scheme is asynchronous: the request is sent—the response comes in seconds or minutes.
XML Structure for Write-Off Request
<!-- TTNQuery — request for write-off upon sale -->
<?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 Client for UTM Interaction
class EgaisUtmClient
{
private string $utmUrl;
private string $orgRarId; // organization identifier in EGAIS
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,
]
])
);
$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,
];
}
}
Order Processing in Bitrix
// Event handler for order status change
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'sale', 'OnSaleStatusOrderChange',
function (\Bitrix\Main\Event $event) {
$order = $event->getParameter('ENTITY');
$statusId = $event->getParameter('VALUE');
if ($statusId !== 'shipped') return; // send only on "Shipped" status
$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);
// Save replyId for tracking
EgaisDocumentTable::add([
'ORDER_ID' => $order->getId(),
'REPLY_ID' => $replyId,
'STATUS' => 'pending',
'SENT_AT' => new \Bitrix\Main\Type\DateTime(),
]);
}
);
How to Avoid Errors in EGAIS Exchange? A Case from Our Practice
From our practice: an online liquor store, ~300 orders per day. Daily task—write off each sold unit of alcohol in EGAIS. If a write-off fails, the order cannot be legally considered closed.
Project challenges:
-
UTM was installed on a office Windows PC; the site was on a hosting. No direct network access.
-
Sometimes UTM was unresponsive (reboots, updates), documents got lost.
-
EGAIS returns AlcoCode—a unique code for each bottle (for labeled alcohol); we needed to store the correspondence AlcoCode ↔ order item.
Solutions:
-
VPN tunnel between hosting and office server + middleware on the office server that receives requests from Bitrix and forwards to UTM. Middleware in Node.js, runs as a Windows service.
-
Task queue on Bitrix side: unconfirmed documents are re-sent after 10 minutes (up to 5 attempts). If exhausted, admin notified.
-
Upon receiving confirmation from EGAIS, we save EGAISQuntId in a table
local_egais_alcocodes, linked to the Bitrix order item.
| Metric | Before Integration | After |
|---|---|---|
| Manual operations in EGAIS | ~2 hours/day | 0 (only monitoring) |
| Write-off delay from shipment | 1–3 hours | < 15 minutes |
| Missed write-offs | 3–5%/month | < 0.1% |
Automated integration is 10 times faster than manual data entry and eliminates fines of up to 300,000 RUB for each unrecorded write-off.
Returns in EGAIS
When alcohol is returned, the reverse operation—adding to stock—is done via a WayBillAct document. Triggered by the return event in Bitrix (OnSaleRefund).
EGAIS Stock in Bitrix
For syncing warehouse stock with EGAIS data, we periodically query UTM (RestBal) and compare with stock in the Bitrix catalog. Discrepancies are logged for review.
What’s Included in the Work
- UTM setup, EGAIS key acquisition (through Rosalkogolregulirovanie)
- Network connection: VPN or middleware service
- PHP client for UTM: document sending, response polling
- XML generation for write-off and return acts
- Bitrix event handlers: shipment, return
- Queue with retries, error monitoring
- EGAIS document history table in Bitrix
- Admin training, 3 months of support
Comparison of manual vs. automated approach:
| Criteria | Manual Entry | Automated Integration |
|---|---|---|
| Time per operation | 10–15 minutes | < 1 second |
| Error risk | high | ≈ 0% |
| Daily time spent | up to 2 hours | 5 minutes (monitoring) |
Common setup mistakes:
- No persistent network connection to UTM—documents never reach EGAIS.
- Incorrect certificates—EGAIS rejects requests.
- Missing order status triggers—write-off does not initiate.
- No response queue processing—confirmations are lost.
Why Trust Our Engineers with Integration?
Our certified specialists have years of experience. We've completed over 50 projects for alcohol online stores. We provide a warranty on all work and training for your team. Request an audit of your infrastructure—we’ll assess the project and give you a timeline.
Timelines: with a ready UTM and network access—4–6 weeks. If infrastructure setup is needed—8–12 weeks. The cost is determined individually. Get a consultation with an engineer today.