↑↓ wybierzEnter otwórzEsc zamknij

    1. Elbuz
    2. Firmy kurierskie w Elbuz

    UPS API w Elbuz: list przewozowy z zamówienia, etykieta, kurier i śledzenie

    5 min czytaniaZaktualizowano

    Elbuz działa z UPS API przez Twoją aplikację na developer.ups.com. List przewozowy i etykietę UPS wystawiasz z karty zamówienia, stamtąd też zamawiasz kuriera, a statusy program pobiera sam co 10 minut.

    Kiedy to się przyda:

    • Wysyłasz z Polski lub innego kraju UE — adres i kraj odbiorcy są brane z zamówienia, panel UPS do listu przewozowego nie jest potrzebny.
    • Etykietę trzeba wydrukować ponownie — druk jest dostępny także kilka dni po utworzeniu listu przewozowego.
    • Paczki są odbierane z Twojego adresu — zgłoszenie odbioru przez kuriera UPS składasz z listu przewozowego.
    • Klient pyta, gdzie jest paczka — status UPS widać w zamówieniu i w rejestrze paczek.

    Od czego zacząć: utwórz aplikację na developer.ups.com → wpisz klucze w Elbuz.

    Co potrafi UPS w Elbuz

    • Podłączenie — Client ID, Client Secret, numer klienta UPS i środowisko testowe UPS.
    • List przewozowy z zamówienia — odbiorca, adres, waga i wymiary wstawiają się same.
    • Etykieta — druk i ponowny druk po numerze listu przewozowego.
    • Zamówienie kuriera — data i godziny odbioru, w odpowiedzi numer zgłoszenia UPS.
    • Statusy paczek — co 10 minut; według Twojej tabeli kodów zmieniają się statusy zamówień.

    Jak podłączyć UPS API: klucze i numer klienta

    Skąd wziąć Client ID i Client Secret UPS

    1. Zaloguj się na developer.ups.com kontem UPS i wybierz „Create an Application” (albo „My Apps” → „Add Apps”).
    2. Wybierz numer klienta UPS, do którego przypisana będzie aplikacja, i zaakceptuj UPS API Access Agreement.
    3. Dodaj produkty Shipping, Tracking i Pickup; Authorization (OAuth) dodaje się sam.
    4. Zapisz aplikację i skopiuj Client ID oraz Client Secret z „My Apps”.

    Numer klienta UPS widać w profilu UPS, w sekcji „Accounts and Payments”. Nie masz jeszcze konta w Polsce — załóż je na ups.com.

    Plan Community jest bezpłatny. Według cennika UPS miesięcznie: śledzenie — 90 000 zapytań, listy przewozowe i kurier — bez limitu, ponowne etykiety — 10 000. Każdy wydruk z Elbuz to jedno zapytanie o ponowną etykietę.

    Co wpisać w Elbuz

    Gdzie: Usługi zewnętrzne i integracje → Dostawa → „UPS”.

    PoleCo wpisać
    „Aktywność”Włączone — inaczej list przewozowy UPS się nie otworzy
    „Użytkownik”Client ID
    „Hasło”Client Secret
    „Numer klienta UPS (Shipper Number)”6 znaków numeru klienta; z tego konta UPS pobiera opłatę
    „Domyślna usługa”Usługa dla wszystkich listów przewozowych (którą wybrać)
    „Środowisko testowe (sandbox)”Włącz do testów, wyłącz do pracy
    Blok „Nadawca”Firma, osoba kontaktowa, kraj kodem ISO (puste — PL), kod pocztowy, miasto, ulica, nr domu, telefon, e-mail. To adres nadawcy na liście przewozowym i adres odbioru
    „Firma”Twoja firma, jeśli każda ma własne konto UPS; rekord firmy ma pierwszeństwo przed ogólnym
    Formularz podłączenia UPS: dane dostępowe API, parametry UPS i blok „Nadawca”
    1Użytkownik i hasło
    2Numer klienta UPS (Shipper Number)
    3Domyślna usługa
    4Środowisko testowe (sandbox)
    5Nadawca
    1. „Użytkownik” i „Hasło” — Client ID i Client Secret aplikacji z developer.ups.com.
    2. „Numer klienta UPS (Shipper Number)” — numer Twojego konta klienta UPS.
    3. „Domyślna usługa” — usługa UPS ustawiana w nowym liście przewozowym.
    4. „Środowisko testowe (sandbox)” — przełącznik, który kieruje zapytania do środowiska testowego UPS zamiast produkcyjnego.
    5. „Nadawca” — adres odbioru i adres zwrotny drukowany na etykiecie.

    Formularz zapisuje się sam, gdy tylko zmienisz pole. „Hasło” po zapisie pokazuje kropki, a puste pole nie kasuje klucza.

    Przy zapisie Elbuz nie sprawdza kluczy. Błąd klucza pokaże pierwszy list przewozowy: „UPS OAuth: ‹tekst UPS›”.

    Którą usługę wybrać

    UsługaCo to jest
    UPS Standard (11)Domyślna
    UPS Express Saver (65)Ekspresowa; w innych krajach UE UPS nazywa ją UPS Worldwide Saver
    UPS Express (07)Ekspresowa
    UPS Expedited (08)Usługa międzynarodowa

    Nazwy i kody pochodzą z słownika usług UPS; które są dla Ciebie dostępne, określa umowa z UPS. Usługa jest jedna dla wszystkich listów przewozowych, w formularzu listu nie da się jej zmienić.

    Środowisko testowe UPS

    Włącz „Środowisko testowe (sandbox)” — listy przewozowe trafią do środowiska testowego UPS (CIE) z tymi samymi Client ID i Client Secret. Etykiety mają tam znak wodny „Sample”, pieniądze nie są pobierane. Przed rozpoczęciem pracy wyłącz przełącznik.

    Jak wystawić list przewozowy UPS 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 „UPS” → sekcja „Dostawa” → „Utwórz list przewozowy”.

    Co formularz wypełni sam i co sprawdzić

    PoleSkądCo sprawdzić
    Nazwisko, Imię, Telefon, E-mailZamówienieTelefon jest obowiązkowy
    Kod pocztowy, Miejscowość, Ulica, Nr domu, Nr mieszkaniaAdres dostawy zamówienia: cały adres trafia do „Ulica”, „Nr domu” i „Nr mieszkania” są pusteUlica, nr domu i nr mieszkania razem — do 35 znaków, miasto — do 30; dłuższe Elbuz przytnie
    Kraj (kod ISO: DE, FR, IT, ES…)Kraj dostawy zamówieniaNierozpoznany — kraj nadawcy
    Waga całkowita, kgWaga produktów zamówieniaJeśli produkty też nie mają wagi — pójdzie 1 kg; zaokrąglenie do 0,1 kg
    Długość, Szerokość, Wysokość, cmPustePrzekazywane tylko wtedy, gdy wypełniono wszystkie trzy
    Opis przesyłkiKategoria lub lista produktówDo 50 znaków
    Dostawa zwrotna (odbiorca)„Pieniądze”, jeśli zamówienie nie jest opłacone, a płatność następuje przy odbiorzeUstaw „Niepotrzebna”: pobranie UPS nie jest podłączone
    Formularz tworzenia listu przewozowego UPS: odbiorca, adres i parametry przesyłki
    1Kraj odbiorcy (kod ISO)
    2Waga całkowita, kg
    3Długość / Szerokość / Wysokość
    4Pobranie: „Niepotrzebna”
    5Przycisk „Utwórz list przewozowy”
    1. Kraj odbiorcy — dwuliterowy kod ISO, np. DE.
    2. Waga całkowita paczki w kilogramach.
    3. Wymiary paczki: długość, szerokość i wysokość w centymetrach.
    4. „Dostawa zwrotna (odbiorca)” ustawiona na „Niepotrzebna”.
    5. „Utwórz list przewozowy” wysyła zgłoszenie do UPS.

    Numer zamówienia trafia do listu przewozowego jako referencja, do 35 znaków. Płaci nadawca — z Twojego konta UPS, opakowanie jest Twoje. Punktów odbioru UPS Access Point formularz nie oferuje: dostawa tylko na adres.

    Co się dzieje po kliknięciu „Utwórz list przewozowy”

    1. Elbuz sprawdza dane jeszcze przed wysłaniem do UPS. Gdy brakuje numeru klienta lub adresu nadawcy, pojawia się komunikat z przyczyną, np. „Error: UPS account number is required (API settings)”; list przewozowy nie powstaje.
    2. UPS tworzy przesyłkę. Numer śledzenia paczki trafia do „Numer listu przewozowego”, pojawia się „Utworzono list przewozowy nr ‹numer›”.
    3. Jeśli UPS odmówi, w oknie będzie jego komunikat z kodem w nawiasie, a zamówienie zostanie bez numeru.

    Aby w zamówieniu pojawiał się link do śledzenia, w sposobie dostawy „UPS” wypełnij „Link do śledzenia przesyłki”, np. https://www.ups.com/track?loc=pl_PL&tracknum= (sposoby dostawy).

    List przewozowy powstaje od razu i jest płatny według cennika UPS. Anulować ani zmienić go z Elbuz nie można — tylko w UPS. Po anulowaniu wyczyść „Numer listu przewozowego” w zamówieniu, aby wystawić nowy.

    Jak wydrukować etykietę UPS

    Gdzie: karta zamówienia → „Podgląd listu przewozowego” → ikona drukarki; albo „Przesyłki” → wiersz → „Drukuj list przewozowy”.

    Etykieta otwiera się w nowej karcie jako obraz GIF. Elbuz za każdym razem pobiera ją z UPS po numerze listu przewozowego, więc ponownie wydrukujesz nawet list, którego numer wpisano ręcznie. UPS przechowuje kopie etykiet przez 90 dni (pomoc UPS).

    Jak zamówić kuriera UPS

    Gdzie: karta zamówienia → „Podgląd listu przewozowego” → blok „Zamówienie kuriera”.

    • „Data odbioru” — domyślnie najbliższy dzień roboczy.
    • „Odbiór od” i „do” — puste: 09:00–17:00.
    • „Liczba paczek, szt.” i „Waga całkowita, kg” — ile odebrać.

    „Zamów kuriera” → „Kurier zamówiony #‹numer›”. Numer zgłoszenia UPS (PRN) zapisuje się w zamówieniu, adres odbioru to blok „Nadawca” podłączenia.

    W Polsce jednorazowy odbiór UPS jest płatny: jedna opłata za przyjazd, niezależnie od liczby paczek (warunki UPS). Codzienny odbiór ustawia się na koncie UPS — wtedy zgłoszenia nie są potrzebne.

    Jak Elbuz śledzi paczki UPS

    Co 10 minut Elbuz pyta UPS o paczki — do 100 listów przewozowych na przebieg. Śledzi zamówienia z ostatnich 60 dni i zamówienia w oznaczonych statusach, dopóki paczka nie otrzyma stanu „Doręczona”. Kod i tekst statusu UPS widać w zamówieniu i w „Przesyłkach”.

    W „Przesyłkach” dla UPS działają „Drukuj list przewozowy”, „SMS do odbiorcy” i „Śledź na stronie przewoźnika” — strona ups.com z numerem paczki.

    Jak zmieniać statusy zamówień według kodów UPS

    Kody UPS Elbuz wpisuje w „Statusy dostawy” sam. Kod, którego nie ma w tabeli, daje w „Przesyłkach” stan „Nieznany”, a status zamówienia się według niego nie zmienia.

    1. W podłączeniu UPS, w bloku „Statusy zamówień, dla których sprawdzać status przesyłki w firmie kurierskiej”, oznacz statusy, w których zamówienie czeka na dostawę, 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 UPS z tabeli poniżej są już wpisane w kolumnie „Kod (nazwa) na stronie (API)”; własne dopisuj po przecinku.
    Kody UPS do okna „Statusy dostawy”
    Twój status dostawyKod UPSStan w „Przesyłkach”
    Oczekiwanie od nadawcyM — UPS otrzymał dane przesyłkiUtworzona
    W drodzeI — w drodze, także w doręczeniu; P — odebranaW drodze
    DostarczonoDDoręczona, odpytywanie się kończy
    OdrzucenieRS — zwrot do nadawcyOdmowa, odpytywanie się kończy

    Bez kodu D przy „Dostarczono” w „Statusy dostawy” paczka nie dostanie stanu „Doręczona”. Elbuz będzie o nią pytał także po doręczeniu, zajmując miejsce w limicie 100 listów przewozowych na przebieg.

    Kod wyjątku X i kod anulowanej przesyłki MV zostaw poza tabelą: taka paczka będzie miała stan „Nieznany” i ją zauważysz. Kody pochodzą ze słownika śledzenia UPS. Jak działają trzy tabele statusów — w artykule o automatycznej zmianie statusu zamówienia.

    Scenariusze

    Pierwsze podłączenie bez ryzyka

    Wpisz klucze i numer klienta, włącz „Środowisko testowe (sandbox)”. Wystaw list przewozowy dla własnego zamówienia i wydrukuj etykietę ze znakiem wodnym „Sample”. Jeśli wszystko gra — wyłącz przełącznik.

    Codzienna wysyłka po UE

    „Domyślna usługa” — UPS Standard. Dla każdego zamówienia — „Utwórz list przewozowy” i druk etykiety. Kuriera zamawiaj jednym zgłoszeniem dziennie albo ustaw codzienny odbiór w UPS.

    Zamówienia zamykają się same

    Oznacz w podłączeniu status „Wysłano”. Kod D wpisz przy „Dostarczono” zarówno w „Statusy dostawy”, jak i w „Statusy zamówienia”. Gdy paczka zostanie doręczona, zamówienie przejdzie na „Dostarczono”, a Elbuz przestanie o nią pytać.

    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 Client Secret albo wyłączono „Aktywność” Wypełnij „Hasło” i włącz „Aktywność” (co wpisać)
    „UPS OAuth: …” UPS nie przyjął Client ID lub Client Secret Skopiuj klucze ponownie z „My Apps” na developer.ups.com
    „UPS account number is required (API settings)” Puste pole „Numer klienta UPS (Shipper Number)” Wpisz numer klienta
    „sender address and phone are required (API settings)” W bloku „Nadawca” brakuje nazwy, ulicy, miasta, kodu pocztowego lub telefonu Wypełnij „Nadawca” w podłączeniu
    „name and phone are required for recipient” albo „address is required for recipient” W zamówieniu brakuje imienia, telefonu, ulicy, miasta lub kodu pocztowego odbiorcy Uzupełnij je w formularzu listu przewozowego
    „cash on delivery is not supported for UPS yet — choose «without COD»” W „Dostawa zwrotna (odbiorca)” ustawiono „Pieniądze” Wybierz „Niepotrzebna”
    W „Przesyłkach” paczka UPS ma stan „Nieznany” Kodu UPS nie ma w oknie „Statusy dostawy” Dopisz kod (kody UPS)

    Najczęstsze pytania

    Ile kosztuje integracja UPS w Elbuz?

    Elbuz nic nie pobiera za listy przewozowe, etykiety ani statusy UPS. API UPS w planie Community jest bezpłatne, za dostawę i kuriera płacisz UPS.

    Czy można wysyłać UPS spoza Polski?

    Tak, z dowolnego kraju UE: wpisz kod kraju w polu „Kraj” bloku „Nadawca”. Elbuz nie przekazuje danych celnych, dlatego wysyłki są możliwe w obrębie UE.

    Czy z Elbuz można wysłać UPS za pobraniem?

    Nie, pobranie UPS nie jest podłączone: list przewozowy z „Pieniądze” zostaje odrzucony. Zostaw „Niepotrzebna” albo nadaj taką paczkę w UPS.

    Jak anulować list przewozowy UPS?

    Tylko w UPS. Potem wyczyść „Numer listu przewozowego” w zamówieniu (po utworzeniu).

    Czy można wybrać usługę UPS dla pojedynczego listu przewozowego?

    Nie, usługa jest jedna dla wszystkich — „Domyślna usługa” w podłączeniu. Przełącz ją przed listem przewozowym innego typu.

    Dlaczego status UPS nie zmienia statusu zamówienia?

    Status zamówienia nie jest oznaczony w podłączeniu albo kodu UPS nie ma w tabeli. Oznacz status i wpisz kody (kody UPS).

    Gdzie to jest i kto ma dostęp

    Menu
    Panel klienta → Ustawienia systemu → Inne ustawienia → Usługi zewnętrzne i integracje → Dostawa → UPS
    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 i kurier — okno „Tworzenie listu przewozowego”
    Przygotuj
    konto UPS z numerem klienta (Shipper Number) i aplikację na developer.ups.com
    1. Utwórz aplikację i kluczedeveloper.ups.com
    2. Wpisz klucze, numer klienta i dane nadawcyUsługi zewnętrzne i integracje → UPS
    3. Wpisz kody statusów UPSTamże, „Ustawienia powiadomień”
    4. Wystaw list przewozowy i wydrukuj etykietęKarta zamówienia, sekcja „Dostawa”
    5. Zamów kurieraPodgląd listu przewozowego

    Powiązane tematy

    • Jeśli chcesz widzieć wszystkie paczki wszystkich przewoźników na jednej liście — Przesyłki.
    • Jeśli wysyłasz też przez FedEx — FedEx w Elbuz: formularz listu przewozowego jest ten sam.
    • Jeśli sklep działa w Niemczech i współpracuje z DHL Paket — DHL Paket w Elbuz.
    • Jeśli chcesz porównać sposoby wystawiania listu przewozowego — list przewozowy z zamówienia.

    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