Belpochta Delivery Service Integration

Belpochta delivery service integration

Belpochta is Belarus national postal operator. For e-commerce working with Belarusian customers, integration ensures delivery nationwide. API less mature than Russian services, so implementation uses official tariff tables.

Tariff-based calculation

class BelpochtaTariffCalculator
{
    private array $domesticParcels = [
        0.1  => 3.20, 0.5  => 4.30, 1.0  => 5.10,
        2.0  => 6.40, 5.0  => 9.60, 10.0 => 13.50,
    ];
    private float $courierSurcharge = 3.50;

    public function calculate(float $weightKg, bool $toDoor = false): array
    {
        $basePrice = null;
        foreach ($this->domesticParcels as $maxWeight => $price) {
            if ($weightKg <= $maxWeight) {
                $basePrice = $price;
                break;
            }
        }

        $total = $basePrice;
        if ($toDoor) $total += $this->courierSurcharge;

        return [
            'base'       => $basePrice,
            'courier_fee'=> $toDoor ? $this->courierSurcharge : 0,
            'total'      => round($total, 2),
            'currency'   => 'BYN',
            'min_days'   => 3,
            'max_days'   => 14,
        ];
    }
}

Corporate API integration

For clients with contract:

class BelpochtaApiClient
{
    private string $baseUrl = 'https://api.belpochta.by/v1';

    public function calculateShipping(array $params): array
    {
        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . config('services.belpochta.api_key'),
        ])->post($this->baseUrl . '/calc', [
            'from_index'   => $params['from_index'],
            'to_index'     => $params['to_index'],
            'weight'       => (int)($params['weight_kg'] * 1000),
        ]);

        return $response->json();
    }

    public function createOrder(array $orderData): array
    {
        $response = Http::post($this->baseUrl . '/orders', $orderData);
        if ($response->failed()) {
            throw new BelpochtaException('Order creation failed');
        }
        return $response->json();
    }
}

Postal codes and city detection

Belarusian indexes are 6-digit, format 2XXXXX. Minsk ranges 220000–220137:

public function validateBelarusPostalCode(string $code): bool
{
    return (bool)preg_match('/^2[0-9]{5}$/', $code);
}

public function getCityByIndex(string $postalCode): ?string
{
    return Cache::remember("belpochta_city_{$postalCode}", now()->addWeek(), function () {
        return Http::get('https://api.belpochta.by/v1/address/by-index', [
            'index' => $postalCode,
        ])->json('city');
    });
}

EMS Belpochta

For urgent shipments, EMS service available. Delivery: 1–3 working days to regional centers:

public function calculateEms(float $weightKg): array
{
    $emsTariffs = [
        0.5  => 8.50,  1.0  => 10.20,  2.0  => 13.40,
        5.0  => 19.60, 10.0 => 28.90,  20.0 => 42.50,
    ];

    $price = null;
    foreach ($emsTariffs as $maxWeight => $tariff) {
        if ($weightKg <= $maxWeight) { $price = $tariff; break; }
    }

    return [
        'cost'     => $price,
        'currency' => 'BYN',
        'min_days' => 1,
        'max_days' => 3,
    ];
}

Currency conversion

If store uses RUB but Belpochta uses BYN:

public function convertToDisplayCurrency(float $byn): float
{
    $rate = Cache::remember("exchange_BYN_RUB", now()->addHour(), function () {
        return Http::get('https://api.nbrb.by/exrates/rates/RUB')->json('Cur_OfficialRate');
    });
    return round($byn * $rate, 2);
}

Timeline

Basic calculator with tariff tables — 2–3 days. Full API integration (requires contract) — 5–7 days.