↑↓ вибірEnter відкритиEsc закрити

    1. Elbuz
    2. Керівництво користувача Elbuz
    3. Продажі та документи
    4. Обробка замовлень покупця
    5. Служби доставки в Elbuz

    DHL API в Elbuz: накладна DHL Paket, Packstation, післяплата і статуси

    10 хв читанняОновлено

    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

    Як підключити 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 днів
    Abrechnungsnummer14 символів: 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
    Форма підключення DHL Paket (Deutschland): ключі, Abrechnungsnummer, IBAN, sandbox і блок «Відправник»
    1Користувач і Пароль
    2Токен
    3API Secret застосунку
    4Abrechnungsnummer
    5IBAN і власник рахунку
    6Тестове середовище
    7Відправник
    1. Користувач і Пароль — логін і пароль від Geschäftskundenportal.
    2. Токен — API Key застосунку з developer.dhl.com.
    3. API Secret застосунку — секрет того ж застосунку для входу OAuth2.
    4. Два поля Abrechnungsnummer — номер для відправок по Німеччині та за кордон.
    5. IBAN і власник рахунку — реквізити для післяплати.
    6. Тестове середовище (sandbox) — вмикає тестовий режим DHL.
    7. Відправник — дані магазину, які потраплять у накладну.

    Форма зберігається сама, щойно ви змінили поле. «Пароль» і «Токен» після збереження показують крапки, а порожнє поле ключ не стирає. Під час збереження 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)
    Форма накладної DHL Paket: одержувач, адреса з кодом пункту видачі, вага й сума післяплати в євро
    1Код пункту видачі
    2Країна (код ISO)
    3Загальна вага, кг
    4Зворотна доставка (одержувач)
    5Створити накладну
    1. Код пункту видачі — сюди вписують номер Packstation чи Postfiliale, якщо відправлення йде не на домашню адресу.
    2. Країна (код ISO) — двобуквений код країни одержувача, наприклад DE.
    3. Загальна вага, кг — вага відправлення, яку передають у DHL.
    4. Зворотна доставка — післяплата, лише по Німеччині; сума в євро.
    5. Кнопка створення накладної в DHL.

    Який продукт DHL вибирає Elbuz

    Відправник і одержувач у Німеччині — DHL Paket (V01PAK) з Abrechnungsnummer «по Німеччині». Інакше продукт задає процедура в номері «за кордон» (11-й і 12-й символи): DHL сам звіряє продукт із цими цифрами.

    ПроцедураПродуктДля чого
    53DHL Paket International (V53WPAK)Посилки покупцям по всьому світу
    54DHL Europaket (V54EPAK)Лише компаніям (B2B), здебільшого в країни ЄС
    66Warenpost 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 — лише в Німеччині.

    Що відбувається після «Створити накладну»

    1. Elbuz перевіряє дані ще до DHL. Немає Abrechnungsnummer потрібного типу чи адреси відправника — повідомлення з причиною; накладна не створюється.
    2. DHL створює відправлення. Номер посилки лягає в «Сервіс доставки: номер», зʼявляється «Створено товарно-транспортну накладну №‹номер›».
    3. Номер замовлення йде в накладну як референс; коротший за 8 символів доповнюється нулями зліва, бо DHL приймає від 8.
    4. Якщо 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 програма сама не знає: поки таблиця порожня, посилка в «Відправленні» має стан «Невідомо», а статуси замовлень не міняються.

    1. У підключенні DHL, блок «Статуси замовлень, за якими перевіряти статус посилки в службі доставки», позначте статуси, у яких замовлення чекає доставки, наприклад «Відвантажено».
    2. У блоці «Налаштування повідомлень» відкрийте «Статуси доставки» (за потреби й «Статуси замовлення», «Статуси оплати»).
    3. Коди DHL з таблиці нижче вже вписані в колонку «Код (назва) на сайті (API)»; свої дописуйте через кому.
    Коди DHL для вікна «Статуси доставки»
    Ваш статус доставкиКод DHLСтан у «Відправленні»
    Чекання від відправникаpre-transitСтворено
    У дорозіtransitВ дорозі
    ДоставленоdeliveredОтримано, опитування припиняється

    Без коду delivered навпроти «Доставлено» у «Статуси доставки» посилка не отримає стан «Отримано», і Elbuz питатиме про неї й після вручення, займаючи місце в ліміті 100 накладних за прохід.

    Вікно «Статуси доставки» для DHL Paket з колонкою кодів статусів на сайті
    1Код (назва) на сайті (API)
    2Доставлено — delivered
    3Порожній код
    1. Колонка з кодами статусів, які повертає служба.
    2. Для статусу «Доставлено» вказано код delivered.
    3. «Відмова від отримання» без коду: серед кодів 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
    1. Отримати ключ APIdeveloper.dhl.com
    2. Вписати доступи, Abrechnungsnummer і відправникаЗовнішні сервіси та інтеграції → DHL Paket
    3. Вписати коди статусів DHLТам само, «Налаштування повідомлень»
    4. Виписати накладну й надрукувати етикеткуКартка замовлення, секція «Доставка»

    Суміжні теми

    Чи була стаття корисною?

    Не вистачає функції? Напишіть нам.

    Ми додамо її безкоштовно, якщо вона знадобиться й іншим.

    Якщо це потрібно тільки вам — домовимося окремо.

    Зміст статті

    Запропонувати доробку

    Спробувати безкоштовно