Skip to main content
StartBlogPrzewodnikiJak połączyć dane śledzenia przesyłek z systemem Oms: mapowanie zamówień i reguły synchronizacji

Jak połączyć dane śledzenia przesyłek z systemem Oms: mapowanie zamówień i reguły synchronizacji

17TRACK

Aby połączyć dane śledzenia przesyłek z systemem zarządzania zamówieniami (OMS), przypisz każdą śledzoną paczkę do wewnętrznego rekordu przesyłki, a następnie połącz tę przesyłkę z zamówieniem i pozycjami realizacji. Odbieraj aktualizacje śledzenia za pośrednictwem interfejsu obsługiwanego przez dostawcę, zachowuj oryginalne zdarzenia i stosuj jednoznaczne zasady dotyczące duplikatów, opóźnionych aktualizacji, statusu przesyłki i finalizacji zamówienia. Nie używaj samego numeru śledzenia jako identyfikatora zamówienia ani nie pozwalaj, aby pojedyncze zdarzenie doręczenia automatycznie zamykało zamówienie składające się z wielu paczek.

Jak połączyć dane śledzenia przesyłek z zamówieniem w systemie OMS

Ten przewodnik jest przeznaczony dla inżynierów integracji i zespołów operacyjnych e-commerce wdrażających takie połączenie. Zalecany projekt oddziela obserwacje przewoźnika od decyzji biznesowych: dane śledzenia opisują podróż paczki, natomiast OMS decyduje, co ta podróż oznacza dla realizacji, komunikacji z klientem i zamknięcia zamówienia.

Określ, który system jest właścicielem każdego rekordu

Przed utworzeniem połączenia API uzgodnij zakres odpowiedzialności z administratorem OMS, zespołem realizacji i zespołem obsługi klienta. W przeciwnym razie nawet technicznie poprawna integracja może nadpisać prawidłowe dane biznesowe.

  • OMS: Jest właścicielem zamówień, pozycji zamówień, wymaganych ilości, anulowań oraz zasad finalizacji zamówień.
  • System realizacji: Jest właścicielem tworzonych przez siebie rekordów przesyłek lub paczek, w tym przydziałów pakowania i przypisań etykiet. Może to być sam OMS lub oddzielny system magazynowy.
  • Dostawca śledzenia: Dostarcza obserwacje dotyczące śledzenia oraz klasyfikacje statusów określone przez dostawcę.
  • Warstwa integracji: Jest właścicielem powiązań identyfikatorów, przetwarzania zdarzeń, normalizacji, obsługi ponowień oraz rekordów audytowych synchronizacji.

Traktuj te zasady jako zalecane granice odpowiedzialności, a nie założenia dotyczące Twojego oprogramowania. Udokumentuj wyjątki. Na przykład jeśli magazyn może wymienić etykietę wysyłkową, integracja potrzebuje jednoznacznej aktualizacji z tego systemu, zamiast zgadywać, że nowo zaobserwowany numer zastępuje stary.

Zbuduj mapowanie zamówienie–paczka przed synchronizacją statusów

Praktyczna relacja to zamówienie → realizacja → paczka → przypisanie śledzenia. Twój OMS może używać innych nazw lub łączyć niektóre z tych rekordów. Zachowaj relacje nawet wtedy, gdy struktura bazy danych jest inna.

Zamówienie może mieć kilka realizacji, a realizacja może obejmować kilka paczek. Paczka może również otrzymać zastępcze przypisanie śledzenia lub powiązany identyfikator ostatniego etapu dostawy. Te identyfikatory nie powinny tworzyć dodatkowych zamówionych ilości.

RekordZalecane polaCel
ZamówienieIdentyfikator dzierżawy lub sklepu, niezmienny identyfikator zamówienia OMSOddziela sprzedawców i zapobiega zależności od wyświetlanych numerów zamówień.
RealizacjaIdentyfikator realizacji, identyfikator zamówienia, identyfikatory i ilości przydzielonych pozycjiOkreśla, które zakupione produkty są realizowane.
PaczkaWewnętrzny identyfikator paczki, identyfikator realizacji, przydziały paczki, jeśli są dostępneZapewnia stabilną tożsamość niezależną od etykiet śledzenia.
Przypisanie śledzeniaIdentyfikator przypisania, identyfikator paczki, konto dostawcy, identyfikator przewoźnika, numer śledzenia, okres aktywnościŁączy przychodzące obserwacje śledzenia z właściwą paczką i cyklem życia przypisania.

