Elbuz łączy się z Ukrposhta API i wystawia list przewozowy prosto z karty zamówienia, drukuje etykietę i co 10 minut pobiera status paczki — bez przepisywania danych do serwisów Ukrposhty.
Kiedy to się przyda:
- Wysyłasz przez Ukrposhtę w ramach umowy — odbiorca, kod pocztowy i kwota wstawiają się z zamówienia, list przewozowy tworzysz jednym przyciskiem.
- Klient płaci przy odbiorze — pobranie na kwotę zamówienia ustawia się samo, jeśli zamówienie nie jest opłacone.
- Masz dużo paczek — listy przewozowe zbiorczo z listy zamówień, statusy wszystkich paczek — w oknie „Przesyłki”.
Od czego zacząć: otrzymaj klucze API od opiekuna w Ukrposhcie → wpisz je w rekordzie Ukrposhty w Elbuz.
Co potrafi Ukrposhta w Elbuz
- List przewozowy z zamówienia — do oddziału lub na adres, z pobraniem i SMS do odbiorcy; pojedynczo lub zbiorczo.
- Etykieta — PDF z karty zamówienia lub z „Przesyłek”.
- Statusy paczek — co 10 minut; według Twojej tabeli kodów Elbuz zmienia status zamówienia, dostawy i płatności.
- Stan paczki w „Przesyłkach” — w drodze, w oddziale, odebrana, odmowa.
Rejestry, przekierowanie, zwrot, zmiana i usunięcie listu przewozowego oraz zamówienie kuriera z Elbuz spośród ukraińskich przewoźników są dostępne tylko w Nova Poshta. W Ukrposhcie te działania wykonuje się w jej serwisach.
Jak podłączyć Ukrposhtę: klucze API i nadawca
Skąd wziąć klucze API Ukrposhty
Klucze wydaje opiekun z Ukrposhty po podpisaniu umowy — w panelu klienta na stronie ich nie ma. Według dokumentacji API Ukrposhty po zawarciu umowy otrzymujesz tabelę dostępów:
- Bearer eCom — do tworzenia przesyłek;
- Bearer StatusTracking — do statusów paczek;
- Counterparty token — token użytkownika;
- Counterparty UUID — identyfikator kontrahenta.
Potrzebny jest jeszcze UUID nadawcy — identyfikator klienta-nadawcy z Twoim adresem w systemie Ukrposhty. Tworzy się go przez API; poproś opiekuna lub wsparcie techniczne API (api-support@ukrposhta.ua) o gotowy UUID. Panel klienta na stronie Ukrposhty to osobna usługa dla osób fizycznych: przesyłek utworzonych przez API w nim nie widać.
Gdzie wpisać klucze w Elbuz
Gdzie: Usługi zewnętrzne i integracje → grupa „Dostawa” → rekord Ukrposhty.
- W pole „Token” wklej Bearer eCom.
- W bloku „Parametry Ukrposhta” wypełnij „Token kontrahenta (counterparty token)” i „UUID nadawcy”.
- Jeśli opiekun wydał osobny Bearer StatusTracking, wpisz go w „Token śledzenia (StatusTracking)”. Gdy pole jest puste, statusy są pobierane z tym samym „Token”.
- Włącz „Aktywność”.
Pola „Użytkownik” i „Hasło” dla Ukrposhty nie są potrzebne. Zapisanego klucza nie widać: pole „Token” pokazuje kropki, a puste pole nie kasuje klucza.
1
Token (Bearer eCom)2
Token kontrahenta3
Token śledzenia (StatusTracking)4
Statusy zamówień do sprawdzania5
UUID nadawcy- „Token” — klucz Bearer wydany przez Ukrposhta eCom.
- „Token kontrahenta” — wydaje go Ukrposhta przy podłączeniu do API.
- „Token śledzenia (StatusTracking)” — służy do pobierania statusów paczek.
- Lista statusów zamówień — dla zamówień w tych statusach Elbuz sprawdza status paczki u przewoźnika.
- „UUID nadawcy” — identyfikator nadawcy wydany przez Ukrposhtę.
Statusy dostawy: jakie kody Ukrposhty wpisać
Elbuz zmienia status zamówienia tylko dla zamówień w statusach oznaczonych na liście „Statusy zamówień, dla których sprawdzać status przesyłki w firmie kurierskiej”. Co na co zmieniać, określają trzy okna w bloku „Ustawienia powiadomień”: „Statusy zamówienia”, „Statusy dostawy”, „Statusy płatności”.
Kody Ukrposhty w „Statusy dostawy” Elbuz wpisuje sam, na ich podstawie „Przesyłki” pokazują stan paczki. „Statusy zamówienia” i „Statusy płatności” wypełniasz Ty, po przecinku. Kody pochodzą z dokumentacji śledzenia statusów Ukrposhty:
| Twój status dostawy | Kody Ukrposhty | Co oznaczają |
|---|---|---|
| Oczekiwanie od nadawcy | 10100 | Przyjęto w oddziale |
| W drodze | 20700, 20800, 20900, 21500 | Sortownia, wysłano, w drodze do oddziału doręczenia |
| W miejscu docelowym | 21700, 21400, 31400 | Dotarła do oddziału doręczenia, w przechowaniu |
| Dostarczono | 41000 | Doręczono |
| Odrzucenie | 31200, 41010 | Paczka wraca do nadawcy, zwrot doręczono Tobie |
1
Kolumna „Kod (nazwa) na stronie (API)”2
W miejscu docelowym3
Dostarczono4
Odrzucenie- „Kod (nazwa) na stronie (API)” — kody statusów Ukrposhty przypisane do każdego statusu dostawy.
- „W miejscu docelowym” — 21700, 21400, 31400.
- „Dostarczono” — 41000.
- „Odrzucenie” — 31200, 41010.
Aby zamówienie samo przechodziło na „Dostarczono”, w „Statusy zamówienia” przy „Dostarczono” wpisz 41000. Elbuz przestaje pytać o paczkę dopiero wtedy, gdy jej kod stoi przy „Dostarczono” lub „Częściowo dostarczone” w „Statusy dostawy”.
Zwrot doręczony Tobie Ukrposhta oznacza kodem doręczenia z przyczyną «відправнику» (do nadawcy) — Elbuz pokazuje go jako 41010, osobno od 41000.
Jak utworzyć list przewozowy Ukrposhty z zamówienia
Gdzie: karta zamówienia → sekcja „Dostawa” → „Utwórz list przewozowy”. Link jest widoczny, jeśli sposób dostawy zamówienia to Ukrposhta; po pierwszym otwarciu formularza nazywa się „Edytuj list przewozowy”.
Co formularz wypełni sam i co sprawdzić
| Pole | Skąd pochodzi |
|---|---|
| Nazwisko, Imię, Imię ojca, Telefon, E-mail | Z zamówienia |
| Kod pocztowy | Kod pocztowy oddziału wybranego na Twojej stronie Elbuz CMS; w przeciwnym razie — kod z adresu dostawy |
| Obwód, Miejscowość, Ulica | Z adresu dostawy |
| Waga całkowita, kg | Suma wag produktów; gdy puste — pójdzie 1 kg |
| Deklarowana wartość, UAH | Suma zamówienia |
| Dostawa zwrotna (odbiorca) | „Pieniądze” na kwotę zamówienia, jeśli nie jest opłacone, a płatność następuje przy odbiorze |
| Płatnik dostawy | „Odbiorca”, jeśli dostawa w zamówieniu wynosi 0; w przeciwnym razie „Nadawca”. Prowizję za pobranie płaci odbiorca |
„Sposób nadania” — „Oddział” lub „Adres”. Zamówienie z dostawą kurierską ze strony Elbuz CMS formularz otwiera od razu z „Adres”.
Przy wysyłce do oddziału Ukrposhta bierze tylko kod pocztowy, więc sprawdź właśnie go. Dla adresu pojawiają się „Ulica”, „Nr domu”, „Nr mieszkania”.
1
Sposób nadania2
Kod pocztowy3
Pobranie: „Pieniądze”4
Powiadomienie SMS5
Utwórz list przewozowy- „Sposób nadania” — przełącza między dostawą do oddziału a na adres.
- „Kod pocztowy” — kod pocztowy odbiorcy, wstawiony z zamówienia.
- „Dostawa zwrotna (odbiorca)” z wybranym „Pieniądze” — kwota, którą odbiorca płaci przy odbiorze.
- „Powiadomienie SMS dla odbiorcy” — przełącznik wysyłki SMS do odbiorcy.
- „Utwórz list przewozowy” — wysyła zgłoszenie do Ukrposhty.
Formularz zapisuje się w zamówieniu przy każdej zmianie pola: gdy otworzysz go następnym razem, zobaczysz swoje wartości.
Co się dzieje po kliknięciu „Utwórz list przewozowy”
- Elbuz sprawdza, czy w rekordzie Ukrposhty są token kontrahenta i UUID nadawcy, a w formularzu — nazwisko, imię, telefon, kod pocztowy, miasto i deklarowana wartość.
- Tworzy w Ukrposhcie adres odbiorcy, potem odbiorcę, a na końcu samą przesyłkę.
- Numer listu przewozowego (kod kreskowy) zapisuje w zamówieniu, a okno zamyka się z komunikatem „Utworzono list przewozowy nr…”.
Za dostawę płaci Ukrposhcie ten, kogo wybrano w „Płatnik dostawy”. Drugiego listu przewozowego dla tego samego zamówienia Elbuz nie utworzy: „List przewozowy już utworzony: … — pominięto.”
Jeśli połączenie zostało zerwane, numeru w zamówieniu nie będzie. Ponowne kliknięcie utworzy nową przesyłkę, nawet jeśli poprzednią Ukrposhta zdążyła zarejestrować — w razie wątpliwości zapytaj opiekuna z Ukrposhty.
Listy przewozowe zbiorczo
Gdzie: lista zamówień → zaznacz zamówienia → „Utwórz list przewozowy (dostawa)”. Przewoźnik jest brany ze sposobu dostawy każdego zamówienia, wartości — z zapisanego formularza lub z zamówienia.
Zamówienia z numerem listu przewozowego są pomijane. Więcej: listy przewozowe zbiorczo.
Jak wydrukować etykietę
Gdzie: karta zamówienia → „Podgląd listu przewozowego” → „Drukuj” albo „Przesyłki” → wiersz → „Drukuj list przewozowy”.
Elbuz sam pobiera z Ukrposhty etykietę adresową PDF 100×100 mm i otwiera ją w oknie. Klucze nie trafiają do przeglądarki. Zbiorczo z „Przesyłek” drukują się tylko listy przewozowe Nova Poshta — etykiety Ukrposhty drukuj pojedynczo.
Jak Elbuz śledzi paczki Ukrposhty
Co 10 minut Elbuz pyta Ukrposhtę o ostatni status każdego listu przewozowego. W jednym przebiegu — do 100 listów, najpierw te, które najdłużej nie były sprawdzane. Numery ze starego modułu Ukrposhty też są śledzone.
- Które zamówienia — utworzone w ciągu ostatnich 60 dni lub w oznaczonych statusach, dopóki kod paczki nie znajdzie się przy „Dostarczono” w „Statusy dostawy”.
- Zamówienia w oznaczonym statusie — status zamówienia, dostawy i płatności zmienia się według Twoich tabel, zmiana trafia do dziennika.
- Pozostałe zamówienia — aktualizują się tylko kod i tekst statusu Ukrposhty.
Wszystkie paczki widać w „Przesyłkach”: stan, kafelki, filtry, SMS do odbiorcy. Stan pochodzi z tabeli „Statusy dostawy”; aby odświeżyć od razu — „Odśwież statusy”.
Scenariusze
Pierwsze podłączenie
Co zrobić. Podpisz umowę, otrzymaj od opiekuna Bearer, token kontrahenta i UUID nadawcy. Wpisz je w rekordzie Ukrposhty, oznacz statusy „Wysłano” i „Dostarczono”, uzupełnij kody w „Statusy dostawy” i 41000 przy „Dostarczono” w „Statusy zamówienia”.
Efekt. Listy przewozowe wystawiasz z karty zamówienia, a zamówienia same przechodzą na „Dostarczono”, gdy Ukrposhta doręczy paczkę.
Płatność przy odbiorze
Co zrobić. Zostaw w zamówieniu płatność przy odbiorze i nie oznaczaj go jako opłaconego.
Efekt. W formularzu listu przewozowego jest już „Pieniądze” na kwotę zamówienia, odbiorca zapłaci w oddziale.
Zamówienie z Twojej strony
Co zrobić. Nic: klient na stronie Elbuz CMS wybiera oddział Ukrposhty.
Efekt. Kod pocztowy oddziału jest już w formularzu, list przewozowy tworzysz jednym przyciskiem.
Wysyłki z całego dnia
Co zrobić. Na liście zamówień zaznacz zamówienia Ukrposhty → „Utwórz list przewozowy (dostawa)”, potem w „Przesyłkach” — „Drukuj” przy każdym wierszu.
Efekt. Numery są w zamówieniach, etykiety wydrukowane, statusy pobiorą się same.
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…” zamiast formularza | W rekordzie Ukrposhty pole „Token” jest puste albo wyłączono „Aktywność” | Wpisz Bearer i włącz „Aktywność” (gdzie wpisać klucze) |
| „Error: sender uuid is required (API settings)” albo „counterparty token is required (API settings)” | Nie wypełniono „UUID nadawcy” lub „Token kontrahenta” | Wypełnij blok „Parametry Ukrposhta” (klucze API) |
| „Error: postcode is required for recipient” (albo first_name, last_name, phone, city), „declared_price is required for shipment”; kilka — po przecinku | W formularzu jest puste pole obowiązkowe | Wypełnij imię, nazwisko, telefon, kod pocztowy, miasto lub deklarowaną wartość (formularz) |
| „Error: …” z tekstem Ukrposhty | Ukrposhta odrzuciła dane: klucz, kod pocztowy, adres, kwotę pobrania | Popraw pole wskazane w treści błędu; w sprawie kluczy — do opiekuna z Ukrposhty |
| Paczki Ukrposhty w „Przesyłkach” mają stan „Nieznany” | Tabela „Statusy dostawy” rekordu Ukrposhty jest pusta | Wpisz kody (tabela kodów) |
| Listy przewozowe się tworzą, a statusy paczek nie przychodzą | Ukrposhta wydała osobny Bearer do śledzenia statusów, a pole na niego jest puste | Wpisz go w „Token śledzenia (StatusTracking)” (gdzie wpisać klucze) |
| „print error: …” w oknie wydruku | Ukrposhta nie zwróciła etykiety: list przewozowy usunięto albo klucz jest nieważny | Sprawdź list przewozowy w serwisach Ukrposhty i klucze w rekordzie |
Najczęstsze pytania
Ile kosztuje integracja z Ukrposhtą?
Elbuz nic nie pobiera za listy przewozowe, etykiety ani statusy. Za dostawę płacisz Ukrposhcie zgodnie z Twoją umową.
Kto płaci za dostawę — ja czy odbiorca?
Tak, jak wybierzesz w polu „Płatnik dostawy”. Domyślnie — odbiorca, jeśli dostawa w zamówieniu wynosi 0, w przeciwnym razie Ty. Prowizję za pobranie zawsze płaci odbiorca.
Czy można wysłać do paczkomatu albo za granicę?
Nie, w formularzu są tylko oddział i adres na Ukrainie.
Czy listy przewozowe z Elbuz widać w panelu klienta Ukrposhty?
Nie, według dokumentacji Ukrposhty przesyłki utworzone przez API nie są pokazywane w panelu klienta. Widać je w Elbuz w „Przesyłkach”.
Ile może ważyć paczka?
Według dokumentacji API Ukrposhty — do 30 kg dla przesyłki jednopaczkowej. Na adres poza strefą doręczeń kurierskich — do 2 kg i 70 cm.
Gdzie to jest i kto ma dostęp
- Menu
- Panel klienta → Ustawienia systemu → Inne ustawienia → Usługi zewnętrzne i integracje → Dostawa
- 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”; paczki — „Przesyłki”
- Przygotuj
- umowę z Ukrposhtą, Bearer, token kontrahenta, UUID nadawcy
List przewozowy można wystawić tylko dla zamówienia, które użytkownik widzi zgodnie z ustawieniem „Czyje dane”.
- Otrzymaj klucze APIOpiekun z Ukrposhty
- Wpisz klucze i UUID nadawcyUsługi zewnętrzne i integracje → Ukrposhta
- Oznacz statusy i uzupełnij kodyTamże, „Ustawienia powiadomień”
- Wystaw list przewozowyKarta zamówienia, sekcja „Dostawa”
- Wydrukuj etykietęKarta zamówienia lub Przesyłki
Powiązane tematy
- Jeśli chcesz widzieć paczki wszystkich przewoźników na jednej liście — Przesyłki.
- Jeśli wysyłasz też przez Nova Poshta — Nova Poshta API w Elbuz.
- Jeśli zamówienie przyszło z Rozetki i list przewozowy trzeba wystawić przez marketplace — list przewozowy przez Rozetka.
- Jeśli listy przewozowe trzeba wystawić dla dziesiątek zamówień — listy przewozowe zbiorczo.
- Jeśli klient ma wybierać Ukrposhtę w koszyku Twojej strony — to dostawa w sklepie Elbuz CMS.
