Інтеграція 1С-Бітрікс зі службою доставки DHL

Інтеграція 1С-Bitrix зі службою доставки DHL

DHL — міжнародний експресс-перевізник з покриттям більше 220 країн. Для інтернет-магазинів актуальні два продукти: DHL Express (терміна міжнародна доставка) та DHL Parcel (регіональна посилкова доставка в Європі). API у них різні — важливо відразу визначитися, з яким саме працюємо.

API DHL: що та де

DHL Express MyDHL+ API — для міжнародних відправлень. Базовий URL: https://express.api.dhl.com/mydhlapi. Авторизація: Basic Auth (ім'я користувача + пароль від облікового запису 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

Клас доставки успадковує \Bitrix\Sale\Delivery\Services\Base. Налаштування в b_sale_delivery_service_params:

• DHL_USERNAME, DHL_PASSWORD — дані для входу від 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 ярлика передаємо менеджеру через адміністративний інтерфейс Bitrix — додаємо кнопку «Надрукувати ярлик DHL» у форму замовлення.

Таможенні декларації

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

Якщо магазин працює з B2B-клієнтами і потребує рахунку, API DHL вміє генерувати Commercial Invoice — передаємо content.exportDeclaration.invoice.

Відстеження відправлень

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

Відповідь — масив shipments[0].events з історією переміщень. Інтегруємо в особистий кабінет покупця на Bitrix: доповнюємо компонент sale.personal.order блоком з історією відстеження, що завантажується через AJAX.

Замовити вивіз вантажу

POST /pickups

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

Строки