Інтеграція логістичних сервісів DHL в мобільний додаток
DHL надає розвинену екосистему API через портал developer.dhl.com. На відміну від багатьох логістичних операторів, документація якісна, sandbox-окремення доступне одразу після реєстрації, а API дотримуються REST-конвенцій. Це не означає, що інтеграція тривіальна — у DHL своя специфіка.
Набір API DHL
DHL Group об'єднує кілька підрозділів, у кожного свій API:
| Підрозділ | API | Призначення |
|---|---|---|
| DHL Express | Express API | Міжнародна експрес-доставка, створення відправлень, етикетки |
| DHL Parcel | Parcel DE/NL/BE API | Внутрішньорегіональна доставка в Європі |
| DHL eCommerce | Global Forwarding API | Трансграничная e-commerce доставка |
| DHL Supply Chain | — | Складські операції (корпоративний сегмент) |
Для більшості e-commerce мобільних додатків потрібен DHL Express API (міжнародні відправлення) або DHL Parcel (доставка по Німеччині/Європі). Це різні базові URL, різні формати запитів, різні токени авторизації.
Авторизація
DHL Express API використовує Basic Auth з обліковими даними DHL аккаунта. У продакшені потрібен реальний аккаунт DHL Express з активованим API-доступом — sandbox та production використовують різні облікові дані.
DHL Parcel (новий API) працює через OAuth 2.0 Client Credentials Flow. Отримуємо access_token через POST /oauth/token та використовуємо в кожному запиті. Токен живе 3600 секунд — кешуємо та оновлюємо автоматично.
Розрахунок тарифів
Endpoint для розрахунку вартості DHL Express:
GET /rates?accountNumber={account}&originCountryCode=RU
&originCityName=Moscow&destinationCountryCode=DE
&destinationCityName=Berlin&weight=2.5&length=30
&width=20&height=15&plannedShippingDateAndTime=2024-01-15T09:00:00
Повертає список продуктів (EXPRESS WORLDWIDE, EXPRESS 12:00 та ін.) з цінами та термінами доставки. В мобільному додатку показуємо користувачеві порівняння варіантів у вигляді списку — не ховаємо за радіокнопки.
Критичний момент: вага та габарити. DHL розраховує об'ємну вагу: (довжина × ширина × висота) / 5000. Бере максимум із фактичної та об'ємної ваги. Додаток повинен пояснити користувачеві, чому підсумкова вага більша за введену.
Створення відправлення та етикетка
POST /shipments створює відправлення та повертає трек-номер та URL етикетки у форматі PDF або ZPL (для термопринтерів). Генерація етикетки в додатку на iOS використовуємо WKWebView для рендеринку PDF або UIPrintInteractionController для прямого друку. На Android — PdfRenderer або інтент на друк через PrintManager.
Трекінг у реальному часі
DHL Shipment Tracking API (GET /tracking/shipments?trackingNumber=...) повертає повну історію подій з кодами та описами. Частота оновлення: раз на 30 хвилин достатньо для більшості сценаріїв. Обмеження API у sandbox — 250 запитів на день.
Для push-уведомлень про статус: DHL Tracking Webhook (доступний для enterprise-аккаунтів) відправляє подіï в реальному часі на ваш webhook URL. Альтернатива — polling через WorkManager / BGAppRefreshTask.
Терміни: інтеграція трекінгу та розрахунку тарифів — 1-2 тижні. Повний цикл створення відправлень з етикетками та вебхуками — 3-4 тижні.