Integration of 1C-Bitrix with the Europost delivery service (Belarus)

1C-Bitrix Integration with Evropochta Delivery Service (Belarus)

Evropochta is a Belarusian courier service operating through a pickup point (PUP) network. It covers major and mid-sized cities in Belarus well and is a popular alternative to Belpochta for e-commerce focused on delivery speed to pickup points. The API provides a JSON interface with key-pair authorization.

Connecting to the Evropochta API

Documentation and access keys are provided after signing a contract. Base URL: https://api.evropochta.by/api/. Authorization: token in the token header (not Authorization: Bearer — specifically a custom token header).

private function apiCall(string $method, string $endpoint, array $data = []): array
{
    $url = 'https://api.evropochta.by/api/' . ltrim($endpoint, '/');
    $ch = curl_init($method === 'GET' ? $url . '?' . http_build_query($data) : $url);

    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'token: ' . $this->getOption('API_TOKEN'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => $method === 'POST' ? json_encode($data) : null,
    ]);

    $result = json_decode(curl_exec($ch), true);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($code !== 200 || ($result['error'] ?? false)) {
        throw new \RuntimeException($result['error']['message'] ?? 'Evropochta API error');
    }

    return $result['data'] ?? $result;
}

Retrieving the Pickup Point List

public function getPickupPoints(?string $cityId = null): array
{
    $params = $cityId ? ['cityId' => $cityId] : [];

    $cacheKey = 'evropochta_pvz_' . ($cityId ?? 'all');
    $cached = \Bitrix\Main\Data\Cache::createInstance();

    if ($cached->startDataCache(3600 * 12, $cacheKey, '/evropochta')) {
        $points = $this->apiCall('GET', '/pickup-points', $params);
        $cached->endDataCache(['points' => $points]);
    }

    return $cached->getVars()['points'];
}

The pickup point list is cached for 12 hours — it does not change hourly. On the website it is displayed on a map (Yandex Maps or OpenStreetMap) or as a dropdown list with a city filter.

Cost Calculation

public function calcPrice(
    string $pvzCode,
    int $weightGram,
    float $declaredValue
): float {
    $response = $this->apiCall('POST', '/tariff', [
        'pvzCode'       => $pvzCode,
        'weight'        => $weightGram,
        'declaredValue' => $declaredValue,
    ]);

    return (float)($response['price'] ?? 0);
}

Cost is in Belarusian rubles. When integrating with 1C-Bitrix, verify the site's currency — if the store operates in multiple currencies, conversion via the National Bank of Belarus exchange rate is required.

Creating a Delivery Order

public function createOrder(\Bitrix\Sale\Shipment $shipment): string
{
    $order = $shipment->getOrder();
    $props = $order->getPropertyCollection();

    $payload = [
        'externalId'     => (string)$order->getId(),
        'pvzCode'        => $props->getItemByOrderPropertyCode('EVROPOCHTA_PVZ')?->getValue(),
        'recipientName'  => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
        'recipientPhone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
        'recipientEmail' => $props->getItemByOrderPropertyCode('EMAIL')?->getValue(),
        'weight'         => $this->getWeight($shipment),
        'declaredValue'  => $order->getPrice(),
        'codAmount'      => 0, // cash on delivery
        'items'          => $this->buildItems($order),
    ];

    $response = $this->apiCall('POST', '/orders', $payload);

    $trackNumber = $response['trackNumber'] ?? '';
    $props->getItemByOrderPropertyCode('EVROPOCHTA_TRACK')?->setValue($trackNumber);
    $order->save();

    return $trackNumber;
}

Tracking

public function getStatus(string $trackNumber): array
{
    $response = $this->apiCall('GET', '/tracking/' . $trackNumber);
    return [
        'status'   => $response['statusName'] ?? '',
        'date'     => $response['updatedAt'] ?? '',
        'pvzName'  => $response['pvzName'] ?? '',
    ];
}

Polling via agent every 2–3 hours for active shipments. Webhooks are not provided.

Status Mapping

Timelines