1C-Bitrix Integration with Russian Post: API, Normalization, Batches
When a Bitrix store starts delivering orders to remote areas, courier services are often helpless — no coverage?
The only operator that reaches every settlement is Russian Post. But integration with its API Otpravka 2.0 is not just POST requests. It involves two-factor authorization, mandatory address normalization according to FIAS, batch mode, and cash on delivery. Without understanding these nuances, parcels go out with errors, and money gets stuck in accounts. The average savings on returns after implementing normalization is 15%, and order processing speed doubles. On one project, savings per month amounted to 120,000 RUB. We have completed dozens of such integrations and compiled a typical solution. Contact us for a consultation to evaluate your project in one day.
We are a team with 10+ years of experience in Bitrix and integrations with Russian Post. Behind us are 50+ projects where the postal API works in production. Below is a technical breakdown of how we do it: from normalization to tracking.
Russian Post API: Operating Principles
Base URL: https://otpravka-api.pochta.ru. Authorization: two tokens simultaneously — Authorization: AccessToken TOKEN and X-User-Authorization: Basic BASE64(login:password). To obtain tokens, you need to register in the Russian Post personal account and create an application. AccessToken is issued automatically, and Basic authorization is formed from the login and password in Base64 format. More details in the official API documentation.
Key method groups:
-
/1.0/user/shipping-points— sender addresses (from where) -
/1.0/clean/address— address normalization -
/1.0/tariff— tariff calculation -
/1.0/user/backlog— batch shipment upload -
/1.0/batch/{batchName}/shipment— creating shipments in a batch -
/1.0/shipment/search— tracking by barcode
Shipment Types
The API supports POSTAL_PARCEL (parcel), EMS, EMS_OPTIMAL, FIRST_CLASS (first class), and small package. The choice of type affects the tariff and delivery time. For cash on delivery, ORDINARY or CASH_ON_DELIVERY is used.How Address Normalization Works?
The main pain point of Russian Post is the quality of addresses entered by customers. The API requires correct addresses in the FIAS format. Normalization is the first step before any operation. If the address is not normalized (quality-code is not GOOD), the parcel cannot be sent — it will not pass sorting. Our clients save up to 15% on returns thanks to this check.
private function normalizeAddress(string $rawAddress): array
{
$response = $this->apiPost('/1.0/clean/address', [
[
'id' => 'addr1',
'original-address' => $rawAddress,
]
]);
$normalized = $response[0] ?? [];
if (($normalized['quality-code'] ?? '') === 'GOOD') {
return $normalized;
}
// Если качество плохое — возвращаем ошибку, не создаём отправление
throw new \RuntimeException(
'Адрес не нормализован: ' . ($normalized['quality-code'] ?? 'unknown')
);
}
Quality codes: GOOD — fully normalized, POSTAL_BOX — PO box, ON_DEMAND — poste restante, UNDEF_* — various normalization problems. Only GOOD guarantees correct delivery.
How to Calculate Tariff?
private function calcTariff(
array $normalizedAddress,
int $weightGram,
string $mailType = 'POSTAL_PARCEL'
): float {
$response = $this->apiPost('/1.0/tariff', [
'object-type' => $mailType,
'mail-category' => 'ORDINARY',
'from-index' => $this->getOption('FROM_INDEX'), // индекс отправки
'to-index' => $normalizedAddress['index'],
'mass' => $weightGram,
'dimension' => [
'height' => 200,
'length' => 300,
'width' => 200,
],
]);
return ($response['total-rate'] ?? 0) / 100; // копейки → рубли
}
Russian Post returns the cost in kopecks — don't forget to divide by 100. Shipment types: POSTAL_PARCEL (parcel), EMS (express), EMS_OPTIMAL (optimal EMS), FIRST_CLASS (first class). Tariff comparison shows that EMS_OPTIMAL is 30% faster than a regular parcel at a similar cost.
Why Is Batch Mode Mandatory?
Russian Post does not accept single shipments — all parcels are grouped into batches. This simplifies logistics and printing. Batch mode processes up to 1000 shipments in one request, which is 5 times faster than sequential creation. First, a batch is created, then shipments are added to it, after which it is sent to print.
public function createShipment(\Bitrix\Sale\Shipment $shipment): string
{
$order = $shipment->getOrder();
$props = $order->getPropertyCollection();
// 1. Получаем или создаём партию
$batchName = $this->getOrCreateBatch($shipment);
// 2. Создаём отправление в партии
$payload = [[
'address-type-to' => 'DEFAULT',
'mail-type' => 'POSTAL_PARCEL',
'mail-category' => 'ORDINARY',
'mass' => $this->getWeight($shipment),
'index-to' => $this->getNormalizedIndex($props),
'recipient-name' => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
'tel-address' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
'str-index-to' => $this->getNormalizedIndex($props),
'order-num' => (string)$order->getId(),
'payment' => $this->getCashOnDelivery($order), // наложенный платёж
]];
$response = $this->apiPost("/1.0/batch/{$batchName}/shipment", $payload);
$barcode = $response['result-ids'][0] ?? null;
if ($barcode) {
$props->getItemByOrderPropertyCode('POCHTA_BARCODE')?->setValue($barcode);
$order->save();
}
return $barcode ?? '';
}
How to Perform Integration Step by Step
- Obtain access tokens in the Russian Post personal account.
- Implement address normalization during order checkout.
- Implement real-time tariff calculation.
- Configure batch shipment creation.
- Connect tracking and status updates.
- Organize printing of stamps and forms.
Cash on Delivery
Cash on delivery (COD) is a key Russian Post function for e-commerce. The payment field in the request contains the amount to be collected from the customer in kopecks. If no COD is needed — pass 0. With COD, Russian Post deducts a commission of ~2–3% and transfers the remainder to the store's bank account. Transfer time is up to 10 business days. Savings on delivery when using COD due to automation reach up to 20%, which in monetary terms can amount to 50,000 RUB with a turnover of 500,000 RUB.
Tracking via Russian Post API
For automatic status updates, we use cron tasks run once an hour.
public function trackShipment(string $barcode): array
{
$response = $this->apiGet('/1.0/shipment/search', ['query' => $barcode]);
$events = $response['trackingData']['trackingItem']['trackingHistoryItem'] ?? [];
$lastEvent = end($events);
return [
'status' => $lastEvent['humanStatus'] ?? '',
'date' => $lastEvent['eventDateTime'] ?? '',
'city' => $lastEvent['cityName'] ?? '',
'barcode' => $barcode,
];
}
Tracking via the main API is rate-limited. For high-load stores, a separate Tracking API with a different quota is used.
Printing Stamps and Forms
After adding shipments to a batch, printing of f7 (address label) and f107/f112 (accompanying documents) is available:
GET /1.0/forms/{barcode}/f7pdf — address label
GET /1.0/batch/{batchName}/checkin — batch submission to the post office
What's Included in the Work?
We use HL-blocks to store integration settings and tagged caching for caching.
| Stage | Result |
|---|---|
| Store and cart analysis | Determining the data schema: orders, properties, delivery types. Unlike 1C exchange via CommerceML, integration with Russian Post does not require XML parsing. |
| Address normalization on frontend and backend | FIAS hints during checkout, cleaning before sending |
| Real-time tariff calculation | Automatic selection of shipment type by weight and amount |
| Creating shipments in a batch | Barcode generation and linking to orders |
| Cash on delivery and tracking | Automatic status updates in admin panel |
| Printing stamps and reports | Direct printing from order in 1 click |
Indicative Timeline
| Scope | Duration |
|---|---|
| Tariff calculation + address normalization | 3–4 days |
| + Shipment creation (batch mode) | +2 days |
| + Cash on delivery + tracking | +2 days |
| + Printing stamps in admin section | +1 day |
Turnkey integration takes 5 to 8 days depending on catalog complexity and individual requirements. Reversibility — when switching to another delivery service, the module is easily replaced.
We guarantee that your parcels will go out with the correct address, barcode, and tariff. Contact us — we will evaluate your project in 1 day and give you a working integration prototype. Get a consultation and a working solution for your store.