Представьте: покупатель кладёт в корзину товар весом 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 |
|---|---|---|
| Точность | Погрешность до 15% при нестандартных габаритах | 100% точность |
| Автоматизация | Требует ручного обновления | Полная автоматизация |
| Создание отправлений | Вручную | Через API |
| Отслеживание | Только публичная страница | Встроенный трекинг |
| Требования | Нет | Договор и API-ключ |
Что входит в работу?
Мы предлагаем комплексную интеграцию «под ключ»:
- Аудит текущей корзины и способов доставки
- Реализация виджета выбора отделения Белпочты
- Калькулятор доставки (таблицы или API)
- Создание заказов через корпоративный API
- Трекинг-страница для покупателя
- Документация и обучение менеджеров
- Поддержка после запуска
Как мы это делаем
Расчёт по тарифным таблицам
Тарифы Белпочты структурированы по весовым категориям и зонам доставки (внутри Минска, по Беларуси, международные). Пример тарифов для посылок внутри Беларуси:
| Вес, кг | Цена, 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 |
Надбавка за доставку до двери (курьер) — 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 раз быстрее, чем ручной ввод данных. Получите консультацию — мы поможем выбрать вариант.
Процесс работы
- Аналитика — разбираем текущую логику доставки, какая CMS, какие объемы.
- Проектирование — выбираем метод (таблицы или API), согласовываем схему.
- Разработка — пишем модуль интеграции, тестируем на тестовом отделении.
- Тестирование — проверяем расчёты, создание заказов, трекинг.
- Деплой — запускаем на боевом сервере, обучаем менеджеров.
- Поддержка — обновляем тарифы при изменениях, исправляем ошибки.
Сроки ориентировочно
- Калькулятор по тарифным таблицам: от 2 до 3 дней.
- Полная интеграция с API (включая договор с Белпочтой): от 5 до 7 дней.
Стоимость рассчитывается индивидуально после аудита. Если хотите избавиться от ошибок в расчётах — получите консультацию. Мы подберём оптимальное решение под ваш магазин.
Типичные ошибки при интеграции
- Неправильная категория веса — клиент вводит 0.2 кг, а код округляет вверх. Используем точное сравнение
<=. - Игнорирование габаритов — Белпочта учитывает объёмный вес для крупных коробок. В табличном методе это не заложено, нужно явно указывать.
- Устаревшие тарифы — таблицы нужно обновлять при каждом изменении. Мы подписываемся на рассылку изменений.
- Отсутствие кэширования курсов валют — запрос к Нацбанку при каждом расчёте замедляет страницу. Используем кэш на час.
Чек-лист проверки интеграции
- Валидация веса: точное сравнение ≤, а не <.
- Учёт объёмного веса для коробок (длина × ширина × высота / 5000).
- Кэширование курсов валют (Нацбанк РБ, TTL 1 час).
- Обработка ошибок API: таймауты, недоступность, неверные индексы.
- Логирование всех запросов для аудита.
Мы гарантируем точность расчётов и полную документацию. Опыт многолетний, более 50 завершённых проектов с почтовыми службами СНГ.