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

Представьте: покупатель кладёт в корзину товар весом 0,2 кг, калькулятор магазина показывает 3,20 BYN, а на сайте Белпочты — 5,10 BYN. Разница в 2 рубля, и клиент уходит к конкуренту. Подвох в границах весовых категорий: тариф на 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 = '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?

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