Elbuz підключається до DHL API за вашим договором DHL Paket у Німеччині й виписує накладні з картки замовлення. Посилка йде на адресу, у Packstation чи Postfiliale, статуси програма забирає сама кожні 10 хвилин.
Коли це знадобиться:
- Магазин у Німеччині відправляє DHL Paket — накладна з картки замовлення, без Geschäftskundenportal.
- Покупець просить Packstation чи Postfiliale — номер і Postnummer вписуються в одне поле.
- Оплата при отриманні — Nachnahme по Німеччині в євро з переказом на ваш IBAN.
- Посилки за кордон — DHL Paket International, Europaket чи Warenpost International за вашою Abrechnungsnummer.
З чого почати: отримайте ключ API на developer.dhl.com → впишіть доступи в Elbuz.
Що вміє DHL Paket в Elbuz
- Підключення — вхід Geschäftskundenportal, ключ API, Abrechnungsnummer і тестове середовище DHL.
- Накладна із замовлення — по Німеччині й за кордон, на адресу, у Packstation чи Postfiliale.
- Післяплата (Nachnahme) — сума із замовлення, переказ на ваш IBAN.
- Етикетка — PDF у будь-який момент за номером накладної.
- Статуси посилок — кожні 10 хвилин; за вашою таблицею кодів міняються статуси замовлень.
Як підключити DHL Paket API
Що взяти в DHL
| Що | Де взяти |
|---|---|
| Ключ API | На developer.dhl.com кнопка «Get Access» створює застосунок з Parcel DE Shipping і видає API Key та API Secret. Окремо підключати вхід OAuth2 (Authentication API) не треба — DHL відкриває його разом із Shipping. Для статусів додайте в той самий застосунок Shipment Tracking – Unified: заявку DHL перевіряє, зазвичай 2–5 робочих днів |
| Логін і пароль | Користувач Geschäftskundenportal. DHL радить окремого системного користувача (System user) з розділу «Benutzer verwalten»: увійти з ним в інтерфейс не можна, пароль діє 365 днів |
| Abrechnungsnummer | 14 символів: EKP (10 цифр) + процедура (2) + участь (2). Для DHL Paket по Німеччині процедура 01; за кордон — 53 (DHL Paket International), 54 (Europaket) чи 66 (Warenpost International). Процедури дає договір з DHL: потрібної немає — зверніться до свого менеджера DHL. Номери є в договорі й у порталі: «Versenden → Einstellungen → Nutzergruppen» |
Портал і API DHL безкоштовні. Бойовий доступ DHL відкриває вручну, після перевірки роботи в тестовому середовищі.
Що вписати в Elbuz
Де: Зовнішні сервіси та інтеграції → Доставка → «DHL Paket (Deutschland)».
| Поле | Що вписати |
|---|---|
| «Активність» | Увімкнено — інакше накладна DHL не відкриється |
| «Користувач», «Пароль» | Логін і пароль Geschäftskundenportal |
| «Токен» | API Key застосунку з developer.dhl.com |
| «API Secret застосунку (developer.dhl.com)» | API Secret того ж застосунку. З ним Elbuz входить у DHL через OAuth2. Порожньо — старий вхід логіном і паролем: поки працює, але DHL прибере його в наступній версії API |
| «Abrechnungsnummer: по Німеччині (14 символів)» | Номер з процедурою 01 |
| «Abrechnungsnummer: за кордон (14 символів)» | Номер з процедурою 53, 54 чи 66 — від неї залежить продукт; без номера накладні за кордон не створюються |
| «Профіль користувача (Gruppenprofil)» | Профіль групи користувача в порталі; за замовчуванням STANDARD_GRUPPENPROFIL |
| «IBAN для післяплати», «Власник рахунку для післяплати» | Рахунок, куди DHL переказує Nachnahme |
| «Тестове середовище (sandbox)» | Увімкніть для перевірки без договору (тестове середовище) |
| Блок «Відправник» | Компанія, контактна особа, країна кодом ISO (порожньо — DE), індекс, місто, вулиця, дім, телефон, e-mail |
1
Користувач і Пароль2
Токен3
API Secret застосунку4
Abrechnungsnummer5
IBAN і власник рахунку6
Тестове середовище7
Відправник- Користувач і Пароль — логін і пароль від Geschäftskundenportal.
- Токен — API Key застосунку з developer.dhl.com.
- API Secret застосунку — секрет того ж застосунку для входу OAuth2.
- Два поля Abrechnungsnummer — номер для відправок по Німеччині та за кордон.
- IBAN і власник рахунку — реквізити для післяплати.
- Тестове середовище (sandbox) — вмикає тестовий режим DHL.
- Відправник — дані магазину, які потраплять у накладну.
Форма зберігається сама, щойно ви змінили поле. «Пароль» і «Токен» після збереження показують крапки, а порожнє поле ключ не стирає. Під час збереження Elbuz доступи не перевіряє — помилку покаже перша накладна.
Тестове середовище DHL
Перевірити інтеграцію можна без договору. Увімкніть «Тестове середовище (sandbox)» і впишіть тестові дані з довідки DHL:
- «Користувач» —
user-valid, «Пароль» —SandboxPasswort2023!; - «Токен» — ваш API Key, «API Secret застосунку» — ваш API Secret;
- Abrechnungsnummer по Німеччині —
33333333330101, за кордон —33333333335301.
Накладні підуть у пісочницю DHL, справжньої відправки не буде. Перед роботою вимкніть перемикач і впишіть свої доступи.
Як виписати накладну DHL Paket із замовлення
Загальний порядок для всіх служб — у статті як виписати накладну із замовлення.
Де: картка замовлення зі способом доставки «DHL Paket (Deutschland)» → секція «Доставка» → «Створити накладну».
Що форма заповнить сама і що перевірити
| Поле | Звідки | Що перевірити |
|---|---|---|
| Прізвище, Ім'я, Телефон, E-Mail | Замовлення | Імʼя, місто й індекс обовʼязкові |
| Індекс, Населений пункт, Вулиця, Дім, Квартира | Адреса доставки замовлення: уся адреса — у «Вулиця», «Дім» і «Квартира» порожні | Вулиця — до 50 символів, дім із квартирою — до 10; довше Elbuz обріже |
| Країна (код ISO: DE, FR, IT, ES…) | Країна доставки замовлення | Не розпізнано — країна відправника |
| Код пункту видачі | Пункт із замовлення | Для Packstation — «номер станції/Postnummer», для Postfiliale — «Postfiliale номер/Postnummer» (Packstation і Postfiliale) |
| Загальна вага, кг | Вага товарів замовлення | Ваги немає й у товарах — піде 1 кг; DHL Paket — до 31,5 кг |
| Довжина, Ширина, Висота, см | Порожні | Передаються, лише якщо заповнено всі три |
| Зворотна доставка (одержувач) | «Гроші», якщо замовлення не оплачене й оплата при отриманні | Лише по Німеччині (Nachnahme) |
1
Код пункту видачі2
Країна (код ISO)3
Загальна вага, кг4
Зворотна доставка (одержувач)5
Створити накладну- Код пункту видачі — сюди вписують номер Packstation чи Postfiliale, якщо відправлення йде не на домашню адресу.
- Країна (код ISO) — двобуквений код країни одержувача, наприклад DE.
- Загальна вага, кг — вага відправлення, яку передають у DHL.
- Зворотна доставка — післяплата, лише по Німеччині; сума в євро.
- Кнопка створення накладної в DHL.
Який продукт DHL вибирає Elbuz
Відправник і одержувач у Німеччині — DHL Paket (V01PAK) з Abrechnungsnummer «по Німеччині». Інакше продукт задає процедура в номері «за кордон» (11-й і 12-й символи): DHL сам звіряє продукт із цими цифрами.
| Процедура | Продукт | Для чого |
|---|---|---|
| 53 | DHL Paket International (V53WPAK) | Посилки покупцям по всьому світу |
| 54 | DHL Europaket (V54EPAK) | Лише компаніям (B2B), здебільшого в країни ЄС |
| 66 | Warenpost International (V66WPI) | Малі відправлення через поштові мережі |
З іншою процедурою в номері «за кордон» накладна не створюється (розбір). Поза митним союзом ЄС (CH, GB, NO, UA) DHL вимагає митних даних, яких Elbuz не передає: такі накладні оформлюйте в Geschäftskundenportal.
Країни одержувача: AT, BE, BG, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK, UA. Для інших програма відповідає «DHL: unsupported country».
Розміри посилки за довідкою DHL — від 15×11×1 до 120×60×60 см.
Packstation і Postfiliale
У «Код пункту видачі» впишіть номер станції й Postnummer одержувача через скісну риску, наприклад 118/12345678. Номер станції — три цифри, Postnummer — 6–10 цифр із облікового запису DHL покупця. З кодом пункту вулиця не потрібна, але індекс і місто станції обовʼязкові.
Для Postfiliale впишіть Postfiliale 518/12345678: номер відділення — від 401 до 999. Postnummer можна не вказувати (Postfiliale 518), якщо в замовленні є e-mail покупця: DHL повідомить його про прибуття посилки.
Із замовлення магазину Elbuz CMS код приходить готовим. У старому замовленні зі збереженим лише номером допишіть код один раз.
Інший формат програма не відправить (розбір). Packstation і Postfiliale — лише в Німеччині.
Що відбувається після «Створити накладну»
- Elbuz перевіряє дані ще до DHL. Немає Abrechnungsnummer потрібного типу чи адреси відправника — повідомлення з причиною; накладна не створюється.
- DHL створює відправлення. Номер посилки лягає в «Сервіс доставки: номер», зʼявляється «Створено товарно-транспортну накладну №‹номер›».
- Номер замовлення йде в накладну як референс; коротший за 8 символів доповнюється нулями зліва, бо DHL приймає від 8.
- Якщо DHL відмовив, у вікні буде його текст — німецькою, з назвою поля, яке не сподобалося.
Накладна створюється одразу й оплачується за договором DHL. Скасувати її з Elbuz не можна — лише в DHL і лише до денного закриття (Tagesabschluss): за замовчуванням о 17:45 або в час, заданий у порталі. Після скасування очистіть «Сервіс доставки: номер» у замовленні, щоб виписати нову.
Післяплата DHL (Nachnahme)
У формі накладної виберіть «Зворотна доставка (одержувач)» → «Гроші» і перевірте суму. Неоплачене замовлення з оплатою при отриманні вже має «Гроші» і суму замовлення. DHL отримує суму в євро, призначення платежу — номер замовлення.
DHL приймає Nachnahme лише в євро. Замовлення з «Гроші» в іншій валюті Elbuz не відправить: «DHL приймає післяплату лише в євро (EUR), а валюта замовлення — UAH…». Змініть валюту замовлення на EUR або виберіть «Не потрібно».
- Лише по Німеччині: за кордон — «DHL: cash on delivery is available only inside Germany».
- Без IBAN і власника рахунку в підключенні — «DHL: IBAN and account holder for cash on delivery are required (API settings)».
За умовами DHL Nachnahme коштує 7,49 € без ПДВ понад ціну посилки, сума — до 3 500 €, гроші приходять зазвичай за 1–2 робочі дні.
Як надрукувати етикетку DHL
Де: картка замовлення → «Перегляд накладної» → значок друку; або «Відправлення» → рядок → «Друк накладної».
Етикетка — PDF у новій вкладці. Elbuz щоразу бере її в DHL за номером посилки, тож передрукувати можна будь-коли.
Курʼєра DHL з Elbuz не викликають: блоку «Виклик курʼєра» в накладній DHL немає.
Як Elbuz стежить за посилками DHL
Кожні 10 хвилин Elbuz питає DHL про посилки тим самим ключем API — до 100 накладних за прохід. Стежить за замовленнями за останні 60 днів і за замовленнями в позначених статусах, доки посилка не отримає стан «Отримано». Код і текст статусу DHL видно в замовленні й у «Відправленні»; кнопка «Відстеження на сайті служби» відкриває сторінку dhl.de з номером.
Стартовий ключ Shipment Tracking дає 250 запитів на добу й не частіше одного на 5 секунд. Коли ліміт вичерпано, Elbuz зупиняє прохід, а решту посилок перевіряє наступного разу — статуси оновлюються повільно. Відправляєте кілька посилок на день — натисніть «Request Upgrade» на сторінці API.
Як міняти статуси замовлень за кодами DHL
Кодів DHL програма сама не знає: поки таблиця порожня, посилка в «Відправленні» має стан «Невідомо», а статуси замовлень не міняються.
- У підключенні DHL, блок «Статуси замовлень, за якими перевіряти статус посилки в службі доставки», позначте статуси, у яких замовлення чекає доставки, наприклад «Відвантажено».
- У блоці «Налаштування повідомлень» відкрийте «Статуси доставки» (за потреби й «Статуси замовлення», «Статуси оплати»).
- Коди DHL з таблиці нижче вже вписані в колонку «Код (назва) на сайті (API)»; свої дописуйте через кому.
| Ваш статус доставки | Код DHL | Стан у «Відправленні» |
|---|---|---|
| Чекання від відправника | pre-transit | Створено |
| У дорозі | transit | В дорозі |
| Доставлено | delivered | Отримано, опитування припиняється |
Без коду delivered навпроти «Доставлено» у «Статуси доставки» посилка не отримає стан «Отримано», і Elbuz питатиме про неї й після вручення, займаючи місце в ліміті 100 накладних за прохід.
1
Код (назва) на сайті (API)2
Доставлено — delivered3
Порожній код- Колонка з кодами статусів, які повертає служба.
- Для статусу «Доставлено» вказано код delivered.
- «Відмова від отримання» без коду: серед кодів DHL окремої відмови немає.
Інших кодів у DHL два: failure — збій доставки — і unknown. Лишіть їх поза таблицею: така посилка матиме стан «Невідомо», і ви її помітите. Як працюють три таблиці статусів — у статті про автозміну статусу замовлення.
Сценарії
Перевірити до договору
Отримайте ключ на developer.dhl.com, впишіть тестові дані DHL і ввімкніть «Тестове середовище (sandbox)». Виписуйте накладну на своєму замовленні й надрукуйте етикетку. Договір підписано — впишіть свої доступи й вимкніть перемикач.
Покупець хоче в Packstation чи Postfiliale
У формі накладної впишіть «Код пункту видачі» на кшталт 118/12345678 чи Postfiliale 518/12345678, індекс і місто станції чи відділення. Вулицю можна лишити як є — DHL її не отримає.
Замовлення в Австрію
Перевірте «Країна» = AT у формі й наявність Abrechnungsnummer «за кордон». Продукт візьметься з цього номера, з процедурою 53 — DHL Paket International; «Зворотна доставка» — «Не потрібно».
Що робити, коли щось пішло не так
| Що ви бачите | Чому так | Що зробити |
|---|---|---|
| «Служба доставки не підключена: заповніть налаштування API цієї служби (Налаштування → Зовнішні сервіси API).» | Не вписано ні пароль, ні ключ, або вимкнено «Активність» | Заповніть доступи й увімкніть «Активність» (що вписати) |
| «DHL: portal login, password and API key are required (API settings)» | Одне з трьох полів — «Користувач», «Пароль», «Токен» — порожнє | Заповніть усі три |
| «DHL: billing number (14 characters) is required for domestic shipments (API settings)» (або international) | Порожня чи неповна Abrechnungsnummer потрібного типу | Впишіть 14 символів без пробілів (Abrechnungsnummer) |
| «DHL OAuth: Unauthorized API Authentication failed: Invalid client identifier» | API Key у «Токен» і API Secret не з одного застосунку або застосунок не має доступу до цього середовища | Скопіюйте обидва ключі з одного застосунку на developer.dhl.com; для бойового — перемикач sandbox вимкнено |
| «DHL: international billing number must be for procedure 53…» | У «за кордон» вписано номер іншого продукту, наприклад з процедурою 01 | Впишіть номер з процедурою 53, 54 чи 66 (продукт) |
| «DHL: pickup point code must be «station number/Postnummer»…» | У «Код пункту видачі» інший формат, наприклад лише номер станції без Postnummer | Впишіть 118/12345678 чи Postfiliale 518/12345678 (Packstation і Postfiliale) |
| «DHL: a Postfiliale needs the Postnummer…» | У коді Postfiliale немає Postnummer, а в замовленні — e-mail покупця | Допишіть Postnummer: Postfiliale 518/12345678, або вкажіть e-mail у замовленні |
| «DHL: cash on delivery is available only inside Germany» | «Гроші» в посилці за кордон | Виберіть «Не потрібно» |
| «DHL приймає післяплату лише в євро (EUR), а валюта замовлення — …» | Замовлення з «Гроші» не в євро | Змініть валюту замовлення на EUR або виберіть «Не потрібно» (Nachnahme) |
| «DHL: unsupported country» | Країна одержувача чи відправника не з переліку DHL у Elbuz | Перевірте код у «Країна» (перелік країн) |
| Статуси DHL оновлюються повільно | Ліміт стартового ключа Shipment Tracking | Попросіть у DHL підвищення ліміту (ліміт ключа) |
| У «Відправленні» посилка DHL зі станом «Невідомо» | Коду DHL немає у вікні «Статуси доставки» | Допишіть код (коди DHL) |
Часті запитання
Скільки коштує інтеграція DHL в Elbuz?
Elbuz за накладні, етикетки й статуси DHL нічого не списує, API DHL безкоштовний. Посилки й Nachnahme ви оплачуєте DHL за договором.
Чи можна підключити DHL без договору DHL Paket?
Лише тестове середовище: ключ API й тестовий користувач DHL. Для справжніх накладних потрібні договір, вхід Geschäftskundenportal і Abrechnungsnummer (тестове середовище).
Чи обовʼязковий API Secret?
Ні, без нього Elbuz входить у DHL логіном і паролем, як раніше. Але DHL прибере цей вхід у наступній версії API, тож впишіть API Secret заздалегідь — окремої заявки в DHL не треба (що вписати).
Чи можна відправити післяплату в гривнях чи злотих?
Ні, DHL приймає Nachnahme лише в євро. Замовлення має бути в EUR (Nachnahme).
Чи можна викликати курʼєра DHL з Elbuz?
Ні, виклик курʼєра для DHL Paket не підключено. Замовте забір у DHL.
Як скасувати накладну DHL?
Лише в DHL, до денного закриття (Tagesabschluss). Потім очистіть «Сервіс доставки: номер» у замовленні (після створення).
Чи можна відправити DHL у відділення пошти (Postfiliale)?
Так, у «Код пункту видачі» — Postfiliale 518/12345678. Без Postnummer потрібен e-mail покупця в замовленні (Packstation і Postfiliale).
Чим DHL Paket відрізняється від DHL у Польщі?
Це різні служби з різними кабінетами: DHL Paket — для договорів з DHL у Німеччині, DHL Parcel Polska — окремий запис «DHL Parcel (Польща, DHL24)».
Де це і хто має доступ
- Меню
- Кабінет → Налаштування системи → Інші налаштування → Зовнішні сервіси та інтеграції → Доставка → DHL Paket (Deutschland)
- Інші входи
- Довідники → Документи → Відправлення → «Служби доставки»; картка замовлення → секція «Доставка»
- Право доступу
- підключення — «API та токени доступу»; накладна — вікно «Створення ТТН служби доставки»
- Підготувати
- договір DHL Paket, користувач Geschäftskundenportal, ключ API з developer.dhl.com
- Отримати ключ APIdeveloper.dhl.com
- Вписати доступи, Abrechnungsnummer і відправникаЗовнішні сервіси та інтеграції → DHL Paket
- Вписати коди статусів DHLТам само, «Налаштування повідомлень»
- Виписати накладну й надрукувати етикеткуКартка замовлення, секція «Доставка»
Суміжні теми
- Якщо потрібно бачити всі посилки всіх служб в одному списку — Відправлення.
- Якщо відправляєте ще й UPS чи FedEx — UPS в Elbuz, FedEx в Elbuz.
- Якщо хочете порівняти способи виписати накладну — накладна із замовлення.
