6 kontroli w celu weryfikacji najnowszych zdarzeń śledzenia przewoźnika zsynchronizowanych za pośrednictwem Twojego API
Aby zweryfikować, czy API zsynchronizowało najnowsze zdarzenia śledzenia przewoźnika, porównaj identyfikator przesyłki, sygnatury czasowe zdarzeń, szczegóły zdarzeń, trasę dostawy, kolejność zdarzeń oraz aktualność danych z niezależnym widokiem śledzenia. Pomyślna odpowiedź API lub potwierdzenie webhooka potwierdza tylko jedną część tego łańcucha; samo w sobie nie dowodzi, że aplikacja otrzymała najnowsze zdarzenie przewoźnika.

Ten przewodnik jest przeznaczony dla programistów i zespołów operacyjnych odpowiedzialnych za dostarczanie danych śledzenia do systemu zarządzania zamówieniami, strony skierowanej do klientów, narzędzia wsparcia lub procesu wysyłania alertów. Celem jest ustalenie, gdzie zdarzenie zaginęło lub uległo zmianie, a następnie podjęcie decyzji, czy ponowić przetwarzanie, poprawić mapowanie, czy poczekać na nowe informacje od przewoźnika.
Zanim zaczniesz: określ, co oznacza „najnowsze”
Rozdziel trzy momenty: kiedy przewoźnik twierdzi, że zdarzenie miało miejsce, kiedy dostawca śledzenia je otrzymał lub udostępnił oraz kiedy aplikacja je zapisała. Te momenty mogą się różnić. Przewoźnik może opublikować skan po faktycznym zdarzeniu, a integracja może przetworzyć go jeszcze później. Najnowsze zdarzenie według czasu wystąpienia nie musi więc być rekordem otrzymanym najpóźniej.
Przed rozpoczęciem analizy wybierz punkt odniesienia. Najlepiej użyć strony śledzenia przewoźnika lub innego autoryzowanego rekordu udostępnionego przez przewoźnika dla tej samej przesyłki. Jeśli nie jest to możliwe, porównaj aplikację z bieżącą odpowiedzią API dostawcy śledzenia. Takie węższe porównanie może ustalić, czy aplikacja jest zgodna z dostawcą; nie może jednak potwierdzić, że dostawca ma już każdy skan przewoźnika. Zapisz moment wykonania porównania, aby późniejsza aktualizacja nie sprawiła, że wcześniejszy wynik będzie wyglądał na niespójny.
1. Potwierdź, że oba systemy dotyczą tej samej przesyłki
Zacznij od numeru śledzenia, przewoźnika oraz wszelkich identyfikatorów konta lub przesyłki używanych przez integrację. Same numery śledzenia mogą być niewystarczające podczas rozwiązywania problemów: numer może zawierać literówkę, być przypisany do niewłaściwego przewoźnika lub zostać ponownie użyty w wewnętrznym rekordzie po edycji zamówienia. Numer zamówienia i numer śledzenia służą też różnym celom. Jedno zamówienie może obejmować wiele paczek, dlatego sprawdzenie najnowszego statusu zamówienia może ukryć nieaktualną paczkę.
- Znajdź dokładny numer śledzenia i przewoźnika przesłane do API śledzenia.
- Potwierdź, który wewnętrzny rekord przesyłki lub paczki otrzymał odpowiedź.
- Sprawdź, czy przesyłka nie została po rejestracji zastąpiona, podzielona, anulowana lub ponownie przypisana.
- Porównaj przewoźnika i numer pokazane w rekordzie źródłowym z tymi wyświetlanymi w aplikacji.
Jeśli identyfikatory się nie zgadzają, przestań traktować różnicę jako opóźnienie synchronizacji. Najpierw popraw powiązanie, a następnie ponownie porównaj zdarzenia. W dziennikach diagnostycznych przechowuj wystarczającą liczbę identyfikatorów, aby można było prześledzić przesyłkę, nie umieszczając w nich poufnych danych uwierzytelniających konta.
2. Porównuj czasy zdarzeń, nie tracąc ich znaczenia
Dla każdego kandydata na najnowsze zdarzenie zapisz zgłoszony przez przewoźnika czas wystąpienia, podaną strefę czasową lub przesunięcie, jeśli są dostępne, oraz czasy odebrania i zapisania przez aplikację. Przelicz sygnatury czasowe na wspólną podstawę do porównania, ale zachowaj oryginalną wartość. RFC 3339 definiuje internetowy format sygnatur czasowych z jawną informacją o przesunięciu; jest użytecznym punktem odniesienia przy projektowaniu własnych pól czasu. Nie gwarantuje jednak, że przewoźnik lub dostawca poda strefę czasową dla każdego zdarzenia.
Wyświetlanie samego czasu, założona lokalna strefa lub parser, który po cichu odrzuca przesunięcie, może przenieść zdarzenie na inną datę kalendarzową albo umieścić je w niewłaściwej kolejności. Jeśli źródło podaje niejednoznaczny czas lokalny, oznacz porównanie jako niepewne zamiast wymyślać precyzyjny moment UTC. Rozróżniaj także czas wystąpienia zdarzenia od czasu odpowiedzi API: odpowiedź pobrana teraz może prawidłowo zawierać zdarzenie, które miało miejsce wcześniej.
Zapisz moment, w którym sprawdziłeś widok przewoźnika lub dostawcy. Jeśli źródło opublikowało nowy skan po wysłaniu żądania API, różnica między tymi widokami nie dowodzi, że wcześniejsze żądanie zakończyło się niepowodzeniem.
3. Sprawdź dane zdarzenia, a nie tylko główny status
Porównaj opis najnowszego zdarzenia, lokalizację, status lub kod przewoźnika oraz wszelkie istotne pola dostawy z rekordem źródłowym. Znormalizowany status, taki jak „w transporcie”, może podsumowywać kilka odrębnych skanów. Jeśli aplikacja przechowuje tylko podsumowanie, może wyglądać na niezmienioną, mimo że pojawiło się nowe zdarzenie.
Sprawdź surową odpowiedź API lub zachowane ciało webhooka, jeśli zezwalają na to zasady przetwarzania danych. Następnie prześledź zdarzenie przez analizowanie, mapowanie pól, utrwalanie i prezentację. Szukaj pól null zastępowanych wartościami domyślnymi, nieoczekiwanych kodów statusu trafiających do kategorii ogólnej, obcinania tekstu lub interfejsu użytkownika wyświetlającego tylko wybrane typy zdarzeń. Rozbieżność etykiety statusu różni się od brakującego zdarzenia: wskazuje raczej na logikę transformacji lub wyświetlania niż na problem z dostarczeniem.
Nie wnioskuj o dostarczeniu wyłącznie na podstawie tego, że lokalizacja lub status brzmią jak końcowe. Potwierdź konkretne zdarzenie i pola, od których zależy proces. Z drugiej strony niezmieniony status wysokiego poziomu nie dowodzi, że synchronizacja została zatrzymana; nowo otrzymany skan może zostać przypisany do tej samej kategorii. Rekord diagnostyczny powinien zachowywać zarówno zdarzenie źródłowe, jak i wartość wyświetlaną użytkownikom.
4. Prześledź, jak zdarzenie dotarło do aplikacji
Jeśli używasz webhooków, sprawdź dziennik odbioru dotyczący danej przesyłki i zdarzenia. Zweryfikuj, czy punkt końcowy zaakceptował żądanie, czy wiadomość przeszła walidację oraz czy przetwarzanie dalszych etapów zostało zakończone. Pomyślna odpowiedź HTTP z punktu końcowego nie dowodzi, że późniejszy worker kolejki zapisał zdarzenie. Jeśli przetwarzanie jest asynchroniczne, przeanalizuj zarówno żądanie przychodzące, jak i wynik zadania.
Jeśli odpytywasz API, sprawdź ostatnie zakończone żądanie, identyfikator przesyłki w tym żądaniu, jego odpowiedź oraz wszelką paginację lub logikę pobierania używaną przez integrację. Po pomyślnym żądaniu nadal może nastąpić nieudany zapis do bazy danych lub odczyt nieaktualnej pamięci podręcznej. Skorzystaj z odpowiedniej dokumentacji dostawcy, aby zweryfikować rzeczywiste pola odpowiedzi, wymagania uwierzytelniania i sposób dostarczania danych dla swojej integracji, zamiast zakładać, że każde API śledzenia działa według tego samego kontraktu. W przypadku integracji z 17TRACK odpowiednimi punktami wyjścia są jego strona Tracking API oraz dokumentacja API; potwierdź udokumentowane działanie używanego punktu końcowego i metody.
Spraw, aby przetwarzanie zdarzeń można było bezpiecznie powtarzać. Ponowienie próby nie powinno tworzyć zduplikowanych skanów, wielokrotnie wysyłać tego samego powiadomienia klienta ani zastępować nowszego zapisanego stanu starszym ładunkiem. Właściwy klucz duplikatu zależy od pól faktycznie dostarczanych przez dostawcę. Przetestuj wybrany klucz na różnych zdarzeniach, które przypadkowo mają ten sam status lub sygnaturę czasową; nie powinny być scalane tylko dlatego, że wyglądają podobnie.
5. Zweryfikuj reguły kolejności i przejść stanów
Posortuj zapisane zdarzenia według jasno określonej reguły, a następnie sprawdź wynik. Wiele aplikacji musi rozróżniać „najnowsze zdarzenie, które wystąpiło” od „najnowszego zdarzenia, które otrzymaliśmy”. Opóźniony wcześniejszy skan może nadejść po nowszym skanie. Jeśli baza danych po prostu uznaje ostatnio przetworzoną wiadomość za bieżący stan przesyłki, taki opóźniony skan może cofnąć wyświetlany status.
Porównaj przechowywaną historię z historią źródłową, a nie tylko pojedyncze pole statusu. Sprawdź, czy nowo otrzymany rekord został dodany, odrzucony jako duplikat czy dopuszczony do aktualizacji bieżącego stanu. Zweryfikuj wszelkie reguły nadające określonym zdarzeniom pierwszeństwo przed innymi. Taka reguła może być zamierzona, ale nie powinna ukrywać zdarzenia źródłowego ani sugerować, że przewoźnik cofnął kamień milowy, gdy aplikacja po prostu późno otrzymała starszy skan.
W ramach praktycznego testu wybierz przesyłkę z więcej niż jednym zdarzeniem i odtwórz jej wiadomości w innej kolejności nadejścia w środowisku nieprodukcyjnym. Potwierdź, że historia zdarzeń pozostaje kompletna, a status widoczny dla klienta jest zgodny z udokumentowaną regułą. Pozwala to wykryć błędy kolejności, których nie ujawni zwykły test z wiadomościami przychodzącymi w prawidłowej kolejności.
6. Zmierz aktualność danych i uzgodnij wyjątki
Na koniec porównaj, co wiedziała każda warstwa w tym samym punkcie obserwacji: widok przewoźnika, odpowiedź dostawcy śledzenia, przychodzący webhook lub wynik odpytywania, rekord w bazie danych oraz dane wyświetlane klientowi. Oznacz pierwszą warstwę, na której oczekiwane zdarzenie znika. Ta granica jest bardziej użyteczna niż ogólny raport, że „śledzenie jest opóźnione”.
Zmierz zarówno wiek najnowszego zdarzenia zgłoszonego przez przewoźnika, jak i czas od ostatniego pomyślnego sprawdzenia lub otrzymania danych przez integrację. Odpowiadają one na różne pytania. Paczka może nie mieć nowego skanu przewoźnika, mimo że integracja działa prawidłowo; z drugiej strony przewoźnik może pokazywać nowy skan, podczas gdy ostatnie pomyślne żądanie jest stare. Używaj progów alertów odzwierciedlających własne wymagania operacyjne i zaobserwowane zachowanie. Nie obiecuj klientom stałego interwału aktualizacji, jeśli uzgodnienia z przewoźnikiem i dostawcą tego nie zapewniają.
Utwórz niewielką kolejkę uzgodnień dla przesyłek, których rekordy różnią się od wybranego źródła porównawczego. Uwzględnij identyfikatory, brakujące lub niezgodne zdarzenie, istotne sygnatury czasowe, pierwszą zawodzącą warstwę oraz następne działanie. Na przykład zdarzenie obecne w odpowiedzi dostawcy, ale nieobecne w bazie danych, wymaga zbadania integracji. Zdarzenie obecne w bazie danych, ale nieobecne na stronie śledzenia, wymaga sprawdzenia wyświetlania lub pamięci podręcznej. Jeśli sam przewoźnik nie pokazuje nowego skanu, kolejne żądanie API nie może go stworzyć.
Test operacyjny jest prosty: czy potrafisz zidentyfikować tę samą przesyłkę, znaleźć jej najnowsze znane zdarzenie źródłowe i prześledzić je aż do widoku skierowanego do użytkownika bez zmiany jego znaczenia? Jeśli nie, sześć kontroli zawęża problem do konkretnej granicy i daje zespołowi uzasadniony kolejny krok.
FAQ
Czy pomyślna odpowiedź webhooka oznacza, że najnowsze zdarzenie zostało zsynchronizowane?
Nie. Pokazuje, że punkt końcowy zwrócił pomyślną odpowiedź na żądanie. Potwierdź również pomyślne zakończenie walidacji, przetwarzania kolejki, zapisu w bazie danych i wyświetlania. Sprawdź dane żądania, aby ustalić, jakie zdarzenie zawierało.
Dlaczego strona przewoźnika pokazuje nowszy skan niż moja odpowiedź API?
Najpierw potwierdź, że oglądasz tę samą paczkę i że obie obserwacje wykonano w porównywalnych momentach. Publikacja informacji przez przewoźnika oraz otrzymanie lub udostępnienie zdarzenia przez dostawcę śledzenia mogą nastąpić w różnym czasie. Jeśli różnica się utrzymuje, skorzystaj z dokumentacji dostawcy i jego procesu wsparcia, aby zbadać konkretną przesyłkę, zamiast zakładać gwarancję aktualizacji.
Czy do wyboru najnowszego statusu powinienem użyć sygnatury czasowej zdarzenia czy czasu jego otrzymania przez system?
Stosuj udokumentowaną regułę odpowiednią dla procesu i zachowuj obie wartości. Sygnatura czasowa zdarzenia opisuje moment wystąpienia zgłoszonej aktywności; czas otrzymania opisuje moment, w którym system się o niej dowiedział. Żadne z tych pól nie rozwiązuje samodzielnie każdego przypadku, szczególnie gdy czasy źródłowe są niejednoznaczne lub wcześniejsze skany przychodzą z opóźnieniem.
Co zrobić, jeśli status API się nie zmienił, ale lista zdarzeń zawiera nowy wpis?
Może to być oczekiwane, jeśli wiele zdarzeń przewoźnika jest mapowanych na jeden znormalizowany status. Porównaj szczegóły zdarzenia i sprawdź, czy aplikacja zapisała oraz wyświetla nowy wpis we właściwym miejscu. Traktuj brakujące zdarzenie i niezmienioną etykietę podsumowania jako różne problemy.
Źródła
- 17TRACK Tracking API — materiał referencyjny dotyczący integracji z API śledzenia.
- Dokumentacja API 17TRACK — punkt odniesienia przy sprawdzaniu właściwego kontraktu integracji.
- RFC 3339: Date and Time on the Internet: Timestamps — materiał referencyjny dotyczący formatu sygnatur czasowych i przesunięcia UTC.