Dopasowuj aktualizacje za pomocą zapisanego powiązania

Podczas tworzenia przesyłki zapisz jej wewnętrzne identyfikatory przed zarejestrowaniem jej do śledzenia. Zapisz każdy identyfikator rekordu śledzenia nadany przez dostawcę, zwrócony w udokumentowanym procesie rejestracji. Jeśli dostawca obsługuje referencję sprzedawcy, użyj nieprzejrzystej referencji wewnętrznej i zachowaj lokalne mapowanie.

W przypadku przychodzących aktualizacji najpierw rozwiąż zapisany identyfikator rekordu dostawcy w ramach właściwego konta dostawcy i dzierżawy. Jeśli ten identyfikator jest niedostępny, użyj udokumentowanej kombinacji numeru śledzenia, tożsamości przewoźnika, kontekstu konta i historii przypisań. Traktuj to jako strategię wyszukiwania, a nie gwarancję globalnej unikalności tej kombinacji.

Nie dopasowuj danych na podstawie imienia i nazwiska klienta, adresu e-mail ani nieoznaczonego zakresem numeru wyświetlanego zamówienia. Przechowuj numery śledzenia jako ciągi znaków, aby zachować zera wiodące. Unikaj usuwania znaków lub zmiany wielkości liter, chyba że odpowiednia umowa z przewoźnikiem lub dostawcą zezwala na taką normalizację.

Jeśli wyszukiwanie nie zwróci żadnego dopasowania lub zwróci kilka możliwych dopasowań, odizoluj aktualizację do zbadania. Nierozwiązane zdarzenie jest bezpieczniejsze niż pewna aktualizacja niewłaściwego zamówienia klienta.

Obsługuj zamówienia częściowe bez wymyślania przydziałów paczek

Rozważ przykładowe zamówienie zawierające trzy sztuki. Paczka A zawiera dwie sztuki, a paczka B jedną. Doręczenie paczki A oznacza, że istnieją dowody doręczenia dwóch sztuk; nie oznacza, że doręczono całe zamówienie.

Jeśli system realizacji rejestruje tylko fakt, że obie paczki należą do tej samej realizacji, nie wymyślaj przydziałów na poziomie sztuk. Nadal możesz obliczyć, czy wszystkie wymagane paczki zostały doręczone, ale raportowanie doręczenia na poziomie produktu powinno pozostać niedostępne lub wyraźnie niepewne do czasu uzyskania danych o przydziale.

Połącz API śledzenia za pomocą trwałej warstwy pozyskiwania danych

Użyj potoku, który oddziela komunikację z dostawcą od zapisów w OMS:

Tworzenie przesyłki → rejestracja śledzenia → przychodząca aktualizacja lub zaplanowane pobieranie → trwałe przechowywanie zdarzeń → mapowanie i normalizacja → aktualizacja OMS → uzgadnianie

W przypadku wdrożenia 17TRACK odpowiednimi punktami wyjścia są strona produktu Tracking API oraz oficjalna dokumentacja API. Przed wdrożeniem adaptera potwierdź właściwy interfejs rejestracji, identyfikatory przewoźników, opcje dostarczania aktualizacji, wymagania uwierzytelniania, definicje statusów i limity konta. Model danych w tym przewodniku jest zaleceniem dotyczącym integracji, a nie twierdzeniem, że 17TRACK używa tych nazw pól lub zapewnia natywne połączenie z Twoim OMS.

Jeśli wybrany dostawca obsługuje webhooki, uwierzytelniaj przychodzące żądania za pomocą udokumentowanego mechanizmu i trwale zapisuj zaakceptowane wiadomości przed ich potwierdzeniem. Umieść powolne operacje OMS poza ścieżką żądania. Stosuj rzeczywisty kontrakt dostawcy dotyczący potwierdzeń i ponowień, zamiast zakładać określone ciało odpowiedzi lub limit czasu.

