Skip to main content
StartBlogPrzewodnikiJak korzystać z interfejsów API do śledzenia przesyłek, aby wysyłać proaktywne powiadomienia o dostawie

Jak korzystać z interfejsów API do śledzenia przesyłek, aby wysyłać proaktywne powiadomienia o dostawie

17TRACK

Aby wysyłać proaktywne powiadomienia o dostawie za pomocą API śledzenia przesyłek, połącz każdą paczkę z jej zamówieniem, pobieraj aktualizacje śledzenia, przekształcaj je w zdarzenia istotne dla klienta i uruchamiaj wiadomości za pośrednictwem usługi e-mail, SMS lub powiadomień w aplikacji. Umieść trwałą kolejkę oraz mechanizmy sprawdzania duplikatów między przychodzącymi danymi śledzenia a wysyłanymi wiadomościami, aby powtarzające się lub opóźnione aktualizacje nie powodowały mylących alertów.

Jak używać interfejsów API śledzenia przesyłek do wysyłania proaktywnych powiadomień o dostawie

Ten przewodnik jest przeznaczony dla programistów i zespołów operacyjnych e-commerce tworzących taki przepływ pracy. Celem nie jest przekazywanie każdego skanu przewoźnika. Chodzi o informowanie klientów, gdy zmienia się coś istotnego, wyjaśnianie znaczenia tej zmiany oraz wskazywanie, czy muszą podjąć działanie.

Zaprojektuj przepływ powiadomień przed podłączeniem API

API śledzenia przesyłek dostarcza informacji o śledzeniu, ale to aplikacja decyduje, jak je wykorzystać. Traktuj widoczność przesyłki i komunikację z klientem jako odrębne zadania, nawet jeśli wybrana usługa oferuje obie funkcje.

Praktyczna architektura składa się z sześciu etapów:

  1. Powiązanie z zamówieniem: w razie potrzeby połącz numer śledzenia i identyfikator przewoźnika z wewnętrznym rekordem przesyłki.
  2. Rejestracja śledzenia: prześlij lub zarejestruj przesyłkę zgodnie z wymaganiami integracyjnymi dostawcy.
  3. Pobieranie aktualizacji: odbieraj wywołania zwrotne webhooków, pobieraj aktualizacje za pomocą żądań API albo łącz oba podejścia.
  4. Przetwarzanie zdarzeń: sprawdzaj poprawność, normalizuj, usuwaj duplikaty i oceniaj przychodzące zdarzenia.
  5. Decyzja o powiadomieniu: wybierz, czy wysłać powiadomienie, z kim się skontaktować oraz którego kanału i szablonu użyć.
  6. Dostarczenie wiadomości: wyślij powiadomienie i zapisz odpowiedź usługi komunikacyjnej.

Przechowuj dane kontaktowe klientów we własnym systemie zamówień lub wiadomości, chyba że integracja rzeczywiście wymaga ich udostępnienia. Usługa śledzenia zazwyczaj nie potrzebuje adresu e-mail klienta tylko po to, aby aplikacja mogła powiązać zdarzenie śledzenia z zamówieniem.

1. Potwierdź umowę integracyjną

Przed napisaniem odbiornika sprawdź w dokumentacji dostawcy informacje dotyczące uwierzytelniania, rejestracji przesyłek, identyfikacji przewoźnika, obsługiwanych metod aktualizacji, formatów odpowiedzi, limitów żądań i obsługi błędów. W przypadku integracji webhooków sprawdź także sposób uwierzytelniania wywołań zwrotnych, odpowiedź potwierdzającą odbiór oraz sposób obsługi nieudanych dostarczeń.

W przypadku implementacji 17TRACK zacznij od strony Tracking API 17TRACK i jej oficjalnej dokumentacji API. W integracji korzystaj z udokumentowanej umowy, zamiast traktować przykładowe nazwy pól z tego przewodnika jako pola żądań lub odpowiedzi 17TRACK. Przed implementacją potwierdź konfigurację wywołań zwrotnych, wymagania bezpieczeństwa i limity właściwe dla konta.

Wybierz metodę aktualizacji zgodnie z umową integracyjną:

  • Webhooki: używaj wywołań zwrotnych, gdy są obsługiwane i odpowiednie dla Twojej infrastruktury. Pozwalają aplikacji przetwarzać aktualizacje, gdy dostawca je wysyła, bez wielokrotnego żądania informacji o tej samej przesyłce.
  • Odpytywanie: pobieraj informacje o śledzeniu według harmonogramu, gdy wywołania zwrotne są niedostępne lub nieodpowiednie. Utrzymuj harmonogram w granicach udokumentowanych limitów żądań.
  • Podejście łączone: używaj wywołań zwrotnych do normalnego przetwarzania oraz wybiórczego pobierania danych przez API w celu uzgadniania przesyłek, których aktualizacje wydają się nieaktualne, jeśli dostawca obsługuje taki przepływ pracy.

Nie obiecuj klientom natychmiastowych powiadomień tylko dlatego, że używasz webhooków. Aplikacja nie może zgłosić zdarzenia przewoźnika, zanim dane śledzenia ze źródła nadrzędnego nie udostępnią takiej informacji.

2. Zbuduj rekord przesyłki odporny na rzeczywiste zamówienia

Używaj wewnętrznego identyfikatora przesyłki jako głównego odwołania, a nie samego numeru śledzenia. Zamówienie może zawierać kilka paczek, a numery śledzenia nie powinny być uznawane za globalnie unikalne na zawsze.

Przydatny rekord wewnętrzny obejmuje:

  • Wewnętrzny identyfikator zamówienia i przesyłki.
  • Numer śledzenia i identyfikator przewoźnika, jeśli są znane.
  • Referencję przesyłki u dostawcy, jeśli została podana.
  • Bieżący znormalizowany status i najnowsze istotne zdarzenie.
  • Czas zdarzenia u przewoźnika, wraz ze strefą czasową lub przesunięciem, jeśli są dostępne.
  • Czas odebrania aktualizacji przez system.
  • Odwołanie do preferencji komunikacyjnych klienta.
  • Historię powiadomień i wszelkie aktywne procedury obsługi wyjątków.

Przechowuj czas zdarzenia oddzielnie od czasu odbioru. Skan wykonany wcześniej może nadejść po nowszym skanie. Jeśli aplikacja sortuje dane wyłącznie według kolejności nadejścia, może błędnie zmienić status dostarczonej przesyłki z powrotem na „w transporcie”.

W przypadku zamówień podzielonych powiąż powiadomienia z właściwą paczką. „Jedna paczka z Twojego zamówienia dotarła” jest dokładniejsze niż „Twoje zamówienie dotarło”, gdy inna paczka jest nadal w drodze.

3. Mapuj zdarzenia śledzenia na decyzje klienta

Opisy przewoźnika są danymi operacyjnymi, a nie gotowymi komunikatami dla klientów. Zbuduj warstwę normalizacji, która zachowa oryginalne zdarzenie i przypisze mu jednocześnie wewnętrzną kategorię zrozumiałą dla reguł powiadomień.

Poniższe kategorie to sugerowane pojęcia aplikacyjne, a nie uniwersalny słownik statusów API:

Kategoria wewnętrznaDecyzja dotycząca powiadomieniaGranica komunikatu
Otrzymano informacje o przesyłceWyślij aktualizację dotyczącą przygotowania tylko wtedy, gdy jest przydatna.Nie sugeruj, że przewoźnik fizycznie posiada przesyłkę wyłącznie na podstawie utworzenia etykiety.
W transporcieRozważ powiadomienie przy pierwszym istotnym przemieszczeniu.Pomijaj rutynowe skany obiektów, chyba że zmieniają kolejny krok klienta.
Wydano do doręczeniaPowiadom, gdy obsługiwane zdarzenie wskazuje ten status.Nie przedstawiaj statusu jako gwarantowanej godziny doręczenia.
Próba doręczenia lub wymagany odbiórWyślij powiadomienie wymagające działania.Uwzględniaj terminy lub instrukcje odbioru tylko wtedy, gdy zostały zweryfikowane.
Wyjątek dotyczący dostawyOceń przyczynę i to, czy klient musi podjąć działanie.Nie opisuj każdego wyjątku jako zagubienia paczki.
DostarczonoWyślij potwierdzenie dotyczące konkretnej paczki.Nie wymyślaj odbiorcy, miejsca doręczenia ani potwierdzenia dostawy.

Zachowuj niepewność. Nierozpoznane zdarzenie powinno trafić do ścieżki weryfikacji lub awaryjnej, zamiast być na siłę przypisywane do najbliższej znanej kategorii. Udostępniaj personelowi pomocy technicznej surowy opis na potrzeby rozwiązywania problemów.

4. Odbieraj aktualizacje bez utraty lub duplikowania pracy

Endpoint webhooka powinien zweryfikować żądanie, trwale zapisać zaakceptowaną aktualizację i zwrócić potwierdzenie wymagane przez dostawcę. Generuj wiadomości asynchronicznie, zamiast czekać na usługę e-mail lub SMS podczas żądania wywołania zwrotnego.

Wdroż udokumentowaną przez dostawcę metodę weryfikacji wywołań zwrotnych. Nie wymyślaj nagłówka podpisu ani nie zakładaj, że każdy dostawca używa tego samego schematu uwierzytelniania. Wymuś również HTTPS, limity rozmiaru żądań, walidację danych i odpowiednie mechanizmy kontroli dostępu.

Uproszczony przepływ przetwarzania wygląda następująco. Są to operacje na poziomie aplikacji, a nie działający przykład SDK:

odbierz wywołanie zwrotne
  zweryfikuj żądanie za pomocą udokumentowanego mechanizmu dostawcy
  sprawdź poprawność danych
  trwale zapisz zaakceptowane dane i atomowo dodaj przetwarzanie do kolejki
  zwróć udokumentowane potwierdzenie

przetwórz aktualizację z kolejki
  znajdź wewnętrzną przesyłkę
  znormalizuj istotne zdarzenia
  pomiń zdarzenia już przetworzone
  oceń chronologię i zmianę stanu
  utwórz zadanie powiadomienia, jeśli zasady na to pozwalają
  zatwierdź stan i zadanie razem

wyślij zadanie powiadomienia
  sprawdź preferencje odbiorcy i reguły wyciszania
  przekaż wiadomość do usługi komunikacyjnej
  zapisz wynik i ponów próbę tylko wtedy, gdy jest to właściwe

Etapy atomowe mają znaczenie. Jeśli aplikacja zapisze zmianę statusu, ale ulegnie awarii przed utworzeniem zadania powiadomienia, klient może nigdy nie otrzymać alertu. Jedną z możliwości projektowych jest transakcyjna skrzynka nadawcza: zapisz zmianę stanu i oczekujące zadanie w ramach tej samej transakcji bazy danych, a następnie pozwól pracownikowi wysłać zadanie.

Obsługuj nieznane odwołania do przesyłek w sposób jawny. Umieszczaj je w kwarantannie na potrzeby analizy lub uzgadniania, zamiast zgadywać, który klient powinien otrzymać powiadomienie.

5. Dodaj ochronę przed duplikatami i kontrole chronologii

Zaprojektuj odbiornik tak, aby tolerował powtarzające się wywołania zwrotne i ponowne próby pracowników. Jeśli dostawca udokumentował stabilny identyfikator zdarzenia, używaj go w pierwszej kolejności. W przeciwnym razie utwórz deterministyczny odcisk zdarzenia na podstawie odpowiednich pól, takich jak wewnętrzny identyfikator przesyłki, kod zdarzenia, czas zdarzenia i lokalizacja. Przetestuj ten odcisk na rzeczywistych danych przed poleganiem na nim.

Usuwanie duplikatów zdarzeń i wyciszanie powiadomień rozwiązują różne problemy. Usuwanie duplikatów zapobiega dwukrotnemu przetworzeniu tego samego zdarzenia. Wyciszanie uniemożliwia wygenerowanie zasadniczo tej samej wiadomości dla klienta przez kilka różnych skanów.

Zdefiniuj tożsamość powiadomienia wokół zdarzenia biznesowego. Potwierdzenie dostawy może używać identyfikatora przesyłki i kamienia milowego „dostarczono”. Próba doręczenia może wymagać tożsamości właściwej dla danej próby, ponieważ późniejsza próba może być rzeczywiście nowym zdarzeniem.

W przypadku aktualizacji przychodzących w niewłaściwej kolejności porównuj znaczniki czasu zdarzeń i oceniaj dozwolone przejścia stanów. Nie zakładaj, że wywołanie zwrotne zawiera wyłącznie nowy skan; sprawdź, czy jego udokumentowana struktura przedstawia pojedyncze zdarzenie, migawkę czy historię. Sprzeczne aktualizacje kieruj do uzgadniania, zamiast po cichu odrzucać wszystkie korekty.

6. Pisz wiadomości wyjaśniające, co stanie się dalej

Każde powiadomienie powinno wskazywać właściwą paczkę, potwierdzoną zmianę oraz kolejny krok klienta. Dodaj bezpieczny link do śledzenia i rozpoznawalne odwołanie do zamówienia. Unikaj ujawniania pełnych adresów lub zbędnych danych osobowych w wiadomościach SMS i podglądach na ekranie blokady.

Na przykład:

  • Wydano do doręczenia: „Twoja paczka dotycząca zamówienia {order_reference} jest w doręczeniu. Śledź jej postęp tutaj: {tracking_link}”.
  • Podjęto próbę doręczenia: „Przewoźnik zgłosił próbę doręczenia Twojej paczki. Sprawdź stronę śledzenia, aby poznać dostępne kolejne kroki: {tracking_link}”.
  • Dostarczono: „Przewoźnik oznaczył paczkę dotyczącą zamówienia {order_reference} jako dostarczoną. Wyświetl dostępne szczegóły dostawy: {tracking_link}”.

Renderuj symbole zastępcze wyłącznie na podstawie zweryfikowanych danych. Jeśli dostępny jest termin dostawy i nadaje się do wyświetlenia, oznacz go jako szacunkowy. Jeśli go brakuje, pomiń go zamiast wymyślać datę.

W przypadku wyjątków odróżniaj problem z przesyłką od zadania klienta. Zakłócenie może wymagać jedynie wyjaśnienia, natomiast zweryfikowany problem z adresem może wymagać działania. Nie kieruj klientów na stronę płatności ani przesyłania dokumentów wyłącznie na podstawie niezaufanej treści tekstowej śledzenia.

Wybieraj kanały na podstawie preferencji klienta, uprawnień kanału, pilności i obowiązujących przepisów. Sprawdź wymagania dotyczące zgód, rezygnacji i godzin ciszy dla jurysdykcji oraz kanałów komunikacji, z których korzystasz. Oddzielaj powiadomienia dotyczące dostawy od kampanii promocyjnych, zamiast zakładać, że te same uprawnienia obejmują oba rodzaje komunikacji.

7. Określ, co dzieje się, gdy śledzenie milknie

Proaktywna komunikacja powinna obejmować zarówno brak postępu, jak i nowe zdarzenia, ale sama cisza nie dowodzi, że przesyłka jest opóźniona lub zagubiona.

Utwórz regułę nieaktualnego śledzenia, wykorzystując poziom usługi, trasę, ostatnie istotne zdarzenie i wszelkie obsługiwane szacunkowe terminy dostawy. Ustalaj progi na podstawie danych operacyjnych i procesu obsługi, zamiast stosować jeden uniwersalny czas oczekiwania do każdej przesyłki.

Po uruchomieniu reguły sprawdź, czy nie pominięto przetwarzania, uzgodnij dane ze źródłem śledzenia, jeśli jest to obsługiwane, i zdecyduj, czy utworzyć wewnętrzne zadanie pomocy technicznej. Jeśli powiadomisz klienta, użyj sformułowania odzwierciedlającego stan wiedzy: „Nie otrzymaliśmy nowej aktualizacji śledzenia” różni się od „Twoja paczka zaginęła”.

Przypisz właściciela nierozwiązanym wyjątkom. System powiadomień, który wielokrotnie ogłasza problem bez tworzenia ścieżki do jego rozwiązania, może zwiększać frustrację klientów.

8. Przetestuj całą ścieżkę przed włączeniem automatycznej wysyłki

Najpierw uruchom przepływ w trybie obserwacyjnym: pobieraj rzeczywiste lub zatwierdzone zdarzenia testowe, generuj proponowane powiadomienia i sprawdzaj wyniki bez kontaktowania się z klientami.

  • Odtwórz identyczne wywołanie zwrotne i potwierdź, że nie tworzy kolejnej wiadomości.
  • Przetwórz starsze zdarzenie tranzytowe po zdarzeniu „dostarczono” i sprawdź wynikowy stan.
  • Przetestuj brakujące znaczniki czasu, nieznane statusy i nieprawidłowo sformatowane dane.
  • Zasymuluj awarię bazy danych przed potwierdzeniem oraz awarię pracownika po zapisaniu danych.
  • Przetestuj przekroczenia limitu czasu wiadomości, w tym niepewną odpowiedź, gdy usługa mogła już zaakceptować wiadomość.
  • Potwierdź, że przesyłki podzielone generują treści właściwe dla poszczególnych paczek.
  • Sprawdź odbiorców, którzy zrezygnowali z komunikacji, nieprawidłowe dane kontaktowe i obsługę godzin ciszy.
  • Zweryfikuj, że linki śledzenia nie ujawniają informacji o zamówieniu innego klienta.

Monitoruj zaakceptowane wywołania zwrotne, błędy przetwarzania, wiek elementów w kolejce, zadania powiadomień, wyciszanie duplikatów i wyniki komunikacji. Mierz opóźnienie przetwarzania od czasu odebrania przez system oddzielnie od wieku zdarzenia przewoźnika. To rozróżnienie pomaga ustalić, czy opóźnione powiadomienie wynikało z dostępności danych nadrzędnych, czy z własnego potoku.

Zacznij od niewielkiego zestawu dobrze rozumianych kamieni milowych. Rozszerzaj reguły dopiero wtedy, gdy zespoły pomocy technicznej i operacyjne uzgodnią, że wiadomości są dokładne, użyteczne i warte otrzymywania.

Najczęściej zadawane pytania

Czy API śledzenia przesyłek automatycznie wysyła wiadomości e-mail lub SMS?

Niekoniecznie. Dostęp do danych śledzenia i komunikacja z klientem to odrębne funkcje. Sprawdź udokumentowany zakres usługi. W niestandardowej integracji aplikacja może przetwarzać aktualizacje śledzenia i wysyłać powiadomienia za pośrednictwem oddzielnej usługi komunikacyjnej.

Czy powinienem powiadamiać klientów o każdym skanie śledzenia?

Zwykle nie. Priorytetowo traktuj istotne kamienie milowe i zdarzenia wymagające działania. Kilka skanów w obiektach może oznaczać normalny transport bez zmiany informacji, które klient powinien znać. Szczegółową historię przechowuj na stronie śledzenia.

Czy mogę zagwarantować powiadomienia o dostawie w czasie rzeczywistym?

Możesz ustawić i monitorować cel przetwarzania po otrzymaniu aktualizacji przez system. Nie możesz zagwarantować, kiedy przewoźnik zarejestruje lub opublikuje skan. Opisuj usługę w sposób uwzględniający tę zależność.

Jak zapobiec duplikowaniu wiadomości o dostawie?

Używaj trwałego usuwania duplikatów zdarzeń, oddzielnej tożsamości powiadomienia dla każdego biznesowego kamienia milowego oraz transakcyjnego tworzenia zadań. Jeśli usługa komunikacyjna obsługuje idempotencję, wykorzystaj ją jako dodatkowe zabezpieczenie. Samo sprawdzanie duplikatów w pamięci operacyjnej nie przetrwa ponownych uruchomień ani pracy wielu pracowników.

Co powinno się stać, jeśli przewoźnik skoryguje status „dostarczono”?

Zachowaj oba zdarzenia i uzgodnij stan przesyłki. Jeśli korekta ma istotny wpływ na klienta, wyślij jasne sprostowanie lub skieruj sprawę do pomocy technicznej zgodnie z zasadami. Nie uznawaj statusu „dostarczono” za trwale nieodwracalny tylko po to, aby uprościć kod.

Źródła

Poniższe oficjalne zasoby są materiałami referencyjnymi dotyczącymi implementacji integracji 17TRACK omówionej powyżej. Schemat wewnętrzny, reguły powiadomień i przepływ przetwarzania w tym przewodniku to zalecenia architektoniczne, a nie cytowane umowy API.

  • Tracking API 17TRACK — oficjalny punkt wyjścia do oceny integracji API.
  • Dokumentacja API 17TRACK — materiały referencyjne dotyczące formatów żądań właściwych dla dostawcy, uwierzytelniania, operacji śledzenia i wymagań integracyjnych.