1C-Bitrix integration with DHL delivery service

Integration of 1C-Bitrix with DHL delivery service

DHL is an international express carrier with coverage in over 220 countries. For online stores, two products are relevant: DHL Express (urgent international delivery) and DHL Parcel (regional parcel delivery in Europe). They have different APIs — it's important to decide which one you're working with from the start.

DHL API: what and where

DHL Express MyDHL+ API — for international shipments. Base URL: https://express.api.dhl.com/mydhlapi. Authorization: Basic Auth (username + password from DHL Express account).

DHL Parcel Connect API — for Europe and other regions. Separate documentation, different authorization.

DHL eCommerce API — for USA and some Asian markets.

For most CIS-market projects with international delivery, DHL Express API is used — we'll focus on it.

Key DHL Express API methods

• POST /shipments — create a shipment, get AWB (Air Waybill) and PDF label
• GET /shipments/{shipmentTrackingNumber}/tracking — tracking
• POST /rates — calculate delivery cost
• POST /pickups — order a pickup

Module architecture in Bitrix

The delivery class inherits from \Bitrix\Sale\Delivery\Services\Base. Settings in b_sale_delivery_service_params:

• DHL_USERNAME, DHL_PASSWORD — credentials from DHL Express
• SHIPPER_ACCOUNT — DHL account number (AccountNumber)
• SHIPPER_ADDRESS — shipper address (used in each request)
• DEFAULT_PRODUCT_CODE — product code, for example P (DHL Express Worldwide)

Cost calculation (Rates)

$ratesRequest = [
    'customerDetails' => [
        'shipperDetails' => [
            'postalCode'   => '220004',
            'cityName'     => 'Minsk',
            'countryCode'  => 'BY',
        ],
        'receiverDetails' => [
            'postalCode'   => '10115',
            'cityName'     => 'Berlin',
            'countryCode'  => 'DE',
        ],
    ],
    'accounts' => [['typeCode' => 'shipper', 'number' => $accountNumber]],
    'productCode' => 'P',
    'localProductCode' => 'P',
    'packages' => [[
        'weight'     => $weightKg,
        'dimensions' => ['length' => 30, 'width' => 20, 'height' => 15],
    ]],
    'plannedShippingDateAndTime' => date('Y-m-d\TH:i:s \G\M\T+0000'),
    'unitOfMeasurement' => 'metric',
];

The response contains an array products with prices for different service options. Select the required productCode and provide the totalPrice to the customer.

Creating a shipment and printing a label

This is the central operation: when creating a shipment, DHL returns an AWB number for tracking and a PDF/ZPL file for printing the label.

In the POST /shipments request, the following are required:

• complete sender and recipient addresses with phone number
• content description (packages[].description)
• customs data for international shipments (content.exportDeclaration)

We save the AWB number in b_sale_order_props as the DHL_AWB property. We provide the PDF label to the manager through the Bitrix admin interface — add a "Print DHL Label" button to the order form.

Customs declarations

For international shipments, DHL requires an export declaration with a list of goods: exportLineItems with fields commodityCode (HS code), exportReasonType, manufacturerCountry. We get the data from product properties in b_iblock_element_prop or from custom order fields.

If the store works with B2B customers and needs an invoice, the DHL API can generate a Commercial Invoice — we pass content.exportDeclaration.invoice.

Shipment tracking

GET /shipments/{awb}/tracking?shipmentTrackingNumber={awb}&trackingView=all-checkpoints

The response is an array shipments[0].events with movement history. We integrate it into the customer's personal account on Bitrix: we supplement the sale.personal.order component with a tracking history block loaded via AJAX.

Order a pickup

POST /pickups

You can automatically create a pickup request when orders accumulate during the day or provide the manager with a "Order DHL Pickup" button in the admin panel.

Timeline