Інтеграція Європошти на сайт: API, доставка, трекінг

Інтеграція Європошти: від розрахунку до трекінгу

Чому інтеграція Європошти ламається та як ми це виправляємо?

Розробники часто стикаються з типовими помилками: неправильний розрахунок ваги (грами vs кілограми), прострочені токени, необроблені 401-статуси, дублювання замовлень при повторних відправках. Завдяки досвіду на 30+ проектах ми знаємо, як обійти ці граблі. Європошта — ключовий перевізник для білоруських інтернет-магазинів. Її мережа налічує понад 1000 пунктів видачі та поштоматів. Інтеграція Європошти — стандарт для e-commerce в РБ. Ми підключаємо Європошту під ключ: від розрахунку до друку етикеток і трекінгу.

Які проблеми вирішуємо

• Аутентифікація та управління токенами. API Європошти використовує Bearer-токен з обмеженим терміном життя. Якщо не обробляти 401, інтеграція буде періодично падати. У нашому клієнті автоматичний refresh: при отриманні 401 токен оновлюється, запит повторюється. Наш SDK дозволяє інтегрувати Європошту в 3 рази швидше порівняно з написанням клієнта з нуля.
• Коректний розрахунок вартості. Помилка в одиницях виміру — частий баг. Європошта очікує вагу в грамах, вартість — у копійках. Ми округлюємо вагу вгору (ceil) і множимо на 100. Це гарантує, що клієнт не отримає несподіваних доплат. Типова вартість доставки по Білорусі розраховується індивідуально, але базова інтеграція коштує від 500 BYN.
• Кешування довідників. Список міст і ПВЗ рідко змінюється, але запит до API щоразу — зайве навантаження. Ми кешуємо дані в Redis на добу, що прискорює сторінку оформлення замовлення в 10 разів.
• Робота з накладеним платежем. Накладений платіж в Білорусі передбачає утримання ПДВ 20%. Ми додаємо податок в оголошену вартість і враховуємо його при формуванні документів.

Покрокове підключення до API Європошти

1. Зареєструйтеся в особистому кабінеті Європошти та отримайте логін/пароль.
2. Налаштуйте клієнт для запиту токена через /auth/login.
3. Використовуйте токен для всіх запитів, обробляючи 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. На карті ПВЗ ми візуально розділяємо поштомати та звичайні точки.

Процес роботи та вартість

Орієнтовні терміни: базова інтеграція — від 4 до 6 робочих днів. Зв'яжіться з нами для точної оцінки вашого проекту.

Що входить в роботу

• Документація: детальний опис API-методів, приклади запитів і відповідей.
• Доступи: налаштування тестового середовища, видача токенів.
• Навчання: демонстрація роботи інтеграції, відповіді на питання команди.
• Підтримка: супровід протягом гарантійного періоду, виправлення помилок.

Чому варто обрати нас

• Понад 30 успішних проектів інтеграції Європошти.
• Економія до 30% витрат на доставку завдяки правильно налаштованій інтеграції.
• Гарантія стабільної роботи та супровід після впровадження.
• Надаємо документацію та навчаємо вашу команду.

Як замовити інтеграцію

Отримайте консультацію щодо вашого проекту. Ми оцінимо обсяг робіт і запропонуємо рішення під ключ.