Skip to main content
StartBlogPrzewodnikiJak uzyskać najnowszy status przesyłki za pośrednictwem API bez czekania na webhook

Jak uzyskać najnowszy status przesyłki za pośrednictwem API bez czekania na webhook

17TRACK

Aby uzyskać najnowszy dostępny status przesyłki bez oczekiwania na webhook, wyślij uwierzytelnione żądanie do interfejsu API zapytań dotyczących przesyłek używanego dostawcy usług śledzenia. Użyj odpowiedzi, aby natychmiast zaktualizować aplikację, a następnie pozostaw webhooki włączone na potrzeby kolejnych zmian. Ważna różnica polega na tym, że zapytanie zwykle pobiera najnowsze zapisane przez dostawcę informacje o śledzeniu; nie musi ono uruchamiać nowego sprawdzenia u przewoźnika.

Jak uzyskać najnowszy status przesyłki za pomocą API bez

To podejście jest przydatne, gdy klient otwiera stronę zamówienia, pracownik działu wsparcia potrzebuje aktualizacji lub system musi odzyskać dane po pominiętym powiadomieniu. Niezawodna implementacja łączy zapytania na żądanie, jasne wskaźniki aktualności oraz zabezpieczenia przed zduplikowanymi lub nieuporządkowanymi aktualizacjami.

Zdecyduj, co oznacza „najnowszy status przesyłki”

Przed wyborem endpointu rozróżnij trzy operacje, które mogą brzmieć podobnie, ale dają różne wyniki.

OperacjaCo robiCzego nie potwierdza
Odczyt własnej bazy danychZwraca informacje o śledzeniu, które aplikacja już przechowuje.Czy dostawca otrzymał nowszą aktualizację.
Zapytanie do API śledzeniaPobiera informacje dostępne za pośrednictwem operacji zapytania dostawcy.Czy podczas tego żądania wykonano nowe wyszukiwanie u przewoźnika.
Żądanie odświeżenia śledzeniaŻąda kolejnego sprawdzenia źródłowego, jeśli dostawca oferuje taką operację.Że przewoźnik ma nowy skan lub że odświeżenie zakończy się synchronicznie.

Użyj zapytania, gdy potrzebujesz odpowiedzi teraz. Zbadaj operację odświeżania tylko wtedy, gdy chcesz, aby dostawca spróbował wykonać kolejne sprawdzenie źródłowe. Nie zakładaj, że dodanie parametru zapobiegającego buforowaniu, powtórzenie żądania lub wysłanie nagłówka HTTP cache-control zmusi przewoźnika do dostarczenia nowych informacji.

Widoczność przesyłki obejmuje kilka etapów: przewoźnik rejestruje zdarzenie, dostawca usług śledzenia je otrzymuje, a aplikacja odbiera je lub pobiera. Bezpośrednie żądanie API może ominąć oczekiwanie na dostarczenie powiadomienia, ale nie może wyeliminować wcześniejszych opóźnień w tym łańcuchu.

Sprawdź specyfikację zapytania przed napisaniem kodu

Za ten proces odpowiada programista integrujący usługę śledzenia. Zacznij od aktualnej dokumentacji dostawcy, a nie od endpointu skopiowanego ze starego przykładu integracji. Potwierdź następujące szczegóły:

  • Identyfikacja przesyłki: Czy zapytanie przyjmuje numer śledzenia, wewnętrzny identyfikator przesyłki czy numer śledzenia połączony z identyfikatorem przewoźnika?
  • Wymogi rejestracji: Czy przesyłka musi zostać zarejestrowana przed wysłaniem zapytania?
  • Uwierzytelnianie: Jaki nagłówek lub mechanizm uwierzytelniania jest wymagany?
  • Znaczenie odpowiedzi: Czy operacja zwraca zapisane informacje, rozpoczyna pobieranie danych czy zwraca zadanie do późniejszego sprawdzenia?
  • Obsługa wyników: Czy pomyślna odpowiedź HTTP może zawierać błąd na poziomie przesyłki lub wynik oczekujący?
  • Ograniczenia użycia: Jakie limity liczby żądań, limity partii i ograniczenia zależne od konta mają zastosowanie?
  • Pola aktualności: Które znaczniki czasu reprezentują zdarzenia przewoźnika, aktualizacje dostawcy i wygenerowanie odpowiedzi?

W przypadku integracji z 17TRACK właściwym produktem jest Tracking API, a nie strona śledzenia dla konsumentów ani interfejs śledzenia w sklepie. Użyj oficjalnej dokumentacji API, aby potwierdzić operację zapytania o informacje dotyczące śledzenia, uwierzytelnianie, pola żądania i strukturę odpowiedzi dla swojej integracji. Traktuj zapytania i obsługę webhooków jako oddzielne ścieżki aplikacji, które aktualizują ten sam rekord przesyłki.

Unikaj zakodowanych na stałe założeń dotyczących działania odświeżania lub częstotliwości zapytań. Szczegóły te muszą odpowiadać faktycznie używanej operacji i warunkom usługi.

Zbuduj wyszukiwanie na żądanie za pośrednictwem backendu

Praktycznym rozwiązaniem jest udostępnienie uwierzytelnionego endpointu we własnej aplikacji. Przeglądarka żąda aktualizacji przesyłki z tego endpointu; serwer sprawdza uprawnienia, decyduje, czy zapytanie do dostawcy jest konieczne, i zwraca ustandaryzowany wynik.

Poniższa trasa jest przykładem endpointu, który można utworzyć w aplikacji. Nie jest to endpoint 17TRACK ani specyfikacja żądania dostawcy.

GET /api/orders/{order_id}/shipment-status

Użyj identyfikatora zamówienia, aby wyszukać przesyłkę na serwerze. Nie pozwalaj wywołującemu pobierać historii śledzenia innego klienta wyłącznie przez zamianę numeru śledzenia w żądaniu. Przechowuj dane uwierzytelniające API dostawcy na backendzie, a nie w kodzie JavaScript przeglądarki ani w pakiecie aplikacji mobilnej.

Przykładowy przepływ żądania

  1. Uwierzytelnij dostęp. Potwierdź, że klient lub pracownik może wyświetlić zamówienie.
  2. Ustal przesyłkę. Odczytaj zapisany identyfikator śledzenia i informacje o przewoźniku, jeśli są dostępne.
  3. Sprawdź lokalną aktualność. Jeśli istnieje niedawne pomyślne zapytanie, użyj go ponownie zgodnie z zasadami aktualności aplikacji.
  4. W razie potrzeby wyślij zapytanie do dostawcy. Użyj udokumentowanej operacji i ograniczonego czasu oczekiwania na żądanie.
  5. Zweryfikuj wynik. Sprawdź zarówno rezultat HTTP, jak i wynik na poziomie przesyłki.
  6. Scal informacje. Zastosuj te same reguły normalizacji i uzgadniania, które są używane dla zdarzeń webhook.
  7. Zwróć status i aktualność. Jeśli są dostępne, uwzględnij czas najnowszego zdarzenia oraz czas ostatniego pomyślnego sprawdzenia dostawcy.

Lokalne zasady aktualności są decyzją inżynieryjną, a nie deklaracją dotyczącą częstotliwości aktualizacji przez przewoźnika. Wybierz je na podstawie wymagań interfejsu, limitów dostawcy, liczby przesyłek i obserwowanej użyteczności zapytań. Wielokrotne klikanie przez klienta przycisku aktualizacji nie powinno tworzyć nieograniczonego strumienia żądań źródłowych.

Normalizuj odpowiedź bez wymyślania informacji o aktualności

Aplikacja może zwracać stabilny format wewnętrzny nawet wtedy, gdy struktury odpowiedzi dostawców się różnią. Ten przykładowy obiekt jest własnym kontraktem aplikacji, a nie rzeczywistym ładunkiem dostawcy:

{
  "shipment_id": "internal-shipment-id",
  "status": "in_transit",
  "latest_event_at": null,
  "provider_updated_at": null,
  "last_successful_query_at": null,
  "retrieval_state": "success",
  "source": "provider_query"
}

Wypełniaj każdy znacznik czasu tylko wtedy, gdy znane jest jego znaczenie. Czas otrzymania odpowiedzi przez serwer należy do metadanych zapytania; nie wolno przedstawiać go jako czasu przemieszczenia paczki. Jeśli dostawca nie podaje znacznika czasu aktualizacji dostawcy, pozostaw to pole nieobecne lub ustaw je na null, zamiast zastępować je innym znacznikiem czasu.

W interfejsie klienta rozdziel komunikaty: „Najnowsze zdarzenie przewoźnika” opisuje aktywność przesyłki, natomiast „Sprawdzono śledzenie” opisuje aktywność pobierania danych przez aplikację. To rozróżnienie zapobiega wrażeniu, że niezmieniony skan został właśnie zarejestrowany.

Nie pozwól, aby zapytania API i webhooki wzajemnie nadpisywały dane

Gdy oba mechanizmy są aktywne, to samo zdarzenie może nadejść przez zapytanie i webhook. Mogą one również zakończyć się w innej kolejności niż zostały rozpoczęte. Zapytanie uruchomione jako pierwsze może zakończyć się po tym, jak webhook dostarczył już nowsze informacje.

Nie stosuj logiki „wygrywa ostatnia odpowiedź”. Ostatnio otrzymany ładunek nie musi przedstawiać najnowszego stanu przesyłki.

  • Udostępnij jeden potok aktualizacji. Przepuszczaj wyniki zapytań i ładunki webhooków przez te same funkcje walidacji, normalizacji i zapisu.
  • Usuwaj duplikaty zdarzeń. Preferuj udokumentowany identyfikator zdarzenia. Jeśli go nie ma, zbuduj starannie zdefiniowany odcisk na podstawie dostępnych pól, takich jak czas zdarzenia, status, lokalizacja i opis.
  • Używaj pól porządkowania o znanym znaczeniu. Udokumentowana rewizja lub sekwencja jest bardziej użyteczna niż zakładanie, że czas nadejścia określa kolejność zdarzeń.
  • Zachowuj historię. Nowo otrzymane zdarzenie może uzupełnić lukę historyczną bez zmiany bieżącego podsumowania przesyłki.
  • Umożliwiaj korekty. Statusy nie tworzą uniwersalnej liniowej drabiny. Postępuj zgodnie z udokumentowanym zachowaniem korekt, zamiast trwale odrzucać każdą pozorną zmianę wstecz.

Gdy kolejność zdarzeń jest niepewna, zachowaj pierwotny ładunek i informacje o jego pochodzeniu na potrzeby analizy. Nie rozwiązuj niejednoznaczności przez tworzenie fikcyjnego znacznika czasu zdarzenia ani zakładanie, że wszystkie znaczniki czasu przewoźników używają tej samej strefy czasowej.

Inaczej obsługuj brak danych i nieudane żądania

Pusty wynik, niezmieniony wynik i nieudane żądanie nie powinny powodować wyświetlenia tego samego komunikatu klientowi.

Zapytanie kończy się powodzeniem, ale status się nie zmienił

Zachowaj istniejący status przesyłki i zaktualizuj czas ostatniego pomyślnego zapytania. Nie generuj nowego zdarzenia przesyłki tylko dlatego, że zakończyło się kolejne wyszukiwanie. Jeśli klient potrzebuje więcej szczegółów, pokaż istniejącą historię zdarzeń i wyjaśnij, że nie zwrócono nowszego zdarzenia śledzenia.

Przesyłka nie ma jeszcze informacji o śledzeniu

Sprawdź, czy wymagana jest rejestracja, czy identyfikator i przewoźnik są prawidłowe oraz w jaki sposób dostawca przedstawia oczekujące pobieranie danych. Sam brak zdarzeń nie dowodzi, że numer śledzenia jest nieprawidłowy lub że paczka zaginęła. Zachowaj rozróżnienie dostawcy między nieznanym identyfikatorem, zarejestrowaną przesyłką oczekującą na informacje a żądaniem, którego nie można było przetworzyć.

Żądanie do dostawcy przekracza limit czasu lub kończy się niepowodzeniem

Jeśli masz wcześniejszy prawidłowy status, zwróć go z wyraźną informacją, że najnowsze sprawdzenie nie powiodło się. Zachowaj bez zmian wcześniejszy czas pomyślnego zapytania. Błąd sieci nie jest wyjątkiem dotyczącym dostawy i nie powinien zmieniać statusu biznesowego paczki.

W przypadku odpowiednich przejściowych błędów stosuj ograniczoną liczbę ponowień z narastającym opóźnieniem i losowym składnikiem. Nie ponawiaj wielokrotnie prób z powodu nieprawidłowych danych uwierzytelniających lub błędnie sformułowanych żądań. Jeśli odpowiedź zawiera Retry-After, interpretuj ją zgodnie z kontraktem dostawcy i semantyką HTTP. Specyfikacja HTTP dopuszcza wyrażenie tej wartości jako opóźnienia w sekundach lub daty HTTP.

Dla tej samej przesyłki przychodzi wiele żądań

Łącz równoczesne wyszukiwania, aby mogły współdzielić jedno żądanie źródłowe. Stosuj limity według konta i przesyłki oraz zapobiegaj zwielokrotnianiu automatycznych ponowień w kilku warstwach aplikacji. Jeśli obsługiwane jest przetwarzanie partiami, sprawdzaj wynik każdej przesyłki, zamiast uznawać całą partię za pomyślną tylko dlatego, że żądanie HTTP zostało zrealizowane.

Używaj odpytywania jako kontrolowanego rozwiązania awaryjnego

Bez webhooków zaplanowane odpytywanie może utrzymywać aktualność bazy danych, ale wymaga wyraźnych zasad działania. Określ, które przesyłki pozostają objęte obsługą, jak błędy wpływają na harmonogram oraz kiedy rutynowe odpytywanie zostaje zakończone.

W przypadku większości integracji rozsądnym punktem wyjścia jest projekt hybrydowy: webhooki obsługują zmiany w tle, zapytania na żądanie obsługują żądania interaktywne, a zadania uzgadniania sprawdzają rekordy wymagające uwagi. Jest to zalecenie architektoniczne, a nie gwarancja minimalizacji kosztów dla każdego konta.

  • Priorytetowo traktuj aktywne przesyłki i rekordy z nierozwiązanymi błędami pobierania.
  • Unikaj wysyłania zapytań dotyczących każdej historycznej przesyłki podczas każdego zaplanowanego uruchomienia.
  • Określ sposób obsługi zakończonych przesyłek, w tym ewentualny okres korekt wymagany przez firmę.
  • Śledź, jak często zapytania znajdują rzeczywiście nowe informacje.
  • Badaj problemy z dostarczaniem webhooków, zamiast maskować je coraz częstszym odpytywaniem.

Monitoruj opóźnienia żądań dostawcy, nieudane zapytania, odpowiedzi o przekroczeniu limitu oraz różnice między danymi pobranymi w zapytaniach a rekordami zasilanymi przez webhooki. Osobno monitoruj wiek najnowszego zdarzenia przewoźnika. Pomyślne odpowiedzi API mogą współistnieć z informacjami o śledzeniu, które się nie zmieniły.

Przetestuj proces przed wydaniem

Pomyślne żądanie to dopiero pierwszy test. Zweryfikuj sytuacje, które w przeciwnym razie mogą powodować mylące aktualizacje statusu:

  • Webhook przychodzi, gdy zapytanie na żądanie jest nadal wykonywane.
  • Dwóch klientów lub pracowników żąda jednocześnie informacji o tej samej przesyłce.
  • Dostawca zwraca powodzenie HTTP, ale zgłasza błąd na poziomie przesyłki.
  • Żądanie kończy się niepowodzeniem, gdy aplikacja ma już prawidłowe informacje o śledzeniu.
  • Zdarzenie nie zawiera strefy czasowej lub zawiera nieznany kod statusu.
  • Korekta przewoźnika zmienia wcześniej wyświetlony wynik.
  • Użytkownik próbuje uzyskać dostęp do przesyłki należącej do innego konta.

Kryterium wydania powinno zakładać, że aplikacja zwraca najlepiej znane informacje o przesyłce, dokładnie wyjaśnia ich aktualność oraz nie uszkadza tych informacji, gdy żądania kończą się niepowodzeniem lub przychodzą w niewłaściwej kolejności.

FAQ

Czy wysłanie zapytania do API zmusza przewoźnika do zeskanowania lub zaktualizowania paczki?

Nie. Pobranie informacji o śledzeniu nie może spowodować fizycznego skanu. To, czy żądanie uruchamia wyszukiwanie źródłowe, zależy od udokumentowanej operacji. Nawet obsługiwane odświeżenie może zwrócić niezmienione informacje, jeśli przewoźnik nie ma nowszego zdarzenia.

Czy mogę używać zapytań API bez konfigurowania webhooków?

Jeśli dostawca obsługuje wymagany proces zapytań, możesz zbudować integrację opartą na żądaniach na żądanie lub odpytywaniu. Najpierw potwierdź wymagania dotyczące rejestracji i zapytań. Aplikacja będzie wtedy odpowiadać za ustalenie momentu sprawdzania, kontrolowanie liczby żądań i wykrywanie zmian.

Jak często należy odpytywać status przesyłki?

Nie ma uniwersalnego interwału. Wybierz harmonogram odpowiedni do limitów dostawcy, liczby przesyłek i biznesowej wartości wcześniejszego wykrywania aktualizacji. Zmierz, jak często odpytywanie zwraca nowe zdarzenia, a następnie dostosuj harmonogram, zamiast zakładać, że częste żądania zapewniają świeższe dane przewoźnika.

Dlaczego API zwraca informacje, które już otrzymałem przez webhook?

Obie ścieżki mogą udostępniać ten sam źródłowy rekord przesyłki. Webhook dostarcza powiadomienie, natomiast zapytanie pobiera informacje na żądanie. Otrzymanie tego samego zdarzenia obiema drogami nie musi być błędem; aplikacja powinna usunąć duplikat.

Czy przycisk aktualizacji powinien mieć nazwę „Odśwież śledzenie”?

Tylko jeśli to określenie dokładnie opisuje operację. Jeśli przycisk pobiera zapisane dane dostawcy, wyraźniejsze będzie „Sprawdź aktualizacje”. Pokaż najnowsze zdarzenie przewoźnika oddzielnie od czasu ostatniego pomyślnego sprawdzenia zakończonego przez aplikację.

Źródła