Подключаем DHL Express API: расчёт, отправление и трекинг

Подключаем DHL Express API: расчёт, отправление и трекинг

Ошибка 401 при попытке получить тарифы DHL — типичная ситуация. Разработчик тратит два дня на отладку, а проблема в неверном продукте: DHL Express и DHL eCommerce используют разные механизмы авторизации. Штатный программист неделями изучает документацию, но всё равно спотыкается о неочевидные ограничения — максимальный вес 70 кг, обязательная таможенная декларация для международных отправлений, строгая валидация адресов. Мы накопили опыт интеграции DHL Express API на 30+ проектах, от простого расчёта до полного цикла создания отправления с трекингом. Результат: прозрачная доставка, минимум ошибок, довольные клиенты. Закажите такую интеграцию — это сэкономит время и деньги.

Решаемые проблемы

• Авторизация и различия API: DHL Express (Basic Auth) и DHL eCommerce (OAuth 2.0) — разные продукты. Использование неправильного API ведёт к ошибкам 401 и неверным тарифам. Мы выбираем нужный API и настраиваем Basic Auth.
• Ошибки адресов и таможни: неверный почтовый индекс или отсутствие таможенной декларации — частые причины отказов. Мы валидируем адреса через Google Maps API и автоматизируем заполнение декларации с HS-кодами.
• Обработка ошибок: DHL возвращает детальные ошибки, но их нужно корректно обрабатывать на стороне сайта. Наша реализация выбрасывает исключения с понятными сообщениями, что сокращает время отладки на 50%.

Как мы интегрируем

Используем паттерн Repository для изоляции DHL API. Все запросы проходят через единый клиент, который обрабатывает авторизацию и ошибки. Для одного мультибрендового магазина электроники с отправками в 20 стран мы интегрировали DHL Express API, добавили таможенные декларации с автозаполнением HS-кодов. Результат: время обработки заказа сократилось на 40%, количество ошибок при создании отправлений — на 70%.

Сравнение продуктов DHL Express и DHL eCommerce

Коды продуктов DHL Express

Техническая реализация

Авторизация

DHL Express API использует Basic Auth с API key и API secret:

class DhlExpressClient {
    private const BASE_URL = 'https://express.api.dhl.com/mydhlapi';

    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();
    }
}

Sandbox credentials: apiKey = demo-key, apiSecret = demo-secret — для тестирования. Реальные ключи получают в DHL Developer Portal.

Расчёт стоимости и сроков

public function getRates(
    array $from, // ['countryCode'=>'RU','cityName'=>'Moscow','postalCode'=>'101000']
    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();
}

Создание отправления

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' => 'RU',
                    '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'] ?? ''),
    ];
}

Таможенная декларация

Для международных отправлений обязательна:

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',
    ];
}

Отслеживание

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 обязательно тестируйте каждую функцию.

Как автоматизировать таможенную декларацию?

Таможенная декларация обязательна для всех международных отправлений 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 под ваш проект. Мы гарантируем корректную работу и предоставляем поддержку. Закажите интеграцию уже сегодня.