Jeśli wymagane jest odpytywanie, zapisuj postęp pobierania tam, gdzie obsługuje to API, kontroluj współbieżność i przestrzegaj udokumentowanych limitów szybkości. Ani odebranie webhooka, ani pomyślne żądanie odpytywania nie dowodzi, że OMS został zaktualizowany; rejestruj te wyniki oddzielnie.

Zdefiniuj reguły synchronizacji odporne na ponowienia i opóźnione zdarzenia

1. Zapewnij idempotentność przetwarzania

Dwukrotne przetworzenie tej samej obserwacji nie powinno powodować duplikowania przesyłki, podwójnego zwiększania ilości ani ponownego wysyłania tego samego powiadomienia do klienta. HTTP nie zapewnia idempotentności dowolnej operacji POST; integracja musi wdrożyć ochronę przed duplikatami. RFC 9110 wyjaśnia idempotentność metod HTTP.

Używaj stabilnego identyfikatora zdarzenia dostawcy, jeśli jest udokumentowany i dostępny. W przeciwnym razie zdefiniuj odcisk na podstawie identyfikatora przypisania i odpowiednich pól zdarzenia, takich jak znacznik czasu zdarzenia, status źródłowy i lokalizacja. Udokumentuj możliwość kolizji lub zmian opisów zdarzeń. Zachowuj surową obserwację nawet wtedy, gdy nie powoduje ona kolejnej czynności OMS.

Chroń każdy efekt uboczny oddzielnie. Na przykład zapis statusu w OMS i powiadomienie e-mail wymagają własnych mechanizmów deduplikacji. Użyj transakcyjnej skrzynki nadawczej lub równoważnego trwałego rekordu pracy, aby awaria procesu nie pozostawiła zaakceptowanego zdarzenia bez zaplanowanej aktualizacji.

2. Przechowuj osobno czas zdarzenia i czas jego odebrania

Czas wystąpienia zdarzenia i czas jego odebrania przez integrację odpowiadają na różne pytania. Przechowuj oba, wraz z oryginalną reprezentacją znacznika czasu i dostarczonym przesunięciem strefy czasowej. Nie przypisuj po cichu strefy czasowej magazynu do zdarzenia, którego strefa czasowa jest nieznana.

Spóźniony skan przesyłki będącej w transporcie powinien zwykle wzbogacać historię bez zastępowania nowszego statusu doręczenia. Same znaczniki czasu są jednak niewystarczające: dostawca może wydać korektę, a zdarzenia mogą zawierać niepełne informacje o czasie. Jeśli są dostępne, używaj udokumentowanych pól sekwencji lub rewizji oraz jednoznacznej polityki korekt.

3. Normalizuj statusy bez usuwania szczegółów źródłowych

Utwórz niewielki wewnętrzny słownik rozumiany przez OMS, na przykład oczekiwanie na przyjęcie przez przewoźnika, w transporcie, w doręczeniu, doręczono, wyjątek i zwrot. Mapuj na niego udokumentowane statusy dostawcy. Są to sugerowane kategorie wewnętrzne, a nie uniwersalne definicje przewoźników.

Przechowuj oryginalny kod statusu, opis, lokalizację zdarzenia, referencję rekordu dostawcy i wersję reguły mapowania. Nieznana wartość powinna tworzyć warunek wymagający przeglądu, a nie domyślnie otrzymywać statusu doręczono lub niepowodzenie. Utworzenie etykiety nie powinno być traktowane jako dowód fizycznego przyjęcia przesyłki przez przewoźnika, chyba że zdarzenie źródłowe wyraźnie potwierdza taką interpretację.

4. Używaj reguł przejść, a nie prostego rankingu liczbowego

Stany przesyłki nie zawsze tworzą prostą linię. Po wyjątku może nastąpić zwykły transport, a próba doręczenia nie jest doręczeniem. Ruch zwrotny może rozpocząć się po wcześniejszym zdarzeniu doręczenia.

  • Pozwalaj na usunięcie wyjątku, gdy kolejne dowody potwierdzają wznowienie transportu.
  • Uniemożliwiaj zwykłemu historycznemu skanowi ciche zastąpienie statusu doręczenia.
  • Pozwalaj na udokumentowaną korektę za pośrednictwem kontrolowanej ścieżki rewizji.
  • Śledź ruch zwrotny oddzielnie od zakończenia wysyłki wychodzącej, jeśli OMS to obsługuje.
  • Kieruj niejednoznaczne lub sprzeczne dowody do kolejki operacyjnej.

Wersjonuj te reguły. Gdy mapowanie się zmieni, zdecyduj, czy ma ono zastosowanie tylko do nowych zdarzeń, czy też rekordy historyczne wymagają kontrolowanego ponownego przeliczenia.

Obliczaj status zamówienia na podstawie wymaganych zobowiązań realizacyjnych

Status paczki i status zamówienia powinny być odrębnymi polami. Paczka oznaczona jako doręczona dostarcza dowodu dotyczącego tej paczki; zakończenie zamówienia zależy od pozostałych wymaganych ilości i polityki biznesowej.

Przydatną wartością domyślną jest oznaczenie zamówienia jako w pełni doręczonego dopiero wtedy, gdy wszystkie ilości wymagające dostawy mają prawidłowe dowody doręczenia na poziomie paczki i nie pozostają nierozwiązane wymagane przydziały. Wyłącz anulowane ilości zgodnie z zasadami anulowania OMS. Obsługuj produkty cyfrowe, zamówienia z odbiorem osobistym i inne zobowiązania niezwiązane z wysyłką za pomocą własnych warunków zakończenia.

Przesyłki zastępcze wymagają jednoznacznych relacji. Jeśli zagubiona paczka zostanie zastąpiona, zdecyduj, czy przesyłka zastępcza zastępuje pierwotne zobowiązanie dostawy. W przeciwnym razie pierwotna paczka może bezterminowo blokować zakończenie, a obie paczki mogą zostać wliczone do realizacji. Zapisz tę decyzję, zamiast wyprowadzać ją wyłącznie ze statusu śledzenia.

Oddziel zakończenie dostawy od zamknięcia finansowego, uprawnień do zwrotu środków i rozstrzygania sporów. Zdarzenie doręczenia przez przewoźnika nie powinno automatycznie uprawniać do zwrotu środków ani rozstrzygać roszczenia klienta.

Odzyskuj sprawność po awariach bez utraty ścieżki audytu

Ponawiaj przejściowe niepowodzenia, stosując ograniczony czas narastania opóźnienia i wszelkie udokumentowane zalecenia dotyczące ponowień. Oddziel tymczasowe awarie połączenia od nieprawidłowych identyfikatorów, wygasłych danych uwierzytelniających, błędów uprawnień i niezgodności schematu. Te ostatnie wymagają działań naprawczych, a nie niekończących się ponowień.

Utrzymuj kolejkę nieudanych prac zawierającą dotkniętą dzierżawę, paczkę, referencję zdarzenia, próbę operacji, klasyfikację błędu i następne działanie. Rejestruj wystarczający kontekst do zbadania problemu, nie kopiując do logów niepotrzebnych danych klienta ani danych uwierzytelniających.

Uruchamiaj uzgadnianie dodatkowo względem zwykłej ścieżki aktualizacji. Przeglądaj aktywne przesyłki z nieaktualnymi informacjami o śledzeniu, zaakceptowane zdarzenia, których zapisy w OMS się nie powiodły, niedopasowane obserwacje oraz różnice między stanem obliczonym przez integrację a stanem OMS. Wybierz częstotliwość przeglądów na podstawie zobowiązań dotyczących dostaw, limitów API i ryzyka operacyjnego, zamiast stosować arbitralny, uniwersalny harmonogram.

Przypisz odpowiedzialność: inżynieria obsługuje pozyskiwanie danych i nieudane zapisy; operacje realizacji rozwiązują brakujące relacje paczek; obsługa klienta przegląda wyjątki wymagające komunikacji z klientem. Kolejka bez przypisanego właściciela jest tylko miejscem przechowywania.

Przetestuj mapowanie i reguły biznesowe przed uruchomieniem

Użyj kontrolowanych danych testowych i ograniczonego wdrożenia produkcyjnego. Przetestuj poniższe przypadki zarówno względem historii zdarzeń, jak i wynikowego rekordu OMS:

  • Zamówienie z jedną paczką przechodzi normalnie do doręczenia.
  • Zamówienie podzielone ma jedną doręczoną paczkę i jedną nadal będącą w transporcie.
  • To samo zdarzenie jest odbierane wielokrotnie bez zduplikowanych efektów ubocznych.
  • Starszy skan przesyłki w transporcie dociera po doręczeniu.
  • Nieznany przewoźnik lub status trafia do kolejki przeglądu.
  • Etykieta zostaje wymieniona bez tworzenia kolejnego zobowiązania realizacyjnego.
  • Przesyłka zastępcza zastępuje pierwotną paczkę zgodnie z zatwierdzoną regułą.
  • OMS jest niedostępny po zaakceptowaniu zdarzenia.
  • Proces uruchamia się ponownie między zapisem w OMS a jego potwierdzeniem.
  • Ten sam wyświetlany numer zamówienia istnieje w dwóch sklepach bez dopasowania między dzierżawami.

Uruchom system, gdy każde zaakceptowane zdarzenie ma możliwy do prześledzenia wynik przetwarzania, niejednoznaczne dopasowania nie mogą automatycznie aktualizować zamówień, a operatorzy mogą bezpiecznie ponawiać nieudane prace. Są to bardziej użyteczne kryteria akceptacji niż samo wykazanie, że żądanie API kończy się powodzeniem.

FAQ

Czy mogę bezpośrednio połączyć numery śledzenia z zamówieniami?

W przypadku ściśle jedno-paczkowego procesu bezpośrednia relacja może początkowo wystarczyć. Mimo to używaj wewnętrznej tożsamości przesyłki między zamówieniem a przypisaniem śledzenia. Zapewnia ona ścieżkę migracji dla przesyłek podzielonych, ponownego etykietowania i przesyłek zastępczych bez zmiany znaczenia rekordu zamówienia.

Czy integracja powinna używać webhooków czy odpytywania?

Użyj mechanizmu dostarczania obsługiwanego przez dostawcę i zgodnego z Twoją infrastrukturą. Webhooki mogą ograniczyć wielokrotne pobieranie, natomiast odpytywanie może obsługiwać procesy oparte na pobieraniu i uzgadnianiu, jeśli jest dostępne. Żadne z tych podejść nie eliminuje potrzeby trwałego przechowywania, obsługi duplikatów i odzyskiwania po awariach.

Co powinno się stać, gdy zdarzenie śledzenia nie ma pasującego zamówienia?

Zapisz je w kolejce niedopasowanych zdarzeń i zbadaj rekord rejestracji, kontekst dzierżawy, tożsamość przewoźnika oraz czas utworzenia przesyłki. Nie twórz automatycznie zamówienia ani nie przypisuj zdarzenia do prawdopodobnego klienta. Ponów jego przetwarzanie po poprawieniu mapowania.

Czy powiadomienia o doręczeniu powinny pochodzić z OMS czy z systemu śledzenia?

Wybierz jednego właściciela dla każdego rodzaju powiadomienia i wyzwalacza. Jeśli dwa systemy mogą wysłać tę samą wiadomość, wyłącz jedną ścieżkę lub współdziel trwały rejestr powiadomień. Zdecyduj również, czy wiadomość dotyczy jednej paczki, czy całego zamówienia, szczególnie w przypadku podzielonej realizacji.

Czy status wyjątku oznacza, że zamówienie nie zostało zrealizowane?

Nie. Wyjątek jest obserwacją wymagającą interpretacji, a niekoniecznie trwałym wynikiem. Zachowaj przyczynę, monitoruj kolejne zdarzenia i użyj polityki eskalacji, aby zdecydować, kiedy operacje powinny zainterweniować.

Źródła

  • 17TRACK Tracking API — oficjalne źródło informacji o produkcie i punkcie wyjścia do integracji API.
  • Dokumentacja API 17TRACK — materiały referencyjne dotyczące kontraktu właściwego dla dostawcy; przed wdrożeniem zweryfikuj odpowiednie interfejsy i wymagania dotyczące konta.
  • RFC 9110, sekcja 9.2.2: Metody idempotentne — semantyka HTTP wspierająca rozróżnienie między idempotentnością metody a ochroną aplikacji przed duplikatami.