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
- Zaloguj się na developer.ups.com kontem UPS i wybierz „Create an Application” (albo „My Apps” → „Add Apps”).
- Wybierz numer klienta UPS, do którego przypisana będzie aplikacja, i zaakceptuj UPS API Access Agreement.
- Dodaj produkty Shipping, Tracking i Pickup; Authorization (OAuth) dodaje się sam.
- 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”.
| Pole | Co 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 |
1
Użytkownik i hasło2
Numer klienta UPS (Shipper Number)3
Domyślna usługa4
Środowisko testowe (sandbox)5
Nadawca- „Użytkownik” i „Hasło” — Client ID i Client Secret aplikacji z developer.ups.com.
- „Numer klienta UPS (Shipper Number)” — numer Twojego konta klienta UPS.
- „Domyślna usługa” — usługa UPS ustawiana w nowym liście przewozowym.
- „Środowisko testowe (sandbox)” — przełącznik, który kieruje zapytania do środowiska testowego UPS zamiast produkcyjnego.
- „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ługa | Co 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ć
| Pole | Skąd | Co sprawdzić |
|---|---|---|
| Nazwisko, Imię, Telefon, E-mail | Zamówienie | Telefon jest obowiązkowy |
| Kod pocztowy, Miejscowość, Ulica, Nr domu, Nr mieszkania | Adres dostawy zamówienia: cały adres trafia do „Ulica”, „Nr domu” i „Nr mieszkania” są puste | Ulica, 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ówienia | Nierozpoznany — kraj nadawcy |
| Waga całkowita, kg | Waga produktów zamówienia | Jeśli produkty też nie mają wagi — pójdzie 1 kg; zaokrąglenie do 0,1 kg |
| Długość, Szerokość, Wysokość, cm | Puste | Przekazywane tylko wtedy, gdy wypełniono wszystkie trzy |
| Opis przesyłki | Kategoria lub lista produktów | Do 50 znaków |
| Dostawa zwrotna (odbiorca) | „Pieniądze”, jeśli zamówienie nie jest opłacone, a płatność następuje przy odbiorze | Ustaw „Niepotrzebna”: pobranie UPS nie jest podłączone |
1
Kraj odbiorcy (kod ISO)2
Waga całkowita, kg3
Długość / Szerokość / Wysokość4
Pobranie: „Niepotrzebna”5
Przycisk „Utwórz list przewozowy”- Kraj odbiorcy — dwuliterowy kod ISO, np. DE.
- Waga całkowita paczki w kilogramach.
- Wymiary paczki: długość, szerokość i wysokość w centymetrach.
- „Dostawa zwrotna (odbiorca)” ustawiona na „Niepotrzebna”.
- „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”
- 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.
- UPS tworzy przesyłkę. Numer śledzenia paczki trafia do „Numer listu przewozowego”, pojawia się „Utworzono list przewozowy nr ‹numer›”.
- 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.
- 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”.
- W bloku „Ustawienia powiadomień” otwórz „Statusy dostawy” (w razie potrzeby także „Statusy zamówienia”, „Statusy płatności”).
- Kody UPS z tabeli poniżej są już wpisane w kolumnie „Kod (nazwa) na stronie (API)”; własne dopisuj po przecinku.
| Twój status dostawy | Kod UPS | Stan w „Przesyłkach” |
|---|---|---|
| Oczekiwanie od nadawcy | M — UPS otrzymał dane przesyłki | Utworzona |
| W drodze | I — w drodze, także w doręczeniu; P — odebrana | W drodze |
| Dostarczono | D | Doręczona, odpytywanie się kończy |
| Odrzucenie | RS — zwrot do nadawcy | Odmowa, 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
| 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 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
- Utwórz aplikację i kluczedeveloper.ups.com
- Wpisz klucze, numer klienta i dane nadawcyUsługi zewnętrzne i integracje → UPS
- Wpisz kody statusów UPSTamże, „Ustawienia powiadomień”
- Wystaw list przewozowy i wydrukuj etykietęKarta zamówienia, sekcja „Dostawa”
- 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.
