↑↓ wybierzEnter otwórzEsc zamknij

    1. Elbuz
    2. Firmy kurierskie w Elbuz

    Ukrposhta API w Elbuz: list przewozowy z zamówienia, etykieta i statusy paczek

    5 min czytaniaZaktualizowano

    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

    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.

    1. W pole „Token” wklej Bearer eCom.
    2. W bloku „Parametry Ukrposhta” wypełnij „Token kontrahenta (counterparty token)” i „UUID nadawcy”.
    3. Jeśli opiekun wydał osobny Bearer StatusTracking, wpisz go w „Token śledzenia (StatusTracking)”. Gdy pole jest puste, statusy są pobierane z tym samym „Token”.
    4. 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.

    Formularz podłączenia Ukrposhty z polem „Token” i blokiem „Parametry Ukrposhta”
    1Token (Bearer eCom)
    2Token kontrahenta
    3Token śledzenia (StatusTracking)
    4Statusy zamówień do sprawdzania
    5UUID nadawcy
    1. „Token” — klucz Bearer wydany przez Ukrposhta eCom.
    2. „Token kontrahenta” — wydaje go Ukrposhta przy podłączeniu do API.
    3. „Token śledzenia (StatusTracking)” — służy do pobierania statusów paczek.
    4. Lista statusów zamówień — dla zamówień w tych statusach Elbuz sprawdza status paczki u przewoźnika.
    5. „UUID nadawcy” — identyfikator nadawcy wydany przez Ukrposhtę.
    Elbuz nie sprawdza kluczy przy zapisie. Błąd klucza zobaczysz dopiero przy pierwszym liście przewozowym — w treści odpowiedzi Ukrposhty.

    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 dostawyKody UkrposhtyCo oznaczają
    Oczekiwanie od nadawcy10100Przyjęto w oddziale
    W drodze20700, 20800, 20900, 21500Sortownia, wysłano, w drodze do oddziału doręczenia
    W miejscu docelowym21700, 21400, 31400Dotarła do oddziału doręczenia, w przechowaniu
    Dostarczono41000Doręczono
    Odrzucenie31200, 41010Paczka wraca do nadawcy, zwrot doręczono Tobie
    Tabela „Statusy dostawy” z kodami Ukrposhty
    1Kolumna „Kod (nazwa) na stronie (API)”
    2W miejscu docelowym
    3Dostarczono
    4Odrzucenie
    1. „Kod (nazwa) na stronie (API)” — kody statusów Ukrposhty przypisane do każdego statusu dostawy.
    2. „W miejscu docelowym” — 21700, 21400, 31400.
    3. „Dostarczono” — 41000.
    4. „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ć

    PoleSkąd pochodzi
    Nazwisko, Imię, Imię ojca, Telefon, E-mailZ zamówienia
    Kod pocztowyKod pocztowy oddziału wybranego na Twojej stronie Elbuz CMS; w przeciwnym razie — kod z adresu dostawy
    Obwód, Miejscowość, UlicaZ adresu dostawy
    Waga całkowita, kgSuma wag produktów; gdy puste — pójdzie 1 kg
    Deklarowana wartość, UAHSuma 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”.

    Formularz listu przewozowego Ukrposhty otwarty z zamówienia, całe okno
    1Sposób nadania
    2Kod pocztowy
    3Pobranie: „Pieniądze”
    4Powiadomienie SMS
    5Utwórz list przewozowy
    1. „Sposób nadania” — przełącza między dostawą do oddziału a na adres.
    2. „Kod pocztowy” — kod pocztowy odbiorcy, wstawiony z zamówienia.
    3. „Dostawa zwrotna (odbiorca)” z wybranym „Pieniądze” — kwota, którą odbiorca płaci przy odbiorze.
    4. „Powiadomienie SMS dla odbiorcy” — przełącznik wysyłki SMS do odbiorcy.
    5. „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”

    1. Elbuz sprawdza, czy w rekordzie Ukrposhty są token kontrahenta i UUID nadawcy, a w formularzu — nazwisko, imię, telefon, kod pocztowy, miasto i deklarowana wartość.
    2. Tworzy w Ukrposhcie adres odbiorcy, potem odbiorcę, a na końcu samą przesyłkę.
    3. 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.”

    List przewozowy trafia do systemu Ukrposhty od razu. Usunąć go z Elbuz nie można — tylko w serwisach Ukrposhty, a potem wyczyść numer w polu zamówienia „Numer listu przewozowego”.

    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

    Najczęstsze problemy
    Co widziszDlaczego tak jestCo 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”.

    1. Otrzymaj klucze APIOpiekun z Ukrposhty
    2. Wpisz klucze i UUID nadawcyUsługi zewnętrzne i integracje → Ukrposhta
    3. Oznacz statusy i uzupełnij kodyTamże, „Ustawienia powiadomień”
    4. Wystaw list przewozowyKarta zamówienia, sekcja „Dostawa”
    5. Wydrukuj etykietęKarta zamówienia lub Przesyłki

    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