Інтеграція служби доставки Белпошти на сайт

Інтеграція служби доставки Белпошти на сайт

Белпошта — національний поштовий оператор Беларуси. Для інтернет-магазинів, що працюють з білоруськими покупцями, інтеграція Белпошти забезпечує доставку по всій країні з охопленням найвідаленіших населених пунктів. API Белпошти менш зріла, ніж у російських служб, тому частина функціоналу реалізується через власні розрахунки на основі офіційних тарифних таблиць.

Статус API

На момент написання Белпошта надає API через особистий кабінет корпоративним клієнтам. Для невеликих магазинів без договору з Белпоштою розрахунок вартості будується на основі публічних тарифних таблиць, розташованих на офіційному сайті.

Розрахунок за тарифними таблицями

Тарифи Белпошти структуровані за ваговими категоріями та зонами доставки (усередину Мінська, по Беларуси, міжнародні):

class BelpochtaTariffCalculator
{
    // Тарифи на посилки в межах Беларуси (актуальні на 2025 рік, BYN)
    private array $domesticParcels = [
        // [макс_вага_кг => базова_ціна_BYN]
        0.1  => 3.20,
        0.25 => 3.70,
        0.5  => 4.30,
        1.0  => 5.10,
        2.0  => 6.40,
        3.0  => 7.70,
        5.0  => 9.60,
        10.0 => 13.50,
        15.0 => 17.20,
        20.0 => 20.80,
        31.5 => 25.60,
    ];

    // Надбавка за доставку до дверей (кур'єр)
    private float $courierSurcharge = 3.50;

    // Задекларована вартість: 0.5% від суми, мінімум 0.50 BYN
    public function calculateDeclaredValueFee(float $value): float
    {
        return max(0.50, $value * 0.005);
    }

    public function calculate(
        float  $weightKg,
        bool   $toDoor = false,
        float  $declaredValue = 0,
        string $type = 'parcel' // parcel, small_packet, ems
    ): array {
        $basePrice = null;

        foreach ($this->domesticParcels as $maxWeight => $price) {
            if ($weightKg <= $maxWeight) {
                $basePrice = $price;
                break;
            }
        }

        if ($basePrice === null) {
            throw new \InvalidArgumentException('Вага перевищує максимально допустиму (31.5 кг)');
        }

        $total = $basePrice;

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

        if ($declaredValue > 0) {
            $total += $this->calculateDeclaredValueFee($declaredValue);
        }

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

Інтеграція через корпоративне API

Для клієнтів з договором доступне API через особистий кабінет. Авторизація — API-ключ у заголовку:

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'),
            'Content-Type'  => 'application/json',
        ])->post($this->baseUrl . '/calc', [
            'from_index'  => $params['from_index'],
            'to_index'    => $params['to_index'],
            'weight'      => (int)($params['weight_kg'] * 1000), // грами
            'length'      => $params['length'] ?? 0,
            'width'       => $params['width'] ?? 0,
            'height'      => $params['height'] ?? 0,
            'service_type'=> $params['service_type'] ?? 'PARCEL',
        ]);

        return $response->json();
    }

    public function createOrder(array $orderData): array
    {
        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . config('services.belpochta.api_key'),
        ])->post($this->baseUrl . '/orders', $orderData);

        if ($response->failed()) {
            throw new BelpochtaException('Order creation failed: ' . $response->body());
        }

        return $response->json();
    }
}

Поштові індекси Беларуси

Білоруські індекси — 6-значні. Формат: XXXXXX. Мінськ — індекси від 220000 до 220137. При введенні адреси варто додати валідацію:

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

// Визначення міста за індексом через довідник FIAS-BY
public function getCityByIndex(string $postalCode): ?string
{
    return Cache::remember("belpochta_city_{$postalCode}", now()->addWeek(), function () use ($postalCode) {
        $response = Http::get('https://api.belpochta.by/v1/address/by-index', [
            'index' => $postalCode,
        ]);
        return $response->json('city');
    });
}

EMS Белпошта

Для невідкладних відправлень — сервіс EMS. Строки доставки по Беларусі: 1–3 робочих дні до обласних центрів, 2–5 днів — малі населені пункти.

public function calculateEms(string $fromIndex, string $toIndex, float $weightKg): array
{
    // EMS-тарифи відрізняються від звичайних посилок
    $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,
        31.5 => 58.00,
    ];

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

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

Відстеження через публічний трекінг

Белпошта надає сторінку відстеження. Для програмного відстеження без договору використовується парсинг або неофіційне API:

public function trackParcel(string $trackNumber): array
{
    // Офіційний трекінг: https://www.belpochta.by/track/
    // Для корпоративних клієнтів — API
    $response = Http::withHeaders([
        'Authorization' => 'Bearer ' . config('services.belpochta.api_key'),
    ])->get($this->baseUrl . '/tracking/' . $trackNumber);

    if ($response->notFound()) {
        return ['error' => 'Відправлення не знайдено'];
    }

    return collect($response->json('events') ?? [])
        ->map(fn($e) => [
            'date'    => $e['date'],
            'time'    => $e['time'],
            'status'  => $e['operation'],
            'place'   => $e['place'],
            'index'   => $e['index'],
        ])
        ->toArray();
}

Особливості для інтернет-магазинів

Накладений платіж через Белпошту вимагає окремого договору. Комісія за накладений платіж — 1.5% від суми, мінімум 0.70 BYN. При накладеному платежі гроші переводяться відправнику банківським переводом.

Максимальна сума накладеного платежу — 500 BYN на одну посилку. Для дорожчих товарів потрібна передплата або інші способи розрахунку.

Конвертація валют

Якщо магазин працює в рублях, а Белпошта — в BYN, потрібна конвертація:

public function convertToDisplayCurrency(float $byn, string $targetCurrency = 'RUB'): float
{
    $rate = Cache::remember("exchange_rate_BYN_{$targetCurrency}", now()->addHour(), function () use ($targetCurrency) {
        $response = Http::get('https://api.nbrb.by/exrates/rates/' . $targetCurrency, [
            'periodicity' => 0,
        ]);
        return $response->json('Cur_OfficialRate');
    });

    return round($byn * $rate, 2);
}

Національний банк Беларуси надає безплатне API курсів валют.

Строки

Базовий калькулятор за тарифними таблицями — 2–3 дні. Повна інтеграція з API (вимагає договору з Белпоштою) — 5–7 днів.