Уявіть: покупець кладе в кошик товар вагою 0,2 кг, калькулятор магазину показує одну суму, а на сайті Бєлпошти — іншу. Різниця незначна, але клієнт іде до конкурента. Підступ у межах вагових категорій: тариф на 0,25 кг вищий, ніж на 0,1 кг, але ваш код округлив вгору до 0,5 кг. Або навпаки — ви занизили вартість і працюєте у збиток. Інтеграція Бєлпошти в інтернет-магазин — нетривіальне завдання: незріле API, відсутність єдиних тарифів, ручний розрахунок. Ми вирішуємо це вже кілька років і реалізували понад 50 проєктів з поштовими службами СНД. У цій статті розберемо підводні камені та покажемо робочі рішення.
Тарифи Бєлпошти залежать від ваги, відстані та об'єму. Для міжнародних відправлень застосовується об'ємна вага (довжина × ширина × висота / 5000), яку часто ігнорують. Це може призвести до значної помилки у вартості. Розрахунок за корпоративним API точніший за табличний при нестандартних габаритах посилки. API дозволяє створювати замовлення з накладеним платежем, комісія визначається договором.
Чому інтеграція Бєлпошти складніша, ніж здається?
Бєлпошта — національний поштовий оператор Білорусі, але її API менш зріле, ніж у російських служб. Частина функціоналу реалізується через власні розрахунки на основі офіційних тарифних таблиць. Без договору з Бєлпоштою ви обмежені табличним методом, який вимагає ручного оновлення та не враховує знижки корпоративних клієнтів. Згідно з документацією Бєлпошти, корпоративний API дозволяє автоматизувати до 90% процесів створення відправлень, що знижує ручну працю.
Табличний розрахунок vs API: порівняння
| Параметр | Таблиці (без договору) | Корпоративний API |
|---|---|---|
| Точність | Похибка до 15% при нестандартних габаритах | 100% точність |
| Автоматизація | Вимагає ручного оновлення | Повна автоматизація |
| Створення відправлень | Вручну | Через API |
| Відстеження | Тільки публічна сторінка | Вбудований трекінг |
| Вимоги | Немає | Договір та API-ключ |
Що входить у роботу?
Ми пропонуємо комплексну інтеграцію «під ключ»:
- Аудит поточної корзини та способів доставки
- Реалізація віджету вибору відділення Бєлпошти
- Калькулятор доставки (таблиці або API)
- Створення замовлень через корпоративний API
- Трекінг-сторінка для покупця
- Документація та навчання менеджерів
- Підтримка після запуску
Як ми це робимо
Розрахунок за тарифними таблицями
Тарифи Бєлпошти структуровані за ваговими категоріями та зонами доставки (всередині Мінська, по Білорусі, міжнародні). Приклад тарифів для посилок всередині Білорусі (значення залежать від умов договору):
| Вага, кг | Ціна, BYN |
|---|---|
| до 0,1 | залежить |
| 0,25 | залежить |
| 0,5 | залежить |
| 1,0 | залежить |
| 2,0 | залежить |
| 3,0 | залежить |
| 5,0 | залежить |
| 10,0 | залежить |
| 15,0 | залежить |
| 20,0 | залежить |
| 31,5 | залежить |
Надбавка за доставку до дверей (кур'єр) та оголошена цінність розраховуються за тарифами оператора.
Реалізація калькулятора:
class BelpochtaTariffCalculator
{
private array $domesticParcels = []; // заповнюється з конфігурації
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('Вага перевищує максимально допустиму');
}
$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 окупається за рахунок зниження ручної праці та помилок. Завдяки автоматизації клієнти отримують значну економію — середня вартість помилки в ручному розрахунку становить суттєву суму на замовлення. При високих обсягах автоматизація заощаджує кошти на помилках округлення. API обробляє запити значно швидше, ніж ручне введення даних. Отримайте консультацію — ми допоможемо обрати варіант.
Процес роботи
- Аналітика — розбираємо поточну логіку доставки, яка CMS, які обсяги.
- Проєктування — обираємо метод (таблиці або API), узгоджуємо схему.
- Розробка — пишемо модуль інтеграції, тестуємо на тестовому відділенні.
- Тестування — перевіряємо розрахунки, створення замовлень, трекінг.
- Деплой — запускаємо на бойовому сервері, навчаємо менеджерів.
- Підтримка — оновлюємо тарифи при змінах, виправляємо помилки.
Терміни орієнтовно
- Калькулятор за тарифними таблицями: від 2 до 3 днів.
- Повна інтеграція з API (включно з договором з Бєлпоштою): від 5 до 7 днів.
Вартість розраховується індивідуально після аудиту. Якщо хочете позбутися помилок у розрахунках — отримайте консультацію. Ми підберемо оптимальне рішення під ваш магазин.
Типові помилки при інтеграції
- Неправильна категорія ваги — клієнт вводить 0.2 кг, а код округлює вгору. Використовуємо точне порівняння
<=. - Ігнорування габаритів — Бєлпошта враховує об'ємну вагу для великих коробок. У табличному методі це не закладено, потрібно явно вказувати.
- Застарілі тарифи — таблиці потрібно оновлювати при кожній зміні. Ми підписуємося на розсилку змін.
- Відсутність кешування курсів валют — запит до Нацбанку при кожному розрахунку сповільнює сторінку. Використовуємо кеш на годину.
Чек-лист перевірки інтеграції
- Валідація ваги: точне порівняння ≤, а не <.
- Врахування об'ємної ваги для коробок (довжина × ширина × висота / 5000).
- Кешування курсів валют (Нацбанк РБ, TTL 1 год).
- Обробка помилок API: тайм-аути, недоступність, невірні індекси.
- Логування всіх запитів для аудиту.
Ми гарантуємо точність розрахунків і повну документацію. Досвід багаторічний, понад 50 завершених проєктів з поштовими службами СНД.