Підключаємо 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 днів. Пишіть нам для оцінки вашого проекту.