↑↓ wybierzEnter otwórzEsc zamknij

    1. Elbuz
    2. Firmy kurierskie w Elbuz

    DHL API w Elbuz: list przewozowy DHL Paket, Packstation, pobranie i statusy

    7 min czytaniaZaktualizowano

    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

    CoSkąd wziąć
    Klucz APINa 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łoUż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
    Abrechnungsnummer14 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)”.

    PoleCo 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
    Formularz podłączenia DHL Paket z danymi dostępowymi, ustawieniami DHL Paket i blokiem nadawcy
    1Użytkownik i Hasło
    2Token
    3API Secret aplikacji
    4Numery Abrechnungsnummer
    5IBAN i właściciel konta
    6Środowisko testowe
    7Blok nadawcy
    1. Użytkownik i Hasło — Twoje logowanie do Geschäftskundenportal.
    2. Token — API Key z developer.dhl.com.
    3. API Secret aplikacji — sekret tej samej aplikacji z developer.dhl.com.
    4. Numery Abrechnungsnummer — 14-znakowe numery dla przesyłek krajowych i zagranicznych.
    5. IBAN i właściciel konta — dane rachunku do pobrań.
    6. Środowisko testowe — przełącza zapytania do środowiska testowego DHL.
    7. 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ć

    PoleSkądCo sprawdzić
    Nazwisko, Imię, Telefon, E-mailZamówienieImię, miejscowość i kod pocztowy są wymagane
    Kod pocztowy, Miejscowość, Ulica, Nr domu, Nr mieszkaniaAdres dostawy zamówienia: cały adres — w „Ulica”, „Nr domu” i „Nr mieszkania” pusteUlica — 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ówieniaNierozpoznany — kraj nadawcy
    Kod punktu odbioruPunkt z zamówieniaDla Packstation — „numer stacji/Postnummer”, dla Postfiliale — „Postfiliale numer/Postnummer” (Packstation i Postfiliale)
    Waga całkowita, kgWaga produktów zamówieniaJeśli wagi nie ma też w produktach — trafi 1 kg; DHL Paket — do 31,5 kg
    Długość, Szerokość, Wysokość, cmPustePrzekazywane 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 odbiorzeTylko w Niemczech (Nachnahme)
    Formularz tworzenia listu przewozowego DHL Paket z odbiorcą, adresem i opcjami przesyłki
    1Kod punktu odbioru
    2Kraj
    3Waga całkowita
    4Dostawa zwrotna
    5Utwórz list przewozowy
    1. Kod punktu odbioru — kod Packstation lub punktu odbioru; przy dostawie do domu puste.
    2. Kraj — dwuliterowy kod ISO kraju docelowego.
    3. Waga całkowita — waga paczki w kilogramach.
    4. Dostawa zwrotna — opcja zwrotu po stronie odbiorcy.
    5. 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.

    ProceduraProduktDo czego
    53DHL Paket International (V53WPAK)Paczki do klientów na całym świecie
    54DHL Europaket (V54EPAK)Tylko do firm (B2B), głównie do krajów UE
    66Warenpost 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”

    1. Elbuz sprawdza dane jeszcze przed wysłaniem do DHL. Brak Abrechnungsnummer potrzebnego typu lub adresu nadawcy — komunikat z przyczyną; list przewozowy się nie tworzy.
    2. DHL tworzy przesyłkę. Numer paczki trafia do „Numer listu przewozowego”, pojawia się „Utworzono list przewozowy nr ‹numer›”.
    3. 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.
    4. 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ą.

    1. 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”.
    2. W bloku „Ustawienia powiadomień” otwórz „Statusy dostawy” (w razie potrzeby także „Statusy zamówienia”, „Statusy płatności”).
    3. Kody DHL z tabeli poniżej są już wpisane w kolumnie „Kod (nazwa) na stronie (API)”; własne dopisuj po przecinku.
    Kody DHL do okna „Statusy dostawy”
    Twój status dostawyKod DHLStan w „Przesyłkach”
    Oczekiwanie od nadawcypre-transitUtworzona
    W drodzetransitW drodze
    DostarczonodeliveredDorę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.

    Okno statusów dostawy z kodami statusów DHL obok nazw statusów
    1Kolumna kodu
    2Dostarczono
    3Pusty kod
    1. Kod (nazwa) na stronie (API) — kod statusu zwracany przez DHL.
    2. Dostarczono — przypisany do kodu delivered.
    3. 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

    Najczęstsze problemy
    Co widziszDlaczego tak jestCo 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
    1. Uzyskaj klucz APIdeveloper.dhl.com
    2. Wpisz dane dostępowe, Abrechnungsnummer i nadawcęUsługi zewnętrzne i integracje → DHL Paket
    3. Wpisz kody statusów DHLTamże, „Ustawienia powiadomień”
    4. Wystaw list przewozowy i wydrukuj etykietęKarta zamówienia, sekcja „Dostawa”

    Powiązane tematy

    Czy ten artykuł był pomocny?

    Brakuje funkcji? Napisz do nas.

    Dodamy ją za darmo, jeśli przyda się też innym.

    Jeśli potrzebujesz jej tylko ty — umówimy się osobno.

    Spis treści

    Zaproponuj usprawnienie

    Wypróbuj Elbuz za darmo