Интеграция 1С-Битрикс со службой доставки DHL

Интеграция 1С-Битрикс со службой доставки DHL

DHL — международный экспресс-перевозчик с покрытием более 220 стран. Для интернет-магазинов актуальны два продукта: DHL Express (срочная международная доставка) и DHL Parcel (региональная посылочная доставка в Европе). API у них разные — важно сразу определиться, с каким именно работаем.

API DHL: что и где

DHL Express MyDHL+ API — для международных отправлений. Базовый URL: https://express.api.dhl.com/mydhlapi. Авторизация: Basic Auth (username + password от аккаунта DHL Express).

DHL Parcel Connect API — для Европы и ряда других регионов. Отдельная документация, другая авторизация.

DHL eCommerce API — для США и некоторых азиатских рынков.

В большинстве проектов для СНГ-рынков с международной доставкой используется DHL Express API — сосредоточимся на нём.

Ключевые методы DHL Express API

• POST /shipments — создать отправление, получить AWB (Air Waybill) и PDF ярлыка
• GET /shipments/{shipmentTrackingNumber}/tracking — трекинг
• POST /rates — расчёт стоимости доставки
• POST /pickups — заказ забора груза курьером

Архитектура модуля в Битрикс

Класс доставки наследует \Bitrix\Sale\Delivery\Services\Base. Настройки в b_sale_delivery_service_params:

• DHL_USERNAME, DHL_PASSWORD — credentials от DHL Express
• SHIPPER_ACCOUNT — номер аккаунта DHL (AccountNumber)
• SHIPPER_ADDRESS — адрес отправителя (используется в каждом запросе)
• DEFAULT_PRODUCT_CODE — код продукта, например P (DHL Express Worldwide)

Расчёт стоимости (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',
];

Ответ содержит массив products с ценами для разных сервисных опций. Выбираем нужный productCode и отдаём totalPrice покупателю.

Создание отправления и печать ярлыка

Это центральная операция: при создании отправления DHL возвращает AWB-номер для трекинга и PDF/ZPL-файл ярлыка для печати.

В запросе POST /shipments обязательны:

• полные адреса отправителя и получателя с телефоном
• описание содержимого (packages[].description)
• таможенные данные для международных отправлений (content.exportDeclaration)

AWB-номер сохраняем в b_sale_order_props как свойство DHL_AWB. PDF ярлыка отдаём менеджеру через административный интерфейс Битрикс — добавляем кнопку «Распечатать ярлык DHL» в форму заказа.

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

Для международных отправлений DHL требует экспортную декларацию с перечнем товаров: exportLineItems с полями commodityCode (код HS), exportReasonType, manufacturerCountry. Данные берём из свойств товаров в b_iblock_element_prop или из пользовательских полей заказа.

Если магазин работает с B2B-клиентами и нужен инвойс, DHL API умеет генерировать Commercial Invoice — передаём content.exportDeclaration.invoice.

Трекинг отправлений

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

Ответ — массив shipments[0].events с историей перемещений. Интегрируем в личный кабинет покупателя на Битрикс: компонент sale.personal.order дополняем блоком с историей трекинга, подгружаемой через AJAX.

Заказ забора груза

POST /pickups

Можно автоматически создавать заявку на забор при накоплении заказов за день или отдавать менеджеру кнопку «Заказать забор DHL» в административной части.

Сроки