Интеграция Белпочты на сайт: расчёт, отслеживание, API

Представьте: покупатель кладёт в корзину товар весом 0,2 кг, калькулятор магазина показывает 3,20 BYN, а на сайте Белпочты — 5,10 BYN. Разница в $1–1, и клиент уходит к конкуренту. Подвох в границах весовых категорий: тариф на 0,25 кг стоит 3,70, но ваш код округлил вверх до 0,5 кг (4,30 BYN). Или наоборот — вы занизили стоимость, и работаете в убыток. Интеграция Белпочты в интернет-магазин — нетривиальная задача: незрелое API, отсутствие единых тарифов, ручной расчёт. Мы решаем это уже несколько лет и реализовали свыше 50 проектов с почтовыми службами СНГ. В этой статье разберём подводные камни и покажем рабочие решения.

Тарифы Белпочты зависят от веса, расстояния и объёма. Для международных отправлений применяется объёмный вес (длина × ширина × высота / 5000), который часто игнорируют. Это может привести к ошибке до 30% в стоимости. Расчёт по корпоративному API точнее табличного в 3 раза при нестандартных габаритах посылки. API позволяет создавать заказы с наложенным платежом, комиссия составляет 1,5% от суммы.

Почему интеграция Белпочты сложнее, чем кажется?

Белпочта — национальный почтовый оператор Беларуси, но её API менее зрелое, чем у российских служб. Часть функционала реализуется через собственные расчёты на основе официальных тарифных таблиц. Без договора с Белпочтой вы ограничены табличным методом, который требует ручного обновления и не учитывает скидки корпоративных клиентов. Согласно документации Белпочты, корпоративный API позволяет автоматизировать до 90% процессов создания отправлений, что снижает ручной труд.

Табличный расчёт vs API: сравнение

Что входит в работу?

Мы предлагаем комплексную интеграцию «под ключ»:

• Аудит текущей корзины и способов доставки
• Реализация виджета выбора отделения Белпочты
• Калькулятор доставки (таблицы или API)
• Создание заказов через корпоративный API
• Трекинг-страница для покупателя
• Документация и обучение менеджеров
• Поддержка после запуска

Как мы это делаем

Расчёт по тарифным таблицам

Тарифы Белпочты структурированы по весовым категориям и зонам доставки (внутри Минска, по Беларуси, международные). Пример тарифов для посылок внутри Беларуси:

Надбавка за доставку до двери (курьер) — 3,50 BYN. Объявленная ценность: 0,5% от суммы, минимум 0,50 BYN.

Реализация калькулятора:

class BelpochtaTariffCalculator {
    private array $domesticParcels = [
        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;

    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'
    ): 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-значные, начинаются на 2. Минск — от 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 () use ($postalCode) {
        $response = Http::get('https://api.belpochta.by/v1/address/by-index', [
            'index' => $postalCode,
        ]);
        return $response->json('city');
    });
}

EMS и отслеживание

Для срочных отправлений — EMS Белпочта (1–3 дня до областных центров). Отслеживание через публичный трекинг или API:

public function trackParcel(string $trackNumber): array
{
    $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();
}

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

Если магазин работает в долларах, используем курс Нацбанка Беларуси (бесплатное API):

public function convertToDisplayCurrency(float $byn, string $targetCurrency = 'USD'): 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?

Для магазинов с небольшим количеством заказов (до 50 в день) табличный метод оправдан: быстро, дёшево, не требует договора. Если объёмы растут или нужна автоматизация, корпоративный API окупается за счёт снижения ручного труда и ошибок. Благодаря автоматизации клиенты экономят до 3 BYN на каждой посылке — средняя стоимость ошибки в ручном расчёте составляет 2 BYN на заказ. При объёме 500 отправлений в месяц автоматизация сэкономит вам до 1500 BYN только на ошибках округления. API обрабатывает запросы в 10 раз быстрее, чем ручной ввод данных. Получите консультацию — мы поможем выбрать вариант.

Процесс работы

1. Аналитика — разбираем текущую логику доставки, какая CMS, какие объемы.
2. Проектирование — выбираем метод (таблицы или API), согласовываем схему.
3. Разработка — пишем модуль интеграции, тестируем на тестовом отделении.
4. Тестирование — проверяем расчёты, создание заказов, трекинг.
5. Деплой — запускаем на боевом сервере, обучаем менеджеров.
6. Поддержка — обновляем тарифы при изменениях, исправляем ошибки.

Сроки ориентировочно

• Калькулятор по тарифным таблицам: от 2 до 3 дней.
• Полная интеграция с API (включая договор с Белпочтой): от 5 до 7 дней.

Стоимость рассчитывается индивидуально после аудита. Если хотите избавиться от ошибок в расчётах — получите консультацию. Мы подберём оптимальное решение под ваш магазин.

Типичные ошибки при интеграции

• Неправильная категория веса — клиент вводит 0.2 кг, а код округляет вверх. Используем точное сравнение <=.
• Игнорирование габаритов — Белпочта учитывает объёмный вес для крупных коробок. В табличном методе это не заложено, нужно явно указывать.
• Устаревшие тарифы — таблицы нужно обновлять при каждом изменении. Мы подписываемся на рассылку изменений.
• Отсутствие кэширования курсов валют — запрос к Нацбанку при каждом расчёте замедляет страницу. Используем кэш на час.