Przebieg działania interfejsu API śledzenia przesyłek: od rejestracji przesyłki do pobierania szczegółów śledzenia
Przepływ pracy interfejsu API do śledzenia przesyłek rozpoczyna się od przesłania numeru śledzenia i wszelkich wymaganych informacji o przewoźniku, sprawdzenia, czy rejestracja zakończyła się powodzeniem, umożliwienia udostępnienia danych śledzenia oraz pobrania statusu przesyłki i historii zdarzeń. W przypadku integracji produkcyjnej deweloperzy muszą również powiązać każdy rekord śledzenia z zamówieniem, obsługiwać częściowe niepowodzenia, bezpiecznie przetwarzać aktualizacje oraz odróżniać zaakceptowaną rejestrację od rzeczywistego skanu przewoźnika.
Ten przewodnik wyjaśnia ten przepływ pracy deweloperom łączącym platformę e-commerce, system zarządzania zamówieniami, aplikację magazynową lub narzędzie obsługi klienta. Oddziela zalecenia dotyczące projektowania aplikacji od wymagań specyficznych dla danego dostawcy. W przypadku integracji z 17TRACK użyj oficjalnej dokumentacji API, aby przed implementacją poniższych przykładów potwierdzić schemat żądania, uwierzytelnianie, obsługiwane operacje i pola odpowiedzi.
Dowiedz się, co rejestracja robi — a czego nie robi
Rejestracja przesyłki w usłudze śledzenia oznacza przesłanie identyfikatora, aby usługa mogła śledzić tę przesyłkę lub zarządzać nią zgodnie z umową dotyczącą jej API. Nie jest to ta sama operacja co zakup opłaty pocztowej, wygenerowanie etykiety wysyłkowej, rezerwacja odbioru lub przekazanie paczki przewoźnikowi.
W aplikacji rozdziel trzy wyniki:
- Żądanie odebrane: API zwróciło odpowiedź na żądanie HTTP.
- Rejestracja zaakceptowana: Usługa zaakceptowała pojedynczy rekord śledzenia do przetwarzania.
- Informacje o śledzeniu dostępne: Usługa posiada informacje o przesyłce, które aplikacja może pobrać lub otrzymać.
Tych wyników nie należy łączyć w pojedynczą flagę „sukcesu”. Zaakceptowany numer śledzenia może jeszcze nie mieć żadnych zdarzeń przewoźnika. Podobnie pomyślna odpowiedź HTTP na żądanie zbiorcze nie oznacza, że każdy element partii został zaakceptowany; sprawdź strukturę wyniku na poziomie aplikacji zdefiniowaną przez dostawcę.
1. Przygotuj identyfikator przesyłki i konfigurację API
Przed wysłaniem żądania rejestracji zdecyduj, w jaki sposób przesyłka będzie identyfikowana w Twoim systemie. Sam identyfikator zamówienia zwykle nie wystarcza, ponieważ jedno zamówienie może zostać podzielone na kilka paczek. Nadaj każdej przesyłce lub paczce własny rekord wewnętrzny i powiąż go z odpowiednim zamówieniem.
Przydatny rekord wewnętrzny zawiera następujące informacje. Są to sugerowane pola aplikacji, a nie schemat żądania 17TRACK.
- Wewnętrzny identyfikator przesyłki: Stały identyfikator paczki.
- Numer zamówienia: Zamówienie lub rekord realizacji, do którego należy przesyłka.
- Numer śledzenia: Identyfikator nadany przez przewoźnika, przechowywany jako tekst w celu zachowania zer wiodących.
- Informacje o przewoźniku: Tożsamość przewoźnika przekazana przez system realizacji zamówień, jeśli jest znana.
- Identyfikator dostawcy: Dowolny identyfikator zwrócony przez usługę śledzenia, wymagany przy późniejszych operacjach.
- Stan rejestracji: Informacja, czy przesłanie oczekuje, zostało zaakceptowane, odrzucone lub oczekuje na uzgodnienie.
- Stan śledzenia: Najnowszy status przesyłki, utrzymywany niezależnie od stanu rejestracji.
Sprawdź dane wejściowe przed przesłaniem. Usuń przypadkowe spacje wokół wartości, ale nie przepisuj numeru śledzenia na podstawie założeń dotyczących formatu przewoźnika. Zachowaj pierwotną wartość na potrzeby rozwiązywania problemów. Jeśli przewoźnik jest znany, przypisz mu udokumentowany identyfikator dostawcy zamiast wysyłać nieformalną nazwę wyświetlaną użytkownikowi.
Konfiguruj uwierzytelnianie po stronie serwera. Przechowuj dane uwierzytelniające poza systemem kontroli wersji, oddziel konfigurację programistyczną od produkcyjnej i usuwaj sekrety z dzienników. Potwierdź udokumentowaną wersję API, limity żądań, limity partii i wymagania dotyczące konta, zamiast przejmować wartości z niepowiązanej integracji.
2. Zarejestruj przesyłkę i zapisz wynik dla każdego elementu
Prześlij rekord śledzenia, korzystając z operacji rejestracji opisanej w dokumentacji dostawcy. Uwzględnij tylko wymagane pola i opcjonalne informacje, które mają określony cel. Unikaj wysyłania imion i nazwisk klientów, adresów lub innych danych osobowych tylko dlatego, że są dostępne w bazie zamówień.
Poniższy pseudokod ilustruje sekwencję aplikacji. Nazwy funkcji są przykładowe; nie są punktami końcowymi API ani metodami SDK.
shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)
result = tracking_adapter.register(shipment)
if result.item_accepted:
save_registration_result(shipment_id, result)
elif result.outcome_unknown:
schedule_registration_reconciliation(shipment_id)
else:
save_registration_error(shipment_id, result)
route_for_retry_or_correction(result)
Zapisz wystarczająco dużo informacji, aby wyjaśnić, co się wydarzyło: wewnętrzny identyfikator przesyłki, czas przesłania, numer próby, wynik na poziomie elementu oraz ewentualny identyfikator żądania dostawcy. Nie polegaj wyłącznie na tymczasowym dzienniku procesu roboczego. Zespoły obsługi klienta i operacyjne potrzebują trwałej odpowiedzi na pytanie, czy przesyłka została pomyślnie zarejestrowana.
Obsługuj przesyłanie zbiorcze indywidualnie
Jeśli API obsługuje rejestrację zbiorczą, powiąż każdy zwrócony element z pierwotną przesyłką. Nie oznaczaj całej partii jako zaakceptowanej tylko dlatego, że żądanie HTTP zakończyło się powodzeniem. Zapisz zaakceptowane elementy, odizoluj odrzucone i osobno zbadaj niejednoznaczne wyniki.
Zapobiega to sytuacji, w której jeden nieprawidłowy numer śledzenia powoduje niepotrzebne ponowienie prób dla rekordów, które już się powiodły. Zapewnia również pracownikom operacyjnym listę rekordów wymagających korekty.
Traktuj przekroczenia czasu jako nieznany wynik
Przekroczenie czasu nie dowodzi, że rejestracja się nie powiodła. Dostawca mógł zaakceptować żądanie, zanim połączenie zostało przerwane. Przed bezrefleksyjnym ponownym przesłaniem użyj udokumentowanego mechanizmu idempotencji, obsługi duplikatów lub operacji wyszukiwania, aby uzgodnić wynik.
Jeśli sposób obsługi duplikatów przez dostawcę jest niejasny, przetestuj go na kontrolowanych rekordach i potwierdź warunki przed włączeniem automatycznych ponowień. Wewnętrzne usuwanie duplikatów zadań rejestracji jest nadal przydatne, ale nie zastępuje zrozumienia, jak zdalna usługa obsługuje powtarzające się żądania.
3. Poczekaj na pojawienie się pierwszych informacji o śledzeniu
Po zaakceptowaniu rejestracji szczegóły śledzenia mogą nie być od razu dostępne. Etykieta może istnieć, zanim przewoźnik zarejestruje fizyczne zdarzenie związane z obsługą. Brakujące informacje mogą również wymagać sprawdzenia numeru śledzenia, wyboru przewoźnika lub wymagań dotyczących wyszukiwania konkretnej przesyłki.
Przedstaw ten stan w sposób jednoznaczny. „Zarejestrowano; oczekiwanie na informacje o śledzeniu” jest dokładniejsze niż „W transporcie” lub „Rejestracja nie powiodła się”. Nie wymyślaj szacowanego terminu dostawy ani zdarzenia dotyczącego przemieszczania się, aby wypełnić pusty interfejs.
Gdy rekord pozostaje pusty, przeprowadź analizę w praktycznej kolejności:
- Potwierdź, że rejestracja pojedynczego elementu została zaakceptowana.
- Porównaj przesłany numer śledzenia z rekordem realizacji zamówienia.
- Sprawdź mapowanie przewoźnika i wszelkie udokumentowane dodatkowe wymagania dotyczące wyszukiwania.
- Sprawdź własną stronę śledzenia przewoźnika dla tej samej przesyłki.
- Jeśli przewoźnik ma zdarzenia, ale Twoja integracja ich nie ma, przeanalizuj odpowiedzi pobierania i skontaktuj się z dostawcą API, przekazując zanonimizowane informacje diagnostyczne.
Unikaj przyjmowania uniwersalnego czasu oczekiwania bez potwierdzenia. Zasady eskalacji powinny uwzględniać usługę wysyłkową, oczekiwany proces przekazania oraz własne zobowiązania operacyjne.
4. Pobierz szczegóły śledzenia i właściwie je zinterpretuj
Gdy rekord jest dostępny, wywołaj udokumentowaną operację pobierania szczegółów śledzenia, używając wymaganych identyfikatorów. Nie zakładaj, że rejestracja i pobieranie akceptują identyczne pola. Niektóre umowy API rozróżniają numery śledzenia, identyfikatory przewoźników i wygenerowane przez dostawcę identyfikatory rekordów.
Aplikacja powinna rozróżniać trzy warstwy informacji:
- Podsumowanie przesyłki: Ogólny stan używany w pulpitach nawigacyjnych, na stronach zamówień i w filtrach operacyjnych.
- Historia zdarzeń: Poszczególne obserwacje, w tym opisy zdarzeń, znaczniki czasu i lokalizacje, jeśli zostały przekazane.
- Metadane pobierania: Informacja, kiedy aplikacja otrzymała lub pobrała dane oraz czy żądanie zakończyło się powodzeniem.
Pomyślne wyszukanie oznacza, że operacja pobierania zakończyła się powodzeniem. Nie oznacza to, że paczka przemieściła się od czasu poprzedniego wyszukania. Przed wygenerowaniem powiadomienia lub uruchomieniem dalszego procesu porównaj zwrócone informacje o śledzeniu z zapisanym rekordem.
Oddziel czas zdarzenia od czasu pobrania
Przechowuj czas związany ze zdarzeniem przewoźnika oddzielnie od czasu, w którym system je otrzymał. Zdarzenie pobrane dziś po południu może opisywać wcześniejszy skan. Zastąpienie czasu zdarzenia czasem pobrania sprawiłoby, że stara aktualizacja wyglądałaby jak nowe fizyczne przemieszczenie.
Zachowaj oryginalny znacznik czasu i wszelkie przekazane przesunięcie. Normalizuj znaczniki czasu na potrzeby porównań tylko wtedy, gdy strefa czasowa jest znana. Jeśli zdarzenie nie zawiera informacji o strefie czasowej, zachowaj tę niepewność zamiast po cichu przypisywać strefę czasową serwera.
Zachowaj pierwotne znaczenie obok znormalizowanego statusu
Znormalizowany status jest przydatny do grupowania przesyłek różnych przewoźników, ale pierwotny opis zdarzenia może dokładniej wyjaśniać problem operacyjny. Zachowaj oba elementy, jeśli są dostępne. Sama ogólna kategoria wyjątku może nie powiedzieć pracownikowi pomocy technicznej, czy kolejnym działaniem powinno być sprawdzenie adresu, skontaktowanie się z odbiorcą czy oczekiwanie na kolejną aktualizację.
Nie wyciągaj wniosków o gwarancji dostawy, potwierdzonej utracie ani konkretnym wyniku odprawy celnej na podstawie niejasnego statusu. Eskaluj sprawę zgodnie z podstawowymi informacjami i zasadami operacyjnymi.
5. Aktualizuj rekordy za pomocą odpytywania lub webhooków
Jednorazowe pobranie szczegółów wystarcza do przetestowania łączności, ale nie wystarcza do utrzymania widoczności przesyłek. Projekt produkcyjny wymaga mechanizmu aktualizacji. Potwierdź mechanizmy obsługiwane przez wybranego dostawcę oraz związane z nimi warunki.
W przypadku odpytywania aplikacja żąda szczegółów śledzenia zgodnie z harmonogramem. Planuj żądania w granicach udokumentowanych limitów, unikaj wielokrotnego odpytywania niezmienionych rekordów bez powodu i stosuj wykładnicze opóźnienie w przypadku błędów możliwych do ponowienia. Otwarcie strony zamówienia przez klienta nie powinno automatycznie uruchamiać nieograniczonego żądania do systemu zewnętrznego; zapisana wersja śledzenia może obsłużyć stronę, podczas gdy kontrolowany proces w tle ją odświeży.
Jeśli używasz webhooków, weryfikuj przychodzące żądania za pomocą udokumentowanego mechanizmu weryfikacji dostawcy. Zapisz zaakceptowane wiadomości lub umieść je w trwałej kolejce przed potwierdzeniem ich odbioru zgodnie z umową webhooka, a następnie przetwarzaj zdarzenia asynchronicznie.
Zaprojektuj odbiornik tak, aby tolerował duplikaty i nieoczekiwaną kolejność nadejścia, chyba że udokumentowana umowa dostawy gwarantuje coś innego. Jeśli jest dostępny, używaj identyfikatora zdarzenia dostawcy do usuwania duplikatów. W przeciwnym razie zdefiniuj i przetestuj odcisk oparty na odpowiednich polach zdarzenia, pamiętając, że taki odcisk może wymagać dostosowania do własnych danych.
Integracja oparta na webhookach może również korzystać z kontrolowanego pobierania w celu uzgadniania danych. Na przykład zadanie odzyskiwania może sprawdzać rekordy, których dotyczyła awaria odbiornika. Jest to wzorzec odporności, a nie zezwolenie na ignorowanie limitów liczby żądań lub wytycznych dostawcy.
6. Przekształcaj informacje o śledzeniu w bezpieczne działania biznesowe
Zaktualizuj wewnętrzny rekord przesyłki przed uruchomieniem działań skierowanych do klienta. Prowadź trwały rejestr powiadomień i przejść między etapami procesu, aby powtórzone zdarzenie nie generowało wielokrotnych wiadomości.
Powiąż działania biznesowe ze znaczącymi zmianami, a nie z każdą odpowiedzią API. Nowo zaobserwowane zdarzenie dostawy może uzasadniać wysłanie powiadomienia o doręczeniu. Powtórzona odpowiedź zawierająca to samo zdarzenie nie powinna go uzasadniać. Wyjątek może wymagać wewnętrznego przeglądu, ale wiadomość do klienta powinna odzwierciedlać faktyczną treść zdarzenia.
Zdefiniuj sposób obsługi zdarzeń otrzymanych po uznaniu przesyłki za zakończoną. Nie usuwaj historii zdarzeń ani nie blokuj na stałe wszystkich późniejszych aktualizacji tylko dlatego, że podsumowanie osiągnęło stan końcowy. Zasady przechowywania, uzgadniania i powiadamiania powinny uwzględniać uzasadnione korekty bez wielokrotnego otwierania zakończonych procesów.
Zastosowanie przepływu pracy w integracji z 17TRACK
W przypadku niestandardowej integracji śledzenia odpowiednimi punktami wyjścia są strona 17TRACK Tracking API oraz dokumentacja dla deweloperów. Użyj strony produktu do oceny oferty, a dokumentacji do ustalenia rzeczywistych warunków integracji. Strony śledzenia dla konsumentów nie zastępują specyfikacji API.
Przed napisaniem adaptera potwierdź format uwierzytelniania, operacje rejestracji i pobierania, zasady identyfikacji przewoźnika, obsługę odpowiedzi na poziomie elementu oraz obowiązujące limity żądań. W przypadku przetwarzania opartego na webhookach potwierdź również schemat danych, proces weryfikacji, wymagania dotyczące potwierdzenia odbioru i sposób ponawiania prób.
Umieść te szczegóły specyficzne dla dostawcy w adapterze, zamiast rozpowszechniać założenia dotyczące pól odpowiedzi w całym systemie zamówień. Dzięki temu pozostała część aplikacji może korzystać z pojęć wewnętrznych, takich jak wynik rejestracji, status przesyłki, historia zdarzeń i ostatnia pomyślna synchronizacja.
Kontrole przed uruchomieniem, które pozwalają uniknąć kosztownych błędów
- Zaakceptowany, ale pusty rekord: Interfejs pokazuje, że informacje o śledzeniu oczekują, a nie że paczka jest w drodze.
- Mieszany wynik partii: Każda przesyłka otrzymuje własny zapisany wynik.
- Przekroczenie czasu po przesłaniu: Proces roboczy uzgadnia niepewny wynik zamiast zakładać niepowodzenie.
- Powtórzone zdarzenie: Oś czasu przesyłki i powiadomienie klienta pozostają pozbawione duplikatów.
- Starsze zdarzenie otrzymane później: Zdarzenie zostaje zachowane bez bezrefleksyjnego zastępowania nowszego podsumowania.
- Niedostępna usługa zewnętrzna: Strona klienta może wyświetlić ostatni zapisany wynik wraz z odpowiednim oznaczeniem aktualności.
- Nieprawidłowe mapowanie przewoźnika: Rekord można poprawić za pomocą udokumentowanej ścieżki odzyskiwania.
- Podzielone zamówienie: Każda paczka zachowuje własny stan śledzenia i historię zdarzeń.
- Ujawnienie danych uwierzytelniających lub ładunku: Dzienniki zawierają odnośniki diagnostyczne bez ujawniania sekretów ani zbędnych danych osobowych.
Praktycznym kryterium ukończenia nie jest samo otrzymanie pomyślnej odpowiedzi rejestracji. Jest nim możliwość prześledzenia paczki od przesłania przez kolejne aktualizacje, wyjaśnienia pustego lub nieudanego wyniku oraz odzyskania sprawności po przerwaniu przetwarzania bez utraty zdarzeń i wielokrotnego uruchamiania działań wobec klientów.
FAQ
Czy rejestracja numeru śledzenia tworzy przesyłkę?
Nie w opisanym tutaj przepływie pracy. Rejestracja śledzenia przesyła istniejący identyfikator do usługi śledzenia. Tworzenie etykiety, zakup opłaty pocztowej i rezerwacja przewoźnika to odrębne operacje, chyba że określone API wyraźnie je łączy.
Dlaczego szczegóły śledzenia są puste po pomyślnej rejestracji?
Akceptacja rejestracji i dostępność danych śledzenia to różne warunki. Przewoźnik mógł jeszcze nie zarejestrować zdarzenia albo może być konieczne sprawdzenie numeru śledzenia, mapowania przewoźnika lub dodatkowych informacji potrzebnych do wyszukania. Sprawdź wynik na poziomie elementu, zanim uznasz rekord za pomyślnie zarejestrowany.
Czy należy rejestrować przesyłkę za każdym razem, gdy pobieram jej status?
Nie używaj wielokrotnej rejestracji jako domyślnego mechanizmu odświeżania. Zapisz zaakceptowany stan rejestracji i korzystaj z udokumentowanego mechanizmu pobierania lub aktualizacji. Przestrzegaj wyraźnych zasad dostawcy dotyczących korekt, ponownej aktywacji lub powtarzających się przesłań.
Czy należy używać odpytywania czy webhooków?
Użyj mechanizmu, który pasuje do udokumentowanej umowy API i wymagań operacyjnych. Odpytywanie wymaga kontrolowanego harmonogramu żądań. Webhooki wymagają bezpiecznego, trwałego odbiornika i przetwarzania odpornego na duplikaty. Jeśli są obsługiwane, aktualizacje webhooków wraz z ukierunkowanym uzgadnianiem mogą zapewnić praktyczną ścieżkę odzyskiwania.
Czy mogę używać numeru śledzenia jako jedynego identyfikatora przesyłki w bazie danych?
Zamiast tego użyj wewnętrznego identyfikatora przesyłki. Przechowuj numer śledzenia i odpowiedni kontekst przewoźnika jako atrybuty tego rekordu. Ułatwia to obsługę podzielonych zamówień, poprawionych numerów śledzenia i odwołań specyficznych dla dostawcy bez zmiany tożsamości wewnętrznej przesyłki.
Źródła
- 17TRACK Tracking API — oficjalny punkt wejścia do oceny integracji z API 17TRACK.
- Dokumentacja API 17TRACK — oficjalne źródło informacji o specyficznych dla implementacji formatach żądań, operacjach, odpowiedziach i wymaganiach integracyjnych. Pseudokod i sugerowane pola wewnętrzne w tym przewodniku to przykłady projektowania aplikacji, a nie cytaty z warunków tego API.


