שילוב 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 וסוד API:

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

פרטי כניסה לסביבת בדיקות: 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(); } } , apiKey = demo-key לבדיקות. מפתחות אמיתיים מתקבלים מפורטל המפתחים של DHL.

חישוב תעריפים וזמני משלוח

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 לפני השליחה. תמיד בדקו כל פונקציה בסביבת הבדיקות.

כיצד לבצע אוטומציה של הצהרת מכס?

הצהרת מכס היא חובה עבור כל המשלוחים הבינלאומיים של DHL Express. אנו מבצעים אוטומציה של מילוי ההצהרה: קודי HS נשלפים ממאגר המוצרים; התיאור והערך נוצרים על בסיס ההזמנה. זה מבטל הזנה ידנית ומפחית את סיכון השגיאות. בסביבת הבדיקות, בדקו את מילוי ההצהרה לפני המעבר לייצור.

מה כלול בעבודה?

• תיעוד אינטגרציה של API.
• מפתחות גישה לסביבת בדיקות וייצור.
• הדרכת מפעילים על טיפול בהזמנות.
• תמיכה טכנית למשך 3 חודשים לאחר העלייה לאוויר.
• אחריות לתפקוד תקין של כל הפונקציות.

תהליך

1. ניתוח: בחינת מגוון המוצרים, היעדים, היקף ההזמנות.
2. עיצוב: בחירת מוצר DHL, תוכנית משלוח.
3. יישום: אינטגרציה של API, הגדרת הצהרות מכס.
4. בדיקות: בסביבת בדיקות עם מפתחות אמיתיים.
5. עלייה לאוויר: מעבר לסביבת ייצור.

לוח זמנים

אינטגרציה של DHL Express עבור חנות מסחר אלקטרוני: בין 5 ל-7 ימי עבודה. הגדרת מכס נוספת: עוד 2–3 ימים.

כיצד להימנע משגיאות אימות?

בדקו שאתם משתמשים ב-API הנכון: DHL Express (Basic Auth) או DHL eCommerce (OAuth 2.0). ודאו שהבקשה כוללת את apiSecret = demo-secret ו-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', ]; } . לייצור, השתמשו במפתחות מחשבון המפתחים שלכם ב-DHL.

צרו קשר כדי לדון באינטגרציה של DHL API עבור הפרויקט שלכם. אנו מבטיחים פעולה תקינה ומספקים תמיכה. הזמינו אינטגרציה היום.