Підключаємо DHL Express API: розрахунок, відправлення та відстеження

public function __construct( private string $apiKey, private string $apiSecret, private bool $sandbox = false ) { if ($sandbox) { // Sandbox: інший URL // https://express.api.dhl.com/mydhlapi/test } } public function request(string $method, string $path, array $params = []): array { $url = ($this->sandbox ? 'https://express.api.dhl.com/mydhlapi/test' : self::BASE_URL) . $path; $response = Http::withBasicAuth($this->apiKey, $this->apiSecret) ->withHeaders(['Content-Type' => 'application/json']) ->{strtolower($method)}($url, $params); if ($response->clientError()) { $error = $response->json(); throw new DhlApiException( $error['detail'] ?? $error['title'] ?? 'DHL API error', $response->status() ); } return $response->json(); } 

}

</details> Sandbox credentials: `apiKey = demo-key`, `apiSecret = demo-secret` — для тестування. Реальні ключі отримують в <cite>[DHL Developer Portal](https://developer.dhl.com)</cite>. ### Розрахунок вартості DHL та термінів ```php public function getRates( array $from, // ['countryCode'=>'UA','cityName'=>'Kyiv','postalCode'=>'01001'] array $to, // ['countryCode'=>'DE','cityName'=>'Berlin','postalCode'=>'10115'] float $weightKg, array $dimensions, string $plannedShipDate ): array { $data = $this->request('GET', '/rates', [ 'accountNumber' => config('services.dhl.account_number'), 'originCountryCode' => $from['countryCode'], 'originCityName' => $from['cityName'], 'originPostalCode' => $from['postalCode'], 'destinationCountryCode' => $to['countryCode'], 'destinationCityName' => $to['cityName'], 'destinationPostalCode' => $to['postalCode'], 'weight' => $weightKg, 'length' => $dimensions['length'], 'width' => $dimensions['width'], 'height' => $dimensions['height'], 'plannedShippingDateAndTime' => $plannedShipDate . 'T10:00:00 GMT+03:00', 'isCustomsDeclarable' => true, 'unitOfMeasurement' => 'metric', ]); return collect($data['products'] ?? []) ->map(fn($p) => [ 'product_code' => $p['productCode'], 'product_name' => $p['productName'], 'currency' => $p['totalPrice'][0]['priceCurrency'], 'total_price' => $p['totalPrice'][0]['price'], 'delivery_time'=> $p['deliveryCapabilities']['deliveryTypeCode'], 'delivery_date'=> $p['deliveryCapabilities']['estimatedDeliveryDateAndTime'] ?? null, ]) ->toArray(); } 

Створення відправлення DHL

public function createShipment(Order $order): array { $payload = [ 'plannedShippingDateAndTime' => now()->addDay()->format('Y-m-d') . 'T10:00:00 GMT+03:00', 'pickup' => [ 'isRequested' => false, // false = самостійна здача на склад DHL ], 'productCode' => $order->dhl_product_code ?? 'P', 'accounts' => [ ['number' => config('services.dhl.account_number'), 'typeCode' => 'shipper'], ], 'customerDetails' => [ 'shipperDetails' => [ 'postalAddress' => [ 'postalCode' => config('services.dhl.shipper_zip'), 'cityName' => config('services.dhl.shipper_city'), 'countryCode' => 'UA', 'addressLine1'=> config('services.dhl.shipper_address'), ], 'contactInformation' => [ 'email' => config('services.dhl.contact_email'), 'phone' => config('services.dhl.contact_phone'), 'companyName' => config('services.dhl.company_name'), 'fullName' => config('services.dhl.contact_name'), ], ], 'receiverDetails' => [ 'postalAddress' => [ 'postalCode' => $order->shipping_zip, 'cityName' => $order->shipping_city, 'countryCode' => $order->shipping_country_code, 'addressLine1'=> $order->shipping_address, ], 'contactInformation' => [ 'email' => $order->recipient_email, 'phone' => $order->recipient_phone, 'fullName' => $order->recipient_name, ], ], ], 'content' => [ 'packages' => [[ 'weight' => $order->total_weight_kg, 'dimensions' => [ 'length' => $order->package_length, 'width' => $order->package_width, 'height' => $order->package_height, ], ]], 'isCustomsDeclarable' => $order->is_international, 'description' => 'E-commerce goods', 'incoterm' => 'DAP', 'unitOfMeasurement' => 'metric', // Митні документи для міжнародних відправлень 'exportDeclaration' => $order->is_international ? $this->buildExportDeclaration($order) : null, ], ]; $response = $this->request('POST', '/shipments', $payload); return [ 'shipment_id' => $response['shipmentTrackingNumber'], 'shipment_number' => $response['shipmentDetails'][0]['shipmentTrackingNumber'], 'label_pdf' => base64_decode($response['documents'][0]['content'] ?? ''), ]; } 

Митна декларація DHL

Для міжнародних відправлень обов'язкова декларація:

private function buildExportDeclaration(Order $order): array { return [ 'lineItems' => $order->items->map(fn($item, $i) => [ 'number' => $i + 1, 'description' => $item->product->name_en, // англійською 'price' => $item->price, 'priceCurrency' => 'USD', 'grossWeight' => [ 'weight' => $item->product->weight_kg, 'unitOfMeasurement' => 'kg', ], 'quantity' => [ 'value' => $item->quantity, 'unitOfMeasurement' => 'PCS', ], 'manufacturerCountry' => 'CN', 'hsCode' => $item->product->hs_code ?? '6109100000', ])->toArray(), 'invoice' => [ 'number' => 'INV-' . $order->id, 'date' => now()->format('Y-m-d'), 'signedBy' => config('services.dhl.contact_name'), 'function' => 'Seller', 'customerReference' => (string)$order->id, ], 'exportReason' => 'PERMANENT', 'exportReasonType'=> 'PERMANENT', 'placeOfIncoterm' => 'Destination', 'shipmentType' => 'commercial', ]; } 

Відстеження DHL

public function trackShipment(string $trackingNumber): array { $response = $this->request('GET', '/tracking', [ 'trackingNumber' => $trackingNumber, ]); $shipment = $response['shipments'][0] ?? null; if (!$shipment) { return []; } return [ 'status' => $shipment['status'], 'description' => $shipment['description'], 'location' => $shipment['location']['address']['cityName'] ?? '', 'events' => collect($shipment['events'])->map(fn($e) => [ 'timestamp' => $e['timestamp'], 'location' => $e['location']['address']['cityName'] ?? '', 'description'=> $e['description'], ])->toArray(), 'estimated_delivery' => $shipment['estimatedTimeOfDelivery'] ?? null, ]; } 

Обмеження та типові помилки

DHL суворо перевіряє адреси отримувачів. Неточний поштовий індекс поверне помилку. Максимальна вага одного місця — 70 кг, розмір сторони — 300 см. Типова помилка — невірний обліковий номер. Ми валідуємо адреси через Google Maps API перед відправкою. У sandbox обов'язково тестуйте кожну функцію. Вартість інтеграції — від $500.

Автоматизація митної декларації

Декларація обов'язкова для всіх міжнародних відправлень DHL Express. Ми автоматизуємо її заповнення: HS-коди підтягуються з бази товарів, опис та вартість формуються на основі замовлення. Це виключає ручне введення та знижує ризик помилок. У sandbox перевірте заповнення декларації перед продакшном.

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

• Документація по інтеграції API.
• Ключі доступу до sandbox та продакшну.
• Навчання операторів роботі з замовленнями.
• Технічна підтримка 3 місяці після деплою.
• Гарантія коректної роботи всіх функцій.

Процес роботи

1. Аналітика: вивчаємо асортимент, напрямки, обсяг замовлень.
2. Проектування: вибираємо продукт DHL, схему відправлень.
3. Реалізація: інтеграція API, налаштування митних декларацій.
4. Тестування: у sandbox з реальними ключами.
5. Деплой: розгортання на бойовому стенді.

Строки

Інтеграція DHL Express для інтернет-магазину — від 5 до 7 робочих днів. Додаткові налаштування митниці — ще 2–3 дні.

Уникнення помилок авторизації

Перевірте, що використовуєте правильний API: DHL Express (Basic Auth) або DHL eCommerce (OAuth 2.0). Переконайтеся, що в запиті є коректні apiKey та apiSecret. У sandbox використовуйте demo-key та demo-secret. Для продакшну – ключі з аккаунту DHL Developer.

Замовте інтеграцію DHL API під ключ за 5 днів. Пишіть нам для оцінки вашого проекту.