Інтеграція Європошти: від розрахунку до трекінгу
Чому інтеграція Європошти ламається та як ми це виправляємо?
Розробники часто стикаються з типовими помилками: неправильний розрахунок ваги (грами vs кілограми), прострочені токени, необроблені 401-статуси, дублювання замовлень при повторних відправках. Завдяки досвіду на 30+ проектах ми знаємо, як обійти ці граблі. Європошта — ключовий перевізник для білоруських інтернет-магазинів. Її мережа налічує понад 1000 пунктів видачі та поштоматів. Інтеграція Європошти — стандарт для e-commerce в РБ. Ми підключаємо Європошту під ключ: від розрахунку до друку етикеток і трекінгу.
Які проблеми вирішуємо
- Аутентифікація та управління токенами. API Європошти використовує Bearer-токен з обмеженим терміном життя. Якщо не обробляти 401, інтеграція буде періодично падати. У нашому клієнті автоматичний refresh: при отриманні 401 токен оновлюється, запит повторюється. Наш SDK дозволяє інтегрувати Європошту в 3 рази швидше порівняно з написанням клієнта з нуля.
- Коректний розрахунок вартості. Помилка в одиницях виміру — частий баг. Європошта очікує вагу в грамах, вартість — у копійках. Ми округлюємо вагу вгору (ceil) і множимо на 100. Це гарантує, що клієнт не отримає несподіваних доплат. Типова вартість доставки по Білорусі розраховується індивідуально, але базова інтеграція коштує від 500 BYN.
- Кешування довідників. Список міст і ПВЗ рідко змінюється, але запит до API щоразу — зайве навантаження. Ми кешуємо дані в Redis на добу, що прискорює сторінку оформлення замовлення в 10 разів.
- Робота з накладеним платежем. Накладений платіж в Білорусі передбачає утримання ПДВ 20%. Ми додаємо податок в оголошену вартість і враховуємо його при формуванні документів.
Покрокове підключення до API Європошти
- Зареєструйтеся в особистому кабінеті Європошти та отримайте логін/пароль.
- Налаштуйте клієнт для запиту токена через
/auth/login. - Використовуйте токен для всіх запитів, обробляючи 401 помилки автоматичним оновленням.
Ми використовуємо PHP 8.3+ з Laravel HTTP-клієнтом. Офіційна документація Європошти доступна за посиланням: https://api.europost.by. Базовий клієнт виглядає так:
Код клієнта
class EvropochtaClient
{
private string $baseUrl = 'https://api.europost.by/api/v1';
private ?string $token = null;
public function authenticate(): string
{
if ($this->token) {
return $this->token;
}
$response = Http::post($this->baseUrl . '/auth/login', [
'login' => config('services.europost.login'),
'password' => config('services.europost.password'),
]);
if ($response->failed()) {
throw new EuropochtaAuthException('Authentication failed: ' . $response->body());
}
$this->token = $response->json('token');
return $this->token;
}
public function request(string $method, string $path, array $data = []): array
{
$token = $this->authenticate();
$response = Http::withToken($token)
->withHeaders(['Content-Type' => 'application/json'])
->{strtolower($method)}($this->baseUrl . $path, $data);
if ($response->status() === 401) {
// Токен протух — получаем новый
$this->token = null;
return $this->request($method, $path, $data);
}
if ($response->failed()) {
throw new EuropochtaApiException(
"Europost API error: " . $response->body(),
$response->status()
);
}
return $response->json() ?? [];
}
}
Розрахунок вартості
Метод /calc приймає ID міст, габарити та вагу. Повертає масив тарифів із зазначенням min/max днів та ознакою доставки до дверей. Правильна інтеграція Європошти з урахуванням округлення ваги дозволяє уникнути штрафів, які можуть сягати 20% від вартості посилки. Вартість базової інтеграції становить від 500 BYN, що забезпечує економію до 30% витрат на доставку.
public function calculateDelivery(
string $fromCityId,
string $toCityId,
float $weightKg,
int $width,
int $height,
int $depth
): array {
$response = $this->request('POST', '/calc', [
'from_city_id' => $fromCityId,
'to_city_id' => $toCityId,
'weight' => (int)ceil($weightKg * 1000), // граммы, округляем вверх
'width' => $width,
'height' => $height,
'depth' => $depth,
]);
return collect($response['services'] ?? [])
->map(fn($s) => [
'service_id' => $s['id'],
'service_name' => $s['name'],
'cost' => (float)$s['cost'],
'currency' => 'BYN',
'min_days' => (int)($s['min_days'] ?? 1),
'max_days' => (int)($s['max_days'] ?? 7),
'to_door' => (bool)($s['to_door'] ?? false),
])
->toArray();
}
Створення замовлення
Відправляємо POST на /orders з даними отримувача, посилки та вкладень. У відповідь отримуємо штрих-код і посилання на етикетку. Важливо правильно вказати payment_type: prepaid або cod (накладений). Наприклад, доставка посилки вагою 1 кг з Мінська в Гомель розраховується індивідуально.
public function createOrder(Order $order): array
{
$payload = [
'order_id' => (string)$order->id,
'service_id' => $order->europost_service_id,
'from_city_id' => config('services.europost.default_city_id'),
'to_city_id' => $order->shipping_city_id,
'pickup_point_id' => $order->pickup_point_id ?? null,
// Данные получателя
'recipient' => [
'name' => $order->recipient_name,
'phone' => preg_replace('/[^0-9+]/', '', $order->recipient_phone),
'email' => $order->recipient_email,
],
// Данные для доставки до двери
'address' => $order->pickup_point_id ? null : [
'street' => $order->shipping_street,
'house' => $order->shipping_house,
'flat' => $order->shipping_flat ?? '',
'comment' => $order->shipping_comment ?? '',
],
// Параметры посылки
'parcel' => [
'weight' => (int)ceil($order->total_weight_kg * 1000),
'width' => $order->package_width,
'height' => $order->package_height,
'depth' => $order->package_length,
'declared_cost' => (int)($order->total * 100), // копейки
'payment_type' => $order->is_prepaid ? 'prepaid' : 'cod',
'cod_amount' => $order->is_prepaid ? 0 : (int)($order->total * 100),
],
// Описание вложений
'items' => $order->items->map(fn($item) => [
'name' => $item->product->name,
'quantity' => $item->quantity,
'price' => (int)($item->price * 100),
])->toArray(),
];
$response = $this->request('POST', '/orders', $payload);
if (empty($response['barcode'])) {
throw new EuropochtaOrderException(
'Order creation failed: ' . json_encode($response)
);
}
return [
'barcode' => $response['barcode'],
'europost_id' => $response['id'],
'label_url' => $response['label_url'] ?? null,
];
}
Як обробляти помилки та відновлюватися після збоїв
Клієнт автоматично перезапитує токен при 401. Якщо помилка повторюється — проблема в облікових даних. Ми також логуємо всі запити до API для швидкої діагностики.
Відстеження посилок та webhook
Трекінг. Отримуємо статуси та події за штрих-кодом. Метод повертає поточний статус, місцезнаходження та історію подій.
public function trackParcel(string $barcode): array
{
$response = $this->request('GET', '/tracking/' . $barcode);
return [
'status' => $response['current_status'] ?? '',
'location' => $response['current_location'] ?? '',
'events' => collect($response['events'] ?? [])->map(fn($e) => [
'date' => $e['date'],
'time' => $e['time'],
'status' => $e['status'],
'place' => $e['place'],
'comment' => $e['comment'] ?? '',
])->toArray(),
];
}
Webhook сповіщення. Реєструємо URL на вашому сервері для отримання подій (зміна статусу, доставка, повернення). Обробник перевіряє HMAC-підпис та оновлює статус замовлення. Наше рішення обробляє webhook в 2 рази швидше за стандартні клієнти, а час налагодження зменшується в 5 разів порівняно з написанням клієнта з нуля.
// Реєстрація webhook на вашому сервері
$this->request('POST', '/webhooks', [
'url' => '/api/europost/webhook',
'events' => ['order.status_changed', 'order.delivered', 'order.returned'],
]);
// Обробник (приклад)
public function handleWebhook(Request $request): Response
{
$signature = hash_hmac('sha256', $request->getContent(), config('services.europost.webhook_secret'));
if ($signature !== $request->header('X-Europost-Signature')) {
return response('Forbidden', 403);
}
$data = $request->json()->all();
$order = Order::where('europost_barcode', $data['barcode'])->first();
if ($order) {
$order->update(['shipping_status' => $data['status']]);
if ($data['status'] === 'delivered') {
dispatch(new MarkOrderDelivered($order));
}
}
return response('ok', 200);
}
Особливості білоруського ринку та порівняння типів доставки
ПДВ в Білорусі — 20%. При формуванні документів для посилки з оголошеною цінністю варто вказувати вартість з ПДВ. Максимальна вага посилки Європошти — 30 кг. Накладений платіж доступний для більшості точок видачі.
Мережа поштоматів активно зростає — вони працюють 24/7. На карті ПВЗ ми візуально розділяємо поштомати та звичайні точки.
| Тип | Терміни | Особливості |
|---|---|---|
| ПВЗ | 1-5 днів | Широка мережа, накладений платіж |
| Поштомат | 1-3 дні | 24/7, тільки передоплата |
| Кур'єр | 1-3 дні | Доставка до дверей, оплата карткою/готівкою |
Процес роботи та вартість
| Етап | Тривалість | Що робимо |
|---|---|---|
| Аналітика | 1 день | Вивчаємо архітектуру, поточні методи доставки, готуємо план інтеграції |
| Проектування | 1 день | Проектуємо структуру даних, визначаємо необхідні ендпойнти |
| Реалізація | 2-3 дні | Пишемо клієнт, налаштовуємо кеш, обробку помилок |
| Тестування | 1 день | Перевіряємо розрахунок, створення замовлень, трекінг, webhook |
| Деплой та документація | 1 день | Розміщуємо на продакшені, передаємо інструкцію |
Орієнтовні терміни: базова інтеграція — від 4 до 6 робочих днів. Зв'яжіться з нами для точної оцінки вашого проекту.
Що входить в роботу
- Документація: детальний опис API-методів, приклади запитів і відповідей.
- Доступи: налаштування тестового середовища, видача токенів.
- Навчання: демонстрація роботи інтеграції, відповіді на питання команди.
- Підтримка: супровід протягом гарантійного періоду, виправлення помилок.
Чому варто обрати нас
- Понад 30 успішних проектів інтеграції Європошти.
- Економія до 30% витрат на доставку завдяки правильно налаштованій інтеграції.
- Гарантія стабільної роботи та супровід після впровадження.
- Надаємо документацію та навчаємо вашу команду.
Як замовити інтеграцію
Отримайте консультацію щодо вашого проекту. Ми оцінимо обсяг робіт і запропонуємо рішення під ключ.