Elbuz łączy się z DHL API na Twojej umowie DHL Paket w Niemczech i wystawia listy przewozowe z karty zamówienia. Paczka idzie na adres, do Packstation lub Postfiliale, a statusy program pobiera sam co 10 minut.
Kiedy to się przyda:
- Sklep w Niemczech wysyła DHL Paket — list przewozowy z karty zamówienia, bez Geschäftskundenportal.
- Klient prosi o Packstation lub Postfiliale — numer i Postnummer wpisujesz w jedno pole.
- Płatność przy odbiorze — Nachnahme na terenie Niemiec w euro z przelewem na Twój IBAN.
- Paczki za granicę — DHL Paket International, Europaket lub Warenpost International na Twój Abrechnungsnummer.
Od czego zacząć: uzyskaj klucz API na developer.dhl.com → wpisz dane dostępowe w Elbuz.
Co potrafi DHL Paket w Elbuz
- Podłączenie — logowanie do Geschäftskundenportal, klucz API, Abrechnungsnummer i środowisko testowe DHL.
- List przewozowy z zamówienia — w Niemczech i za granicę, na adres, do Packstation lub Postfiliale.
- Pobranie (Nachnahme) — kwota z zamówienia, przelew na Twój IBAN.
- Etykieta — PDF w dowolnym momencie według numeru listu przewozowego.
- Statusy paczek — co 10 minut; według Twojej tabeli kodów zmieniają się statusy zamówień.
Jak podłączyć DHL Paket API
Co uzyskać w DHL
| Co | Skąd wziąć |
|---|---|
| Klucz API | Na developer.dhl.com przycisk „Get Access” tworzy aplikację z Parcel DE Shipping i wydaje API Key oraz API Secret. Logowania OAuth2 (Authentication API) nie trzeba podłączać osobno — DHL udostępnia je razem z Shipping. Do statusów dodaj w tej samej aplikacji Shipment Tracking – Unified: wniosek DHL weryfikuje, zwykle 2–5 dni roboczych |
| Login i hasło | Użytkownik Geschäftskundenportal. DHL zaleca osobnego użytkownika systemowego (System user) z sekcji „Benutzer verwalten”: nie można się nim zalogować do interfejsu, hasło jest ważne 365 dni |
| Abrechnungsnummer | 14 znaków: EKP (10 cyfr) + procedura (2) + udział (2). Dla DHL Paket w Niemczech procedura 01; za granicę — 53 (DHL Paket International), 54 (Europaket) lub 66 (Warenpost International). Procedury wynikają z umowy z DHL: jeśli brakuje potrzebnej, zwróć się do swojego opiekuna DHL. Numery są w umowie i w portalu: „Versenden → Einstellungen → Nutzergruppen” |
Portal i API DHL są bezpłatne. Dostęp produkcyjny DHL otwiera ręcznie, po sprawdzeniu działania w środowisku testowym.
Co wpisać w Elbuz
Gdzie: Usługi zewnętrzne i integracje → Dostawa → „DHL Paket (Deutschland)”.
| Pole | Co wpisać |
|---|---|
| „Aktywność” | Włączone — inaczej list przewozowy DHL się nie otworzy |
| „Użytkownik”, „Hasło” | Login i hasło Geschäftskundenportal |
| „Token” | API Key aplikacji z developer.dhl.com |
| „API Secret aplikacji (developer.dhl.com)” | API Secret tej samej aplikacji. Z nim Elbuz loguje się do DHL przez OAuth2. Puste — stare logowanie loginem i hasłem: na razie działa, ale DHL usunie je w następnej wersji API |
| „Abrechnungsnummer: w Niemczech (14 znaków)” | Numer z procedurą 01 |
| „Abrechnungsnummer: zagranica (14 znaków)” | Numer z procedurą 53, 54 lub 66 — od niej zależy produkt; bez numeru listy przewozowe za granicę się nie tworzą |
| „Profil użytkownika (Gruppenprofil)” | Profil grupy użytkownika w portalu; domyślnie STANDARD_GRUPPENPROFIL |
| „IBAN dla pobrania”, „Właściciel konta dla pobrania” | Rachunek, na który DHL przelewa Nachnahme |
| „Środowisko testowe (sandbox)” | Włącz, żeby sprawdzić bez umowy (środowisko testowe) |
| Blok „Nadawca” | Firma, osoba kontaktowa, kraj kodem ISO (puste — DE), kod pocztowy, miejscowość, ulica, nr domu, telefon, e-mail |
1
Użytkownik i Hasło2
Token3
API Secret aplikacji4
Numery Abrechnungsnummer5
IBAN i właściciel konta6
Środowisko testowe7
Blok nadawcy- Użytkownik i Hasło — Twoje logowanie do Geschäftskundenportal.
- Token — API Key z developer.dhl.com.
- API Secret aplikacji — sekret tej samej aplikacji z developer.dhl.com.
- Numery Abrechnungsnummer — 14-znakowe numery dla przesyłek krajowych i zagranicznych.
- IBAN i właściciel konta — dane rachunku do pobrań.
- Środowisko testowe — przełącza zapytania do środowiska testowego DHL.
- Blok nadawcy — firma i adres, z którego wysyłane są paczki.
Formularz zapisuje się sam, gdy tylko zmienisz pole. „Hasło” i „Token” po zapisaniu wyświetlają kropki, a puste pole nie kasuje klucza. Przy zapisie Elbuz nie sprawdza danych dostępowych — błąd pokaże pierwszy list przewozowy.
Środowisko testowe DHL
Integrację można sprawdzić bez umowy. Włącz „Środowisko testowe (sandbox)” i wpisz dane testowe z dokumentacji DHL:
- „Użytkownik” —
user-valid, „Hasło” —SandboxPasswort2023!; - „Token” — Twój API Key, „API Secret aplikacji” — Twój API Secret;
- Abrechnungsnummer w Niemczech —
33333333330101, za granicę —33333333335301.
Listy przewozowe trafią do piaskownicy DHL, prawdziwej wysyłki nie będzie. Przed rozpoczęciem pracy wyłącz przełącznik i wpisz własne dane dostępowe.
Jak wystawić list przewozowy DHL Paket z zamówienia
Ogólna kolejność dla wszystkich przewoźników — w artykule jak wystawić list przewozowy z zamówienia.
Gdzie: karta zamówienia ze sposobem dostawy „DHL Paket (Deutschland)” → sekcja „Dostawa” → „Utwórz list przewozowy”.
Co formularz wypełni sam i co sprawdzić
| Pole | Skąd | Co sprawdzić |
|---|---|---|
| Nazwisko, Imię, Telefon, E-mail | Zamówienie | Imię, miejscowość i kod pocztowy są wymagane |
| Kod pocztowy, Miejscowość, Ulica, Nr domu, Nr mieszkania | Adres dostawy zamówienia: cały adres — w „Ulica”, „Nr domu” i „Nr mieszkania” puste | Ulica — do 50 znaków, nr domu z mieszkaniem — do 10; dłuższe Elbuz przytnie |
| Kraj (kod ISO: DE, FR, IT, ES…) | Kraj dostawy zamówienia | Nierozpoznany — kraj nadawcy |
| Kod punktu odbioru | Punkt z zamówienia | Dla Packstation — „numer stacji/Postnummer”, dla Postfiliale — „Postfiliale numer/Postnummer” (Packstation i Postfiliale) |
| Waga całkowita, kg | Waga produktów zamówienia | Jeśli wagi nie ma też w produktach — trafi 1 kg; DHL Paket — do 31,5 kg |
| Długość, Szerokość, Wysokość, cm | Puste | Przekazywane tylko wtedy, gdy wypełnione są wszystkie trzy |
| Dostawa zwrotna (odbiorca) | „Pieniądze”, jeśli zamówienie nie jest opłacone, a płatność jest przy odbiorze | Tylko w Niemczech (Nachnahme) |
1
Kod punktu odbioru2
Kraj3
Waga całkowita4
Dostawa zwrotna5
Utwórz list przewozowy- Kod punktu odbioru — kod Packstation lub punktu odbioru; przy dostawie do domu puste.
- Kraj — dwuliterowy kod ISO kraju docelowego.
- Waga całkowita — waga paczki w kilogramach.
- Dostawa zwrotna — opcja zwrotu po stronie odbiorcy.
- Utwórz list przewozowy — wysyła zapytanie do DHL.
Jaki produkt DHL wybiera Elbuz
Nadawca i odbiorca w Niemczech — DHL Paket (V01PAK) z Abrechnungsnummer „w Niemczech”. W przeciwnym razie produkt wyznacza procedura w numerze „zagranica” (11. i 12. znak): DHL sam porównuje produkt z tymi cyframi.
| Procedura | Produkt | Do czego |
|---|---|---|
| 53 | DHL Paket International (V53WPAK) | Paczki do klientów na całym świecie |
| 54 | DHL Europaket (V54EPAK) | Tylko do firm (B2B), głównie do krajów UE |
| 66 | Warenpost International (V66WPI) | Małe przesyłki przez sieci pocztowe |
Z inną procedurą w numerze „zagranica” list przewozowy się nie tworzy (rozwiązywanie problemów). Poza unią celną UE (CH, GB, NO, UA) DHL wymaga danych celnych, których Elbuz nie przekazuje: takie listy przewozowe wystawiaj w Geschäftskundenportal.
Kraje odbiorcy: 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. Dla pozostałych program odpowiada „DHL: unsupported country”.
Wymiary paczki według dokumentacji DHL — od 15×11×1 do 120×60×60 cm.
Packstation i Postfiliale
W „Kod punktu odbioru” wpisz numer stacji i Postnummer odbiorcy przez ukośnik, np. 118/12345678. Numer stacji to trzy cyfry, Postnummer — 6–10 cyfr z konta DHL klienta. Z kodem punktu ulica nie jest potrzebna, ale kod pocztowy i miejscowość stacji są wymagane.
Dla Postfiliale wpisz Postfiliale 518/12345678: numer placówki — od 401 do 999. Postnummer można pominąć (Postfiliale 518), jeśli w zamówieniu jest e-mail klienta: DHL powiadomi go o dotarciu paczki.
Z zamówienia ze sklepu Elbuz CMS kod przychodzi gotowy. W starym zamówieniu, w którym zapisano tylko numer, dopisz kod raz.
Innego formatu program nie wyśle (rozwiązywanie problemów). Packstation i Postfiliale działają tylko w Niemczech.
Co się dzieje po kliknięciu „Utwórz list przewozowy”
- Elbuz sprawdza dane jeszcze przed wysłaniem do DHL. Brak Abrechnungsnummer potrzebnego typu lub adresu nadawcy — komunikat z przyczyną; list przewozowy się nie tworzy.
- DHL tworzy przesyłkę. Numer paczki trafia do „Numer listu przewozowego”, pojawia się „Utworzono list przewozowy nr ‹numer›”.
- Numer zamówienia trafia do listu przewozowego jako referencja; krótszy niż 8 znaków jest uzupełniany zerami z lewej, bo DHL przyjmuje od 8.
- Jeśli DHL odmówił, w oknie pojawi się jego komunikat — po niemiecku, z nazwą pola, które nie przeszło weryfikacji.
List przewozowy tworzy się od razu i jest płatny według umowy z DHL. Nie anulujesz go z Elbuz — tylko w DHL i tylko do dziennego zamknięcia (Tagesabschluss): domyślnie o 17:45 lub o godzinie ustawionej w portalu. Po anulowaniu wyczyść „Numer listu przewozowego” w zamówieniu, żeby wystawić nowy.
Pobranie DHL (Nachnahme)
W formularzu listu przewozowego wybierz „Dostawa zwrotna (odbiorca)” → „Pieniądze” i sprawdź kwotę. Nieopłacone zamówienie z płatnością przy odbiorze ma już „Pieniądze” i kwotę zamówienia. DHL dostaje kwotę w euro, tytuł płatności — numer zamówienia.
DHL przyjmuje Nachnahme tylko w euro. Zamówienia z „Pieniądze” w innej walucie Elbuz nie wyśle: „DHL przyjmuje pobranie tylko w euro (EUR), a waluta zamówienia to PLN…”. Zmień walutę zamówienia na EUR albo wybierz „Niepotrzebna”.
- Tylko w Niemczech: za granicę — „DHL: cash on delivery is available only inside Germany”.
- Bez IBAN-u i właściciela konta w podłączeniu — „DHL: IBAN and account holder for cash on delivery are required (API settings)”.
Według warunków DHL Nachnahme kosztuje 7,49 EUR netto ponad cenę paczki, kwota — do 3 500 EUR, pieniądze przychodzą zwykle w 1–2 dni robocze.
Jak wydrukować etykietę DHL
Gdzie: karta zamówienia → „Podgląd listu przewozowego” → ikona drukowania; albo „Przesyłki” → wiersz → „Drukuj list przewozowy”.
Etykieta to PDF w nowej karcie. Elbuz za każdym razem pobiera ją z DHL według numeru paczki, więc możesz ją wydrukować ponownie w dowolnym momencie.
Kuriera DHL z Elbuz się nie zamawia: w liście przewozowym DHL nie ma bloku „Zamówienie kuriera”.
Jak Elbuz śledzi paczki DHL
Co 10 minut Elbuz pyta DHL o paczki tym samym kluczem API — do 100 listów przewozowych na przebieg. Śledzi zamówienia z ostatnich 60 dni i zamówienia w oznaczonych statusach, dopóki paczka nie dostanie stanu „Doręczona”. Kod i tekst statusu DHL widać w zamówieniu i w „Przesyłkach”; przycisk „Śledź na stronie przewoźnika” otwiera stronę dhl.de z numerem.
Startowy klucz Shipment Tracking daje 250 zapytań na dobę i nie częściej niż jedno na 5 sekund. Gdy limit się wyczerpie, Elbuz przerywa przebieg, a pozostałe paczki sprawdza następnym razem — statusy aktualizują się wolno. Jeśli wysyłasz kilka paczek dziennie, kliknij „Request Upgrade” na stronie API.
Jak zmieniać statusy zamówień według kodów DHL
Kodów DHL program sam nie zna: dopóki tabela jest pusta, paczka w „Przesyłkach” ma stan „Nieznany”, a statusy zamówień się nie zmieniają.
- W podłączeniu DHL, w bloku „Statusy zamówień, dla których sprawdzać status przesyłki w firmie kurierskiej”, oznacz statusy, w których zamówienie czeka na doręczenie, np. „Wysłano”.
- W bloku „Ustawienia powiadomień” otwórz „Statusy dostawy” (w razie potrzeby także „Statusy zamówienia”, „Statusy płatności”).
- Kody DHL z tabeli poniżej są już wpisane w kolumnie „Kod (nazwa) na stronie (API)”; własne dopisuj po przecinku.
| Twój status dostawy | Kod DHL | Stan w „Przesyłkach” |
|---|---|---|
| Oczekiwanie od nadawcy | pre-transit | Utworzona |
| W drodze | transit | W drodze |
| Dostarczono | delivered | Doręczona, odpytywanie się kończy |
Bez kodu delivered przy „Dostarczono” w „Statusy dostawy” paczka nie dostanie stanu „Doręczona”, a Elbuz będzie o nią pytać także po doręczeniu, zajmując miejsce w limicie 100 listów przewozowych na przebieg.
1
Kolumna kodu2
Dostarczono3
Pusty kod- Kod (nazwa) na stronie (API) — kod statusu zwracany przez DHL.
- Dostarczono — przypisany do kodu delivered.
- Odrzucenie — puste, bo DHL nie zgłasza tego statusu osobno.
Innych kodów DHL ma dwa: failure — nieudane doręczenie — i unknown. Zostaw je poza tabelą: taka paczka będzie miała stan „Nieznany” i ją zauważysz. Jak działają trzy tabele statusów — w artykule o automatycznej zmianie statusu zamówienia.
Scenariusze
Sprawdzić przed podpisaniem umowy
Uzyskaj klucz na developer.dhl.com, wpisz dane testowe DHL i włącz „Środowisko testowe (sandbox)”. Wystaw list przewozowy dla własnego zamówienia i wydrukuj etykietę. Gdy umowa jest podpisana, wpisz własne dane dostępowe i wyłącz przełącznik.
Klient chce odebrać w Packstation lub Postfiliale
W formularzu listu przewozowego wpisz „Kod punktu odbioru” w rodzaju 118/12345678 lub Postfiliale 518/12345678 oraz kod pocztowy i miejscowość stacji lub placówki. Ulicę możesz zostawić bez zmian — DHL jej nie dostanie.
Zamówienie do Austrii
Sprawdź, czy w formularzu „Kraj” = AT i czy jest Abrechnungsnummer „zagranica”. Produkt wynika z tego numeru, przy procedurze 53 — DHL Paket International; „Dostawa zwrotna” — „Niepotrzebna”.
Co zrobić, gdy coś pójdzie nie tak
| Co widzisz | Dlaczego tak jest | Co zrobić |
|---|---|---|
| „Firma kurierska nie jest podłączona: uzupełnij ustawienia API tej firmy (Ustawienia systemu → Inne ustawienia → Usługi zewnętrzne i integracje).” | Nie wpisano ani hasła, ani klucza albo „Aktywność” jest wyłączona | Wypełnij dane dostępowe i włącz „Aktywność” (co wpisać) |
| „DHL: portal login, password and API key are required (API settings)” | Jedno z trzech pól — „Użytkownik”, „Hasło”, „Token” — jest puste | Wypełnij wszystkie trzy |
| „DHL: billing number (14 characters) is required for domestic shipments (API settings)” (lub international) | Pusty lub niepełny Abrechnungsnummer potrzebnego typu | Wpisz 14 znaków bez spacji (Abrechnungsnummer) |
| „DHL OAuth: Unauthorized API Authentication failed: Invalid client identifier” | API Key w „Token” i API Secret nie pochodzą z jednej aplikacji albo aplikacja nie ma dostępu do tego środowiska | Skopiuj oba klucze z jednej aplikacji na developer.dhl.com; dla środowiska produkcyjnego przełącznik sandbox musi być wyłączony |
| „DHL: international billing number must be for procedure 53…” | W „zagranica” wpisano numer innego produktu, np. z procedurą 01 | Wpisz numer z procedurą 53, 54 lub 66 (produkt) |
| „DHL: pickup point code must be «station number/Postnummer»…” | W „Kod punktu odbioru” jest inny format, np. sam numer stacji bez Postnummer | Wpisz 118/12345678 lub Postfiliale 518/12345678 (Packstation i Postfiliale) |
| „DHL: a Postfiliale needs the Postnummer…” | W kodzie Postfiliale nie ma Postnummer, a w zamówieniu — e-maila klienta | Dopisz Postnummer: Postfiliale 518/12345678 albo podaj e-mail w zamówieniu |
| „DHL: cash on delivery is available only inside Germany” | „Pieniądze” w paczce za granicę | Wybierz „Niepotrzebna” |
| „DHL przyjmuje pobranie tylko w euro (EUR), a waluta zamówienia to …” | Zamówienie z „Pieniądze” nie jest w euro | Zmień walutę zamówienia na EUR albo wybierz „Niepotrzebna” (Nachnahme) |
| „DHL: unsupported country” | Kraj odbiorcy lub nadawcy spoza listy DHL w Elbuz | Sprawdź kod w „Kraj” (lista krajów) |
| Statusy DHL aktualizują się wolno | Limit startowego klucza Shipment Tracking | Poproś DHL o podniesienie limitu (limit klucza) |
| W „Przesyłkach” paczka DHL ze stanem „Nieznany” | Kodu DHL nie ma w oknie „Statusy dostawy” | Dopisz kod (kody DHL) |
Najczęstsze pytania
Ile kosztuje integracja DHL w Elbuz?
Elbuz nic nie pobiera za listy przewozowe, etykiety i statusy DHL, API DHL jest bezpłatne. Za paczki i Nachnahme płacisz DHL według umowy.
Czy mogę podłączyć DHL bez umowy DHL Paket?
Tylko środowisko testowe: klucz API i testowy użytkownik DHL. Do prawdziwych listów przewozowych potrzebne są umowa, logowanie do Geschäftskundenportal i Abrechnungsnummer (środowisko testowe).
Czy API Secret jest obowiązkowy?
Nie, bez niego Elbuz loguje się do DHL loginem i hasłem, jak dotąd. DHL usunie jednak to logowanie w następnej wersji API, więc wpisz API Secret zawczasu — osobny wniosek do DHL nie jest potrzebny (co wpisać).
Czy mogę wysłać pobranie w złotych lub hrywnach?
Nie, DHL przyjmuje Nachnahme tylko w euro. Zamówienie musi być w EUR (Nachnahme).
Czy mogę zamówić kuriera DHL z Elbuz?
Nie, zamawianie kuriera dla DHL Paket nie jest podłączone. Zamów odbiór w DHL.
Jak anulować list przewozowy DHL?
Tylko w DHL, do dziennego zamknięcia (Tagesabschluss). Potem wyczyść „Numer listu przewozowego” w zamówieniu (po utworzeniu).
Czy mogę wysłać DHL do placówki pocztowej (Postfiliale)?
Tak, w „Kod punktu odbioru” — Postfiliale 518/12345678. Bez Postnummer potrzebny jest e-mail klienta w zamówieniu (Packstation i Postfiliale).
Czym DHL Paket różni się od DHL w Polsce?
To różni przewoźnicy z różnymi panelami: DHL Paket — dla umów z DHL w Niemczech, DHL Parcel Polska — osobny wpis „DHL Parcel (Polska, DHL24)”.
Gdzie to jest i kto ma dostęp
- Menu
- Panel klienta → Ustawienia systemu → Inne ustawienia → Usługi zewnętrzne i integracje → Dostawa → DHL Paket (Deutschland)
- Inne wejścia
- Słowniki → Dokumenty → Przesyłki → „Przewoźnicy”; karta zamówienia → sekcja „Dostawa”
- Uprawnienia
- podłączenie — „API i tokeny dostępu”; list przewozowy — okno „Tworzenie listu przewozowego”
- Przygotować
- umowę DHL Paket, użytkownika Geschäftskundenportal, klucz API z developer.dhl.com
- Uzyskaj klucz APIdeveloper.dhl.com
- Wpisz dane dostępowe, Abrechnungsnummer i nadawcęUsługi zewnętrzne i integracje → DHL Paket
- Wpisz kody statusów DHLTamże, „Ustawienia powiadomień”
- Wystaw list przewozowy i wydrukuj etykietęKarta zamówienia, sekcja „Dostawa”
Powiązane tematy
- Jeśli chcesz widzieć wszystkie paczki wszystkich przewoźników na jednej liście — Przesyłki.
- Jeśli wysyłasz też UPS lub FedEx — UPS w Elbuz, FedEx w Elbuz.
- Jeśli chcesz porównać sposoby wystawiania listu przewozowego — list przewozowy z zamówienia.
- Jeśli klient ma wybrać DHL Packstation w koszyku Twojego sklepu internetowego — to dostawa w sklepie Elbuz CMS.
