Skip to main content
StartBlogPrzewodnikiTestowanie integracji Tracking API w środowisku deweloperskim: sandbox, numery testowe, mockowane webhooki

Testowanie integracji Tracking API w środowisku deweloperskim: sandbox, numery testowe, mockowane webhooki

17TRACK

Aby przetestować integrację z API śledzenia w środowisku deweloperskim, zastosuj trzy uzupełniające się metody: piaskownicę dostawcy lub udokumentowane numery testowe do sprawdzania działania API, lokalne dane testowe do powtarzalnych scenariuszy przesyłek oraz symulowane webhooki dla punktu końcowego odbierającego dane. Następnie wykonaj kontrolowany test na żywo, aby zweryfikować elementy, których symulacje nie mogą potwierdzić, w tym dane uwierzytelniające, konfigurację subskrypcji i rzeczywiste dostarczanie zdarzeń.

Testowanie integracji API śledzenia w środowisku deweloperskim — piaskownica i numery testowe

Niniejszy przewodnik jest przeznaczony dla deweloperów integrujących śledzenie przesyłek z platformą e-commerce, systemem zarządzania zamówieniami, ERP lub usługą powiadomień dla klientów. Celem nie jest jedynie otrzymanie pomyślnej odpowiedzi API. Należy potwierdzić, że aktualizacje śledzenia generują prawidłowy stan zamówienia bez zduplikowanych wiadomości, utraconych zdarzeń ani przypadkowego kontaktu z rzeczywistymi klientami.

Oddziel działanie dostawcy od działania aplikacji

Integracja śledzenia ma co najmniej dwie granice: żądania wysyłane przez aplikację do dostawcy oraz aktualizacje odbierane lub pobierane później przez aplikację. Pomyślne żądanie na pierwszej granicy nie potwierdza, że druga granica działa.

Zbuduj plan testów wokół tych granic, zamiast oczekiwać, że jeden testowy numer śledzenia przetestuje cały system.

Metoda testowaniaCo może zweryfikowaćCzego sama nie może potwierdzić
Piaskownica dostawcyObsługiwane formaty żądań, uwierzytelnianie i symulowane działanie opisane przez dostawcęDostępność danych przewoźników produkcyjnych ani sposób dostarczania danych w środowisku produkcyjnym
Udokumentowane numery testoweOkreślone scenariusze przypisane do tych numerówInne statusy, przewoźników ani sekwencje webhooków
Lokalne dane testowe i mocki APIParser, reguły mapowania, utrwalanie danych i obsługę błędówCzy rzeczywisty dostawca akceptuje żądania lub wysyła taki sam ładunek danych
Symulowane żądania webhookówObsługę punktu końcowego, walidację, deduplikację i skutki dla kolejnych systemówKonfigurację wywołań zwrotnych po stronie dostawcy ani rzeczywiste ponowienia dostarczenia
Kontrolowany test na żywoRzeczywistą łączność i zaobserwowany przebieg obsługi przesyłkiKażdy rzadki błąd, wyjątek lub sekwencję dostarczenia

Zalecane podejście: zapewnij deterministyczność testów lokalnych, korzystaj z testów obsługiwanych przez dostawcę, jeśli są dostępne, a przesyłki na żywo wykorzystuj wyłącznie do potwierdzenia połączenia między systemami.

Potwierdź umowę z dostawcą przed utworzeniem danych testowych

Rozpocznij od oficjalnej dokumentacji wersji API, której zamierzasz używać. Potwierdź podstawowy URL, metodę uwierzytelniania, wymagania rejestracyjne, schemat odpowiedzi, konfigurację webhooków oraz wszelkie udokumentowane funkcje testowe. Nie zakładaj, że istnieje osobna piaskownica tylko dlatego, że dostawca oferuje API.

W przypadku integracji z 17TRACK skorzystaj ze strony 17TRACK Tracking API oraz oficjalnej dokumentacji API jako punktów wyjścia. Przed utworzeniem przykładów zależnych od dostawcy zweryfikuj tam odpowiednie specyfikacje żądań i wywołań zwrotnych. Poniższe przykłady są celowo danymi testowymi należącymi do aplikacji, a nie odwzorowaniem schematu API 17TRACK.

Przed podłączeniem kodu deweloperskiego do zewnętrznego konta rozstrzygnij następujące kwestie:

  • Czy dane uwierzytelniające środowiska deweloperskiego i produkcyjnego są oddzielne oraz do którego środowiska zapewniają dostęp?
  • Czy piaskownica obsługuje wywołania zwrotne, czy tylko testowanie żądanie–odpowiedź?
  • Czy numery testowe są udokumentowane i jakie dokładnie wyniki generują?
  • Czy rejestracje lub inne żądania testowe mogą zużywać limit konta albo tworzyć trwałe rekordy?
  • Jakie zasady uwierzytelniania wywołań zwrotnych, potwierdzania odbioru, limitów czasu i ponawiania są udokumentowane?
  • Jakie identyfikatory łączą rejestrację śledzenia, przesyłkę, przewoźnika i zdarzenie wywołania zwrotnego?

Jeśli działanie funkcji testowych nie jest jasno udokumentowane, poproś dostawcę o potwierdzenie. W międzyczasie kontynuuj testowanie własnej logiki przetwarzania za pomocą mocków. Niepotwierdzona funkcja piaskownicy jest niepewnością planistyczną, a nie dowodem na jej brak po stronie dostawcy.

Zbuduj odizolowane środowisko deweloperskie

Użyj oddzielnej bazy danych lub odizolowanego dzierżawcy, osobnych sekretów i syntetycznych zamówień. Kieruj wiadomości e-mail, SMS i inne powiadomienia do miejsc testowych lub przechwytywacza powiadomień. Przesyłka oznaczona jako dostarczona w danych testowych nie może powodować wysłania wiadomości do rzeczywistego kupującego.

Dodaj wyraźny znacznik środowiska do rekordów wewnętrznych i dzienników. Przechowuj dane uwierzytelniające dostawcy na serwerze, poza systemem kontroli wersji, i usuwaj sekrety z przechwyconych żądań. Jeśli do obsługi wywołań zwrotnych potrzebny jest tymczasowy dostęp publiczny, udostępnij wyłącznie przeznaczoną do tego trasę deweloperską i zachowaj jej mechanizmy uwierzytelniania.

Przed wysłaniem zdarzeń utwórz niewielki zestaw znanych zamówień. Uwzględnij dwie przesyłki przypisane do jednego zamówienia oraz, jeśli aplikacja to obsługuje, ten sam ciąg numeru śledzenia w kontekście różnych przewoźników. Przypadki te ujawniają założenia, zgodnie z którymi sam numer śledzenia zawsze identyfikuje unikatowy rekord biznesowy.

Z góry określ oczekiwany efekt każdego testu: stan przesyłki, powiązanie z zamówieniem, wpisy na osi czasu, liczbę powiadomień i rekord audytowy. Dzięki temu demonstracja staje się asercją, która może zakończyć się powodzeniem lub niepowodzeniem.

Używaj numerów testowych wyłącznie zgodnie z ich udokumentowanym przeznaczeniem

Numer śledzenia ma dwie odrębne role testowe. Może być danymi wejściowymi służącymi do sprawdzenia rejestracji, a także identyfikować przesyłkę generującą zdarzenia śledzenia. Numer, który przechodzi walidację formatu, nie musi zapewniać użytecznej historii zdarzeń.

Gdy dostępne są oficjalne numery testowe

Zapisz scenariusz określony przez dostawcę obok każdego numeru. Nie należy zakładać, że numer udokumentowany dla dostarczonej przesyłki symuluje wyjątek, zwrot lub nieudaną próbę doręczenia. Sprawdź również, czy wynik jest stały, zmienia się w czasie lub wymaga wyboru konkretnego przewoźnika.

Przechowuj te numery w dedykowanej konfiguracji testów integracyjnych. Nie rozprowadzaj ich w testach jednostkowych, ponieważ zmiana zewnętrznego działania może sprawić, że w innym przypadku deterministyczne testy staną się niewiarygodne.

Gdy oficjalne numery testowe nie są potwierdzone

Używaj syntetycznych identyfikatorów we własnej aplikacji i symuluj granicę dostawcy. Nigdy nie wymyślaj wiarygodnie wyglądającego numeru i nie zakładaj, że jest zarezerwowany do testów — może odpowiadać rzeczywistej przesyłce.

Do walidacji na żywo używaj przesyłek, nad którymi masz kontrolę i do których uzyskania dostępu jesteś upoważniony. Unikaj kopiowania numerów śledzenia z publicznych zrzutów ekranu lub rozmów z klientami. Traktuj historię przesyłek jako potencjalnie wrażliwą, ponieważ może zawierać lokalizacje, znaczniki czasu i informacje o doręczeniu.

Starsza dostarczona przesyłka może pomóc w sprawdzeniu parsowania, ale jest słabą zależnością dla ciągłej integracji. Dostępność danych historycznych i odpowiedź zewnętrzna mogą się zmienić. Zachowaj oczyszczone dane testowe do powtarzalnych testów, a kontrolę na żywo przeprowadzaj osobno.

Twórz dane testowe wokół istotnych zmian stanu przesyłki

Twórz dane testowe na podstawie udokumentowanego schematu oraz, jeśli są dostępne, oczyszczonych rzeczywistych odpowiedzi. Przechowuj dane testowe ładunków dostawcy oddzielnie od wewnętrznego znormalizowanego modelu zdarzeń. Testuj adapter między nimi, aby wewnętrzny mock nie ukrywał uszkodzonego parsera dostawcy.

Przydatny zestaw początkowy obejmuje następujące scenariusze:

  • Brak zdarzeń śledzenia: zachowaj przesyłkę bez twierdzenia, że jest w ruchu lub została dostarczona.
  • W transporcie: zaktualizuj oś czasu i zachowaj prawidłowe powiązanie z zamówieniem.
  • Wydana do doręczenia: zastosuj zasady powiadomień bez uznawania doręczenia za zakończone.
  • Dostarczona: zarejestruj zakończenie i wykonaj zamierzoną czynność biznesową tylko raz.
  • Wyjątek lub próba doręczenia: zachowaj rozróżnienie względem zakończonego doręczenia.
  • Ruch zwrotny: unikaj interpretowania każdego późniejszego skanu jako postępu w kierunku pierwotnego odbiorcy.
  • Nieznany status: zachowaj wystarczającą ilość informacji do diagnozy bez wymyślania mapowania statusu.

Używaj własnych znormalizowanych nazw tych scenariuszy, a następnie jawnie mapuj na nie udokumentowane wartości dostawcy. Nie zakładaj, że różne API używają tych samych etykiet statusu ani że dana etykieta ma wszędzie identyczne znaczenie biznesowe.

Zmieniaj również strukturę danych: pusta lista zdarzeń, brakujące pola opcjonalne, dodatkowe nieznane pola, nazwy lokalizacji zawierające Unicode, znaczniki czasu z przesunięciami strefy czasowej oraz nieprawidłowe wartości wymagane. Parser powinien tolerować zgodne rozszerzenia, odrzucając dane, których nie można bezpiecznie przetworzyć.

Przesyłaj symulowane webhooki przez rzeczywistą ścieżkę odbioru

Symulowany webhook powinien testować trasę odbioru, oprogramowanie pośredniczące uwierzytelniania, walidację, przechowywanie danych i przetwarzanie przez zadania robocze, a nie tylko wywoływać końcową funkcję aktualizacji statusu.

Poniższy ładunek przedstawia syntetyczne zdarzenie wewnętrzne. Nazwy pól, identyfikator zdarzenia i status mają charakter przykładowy; nie stanowią kontraktu wywołania zwrotnego dostawcy.

{
  "event_id": "dev-event-001",
  "shipment_id": "dev-shipment-001",
  "tracking_number": "INTERNAL-TEST-001",
  "status": "in_transit",
  "occurred_at": "2025-01-15T10:00:00Z"
}

Zapisz go jako tracking-event.json i wyślij metodą POST do lokalnego odbiornika testowego:

curl --request POST \
  http://localhost:3000/dev/tracking-events \
  --header 'Content-Type: application/json' \
  --data-binary @tracking-event.json

To polecenie sprawdza wyłącznie lokalne kierowanie i obsługę. Nie demonstruje uwierzytelniania dostawcy. Trasę przeznaczoną wyłącznie dla środowiska deweloperskiego należy zablokować w środowisku produkcyjnym albo przetestować produkcyjny odbiornik przy użyciu udokumentowanej przez dostawcę metody uwierzytelniania i osobnego sekretu testowego.

Testuj uwierzytelnianie bez osłabiania zabezpieczeń produkcyjnych

Jeśli dostawca określa podpisywane wywołania zwrotne, zaimplementuj dokładnie ten schemat zamiast wybierać dowolny nagłówek lub algorytm podpisu. W przypadku schematów podpisujących bajty żądania zachowaj oryginalne ciało do weryfikacji; parsowanie i ponowne serializowanie JSON może zmienić te bajty.

W stosownych przypadkach przetestuj prawidłowe uwierzytelnianie, brak danych uwierzytelniających, zmodyfikowane treści i nieprawidłowe podpisy. Jeśli udokumentowany schemat obejmuje znaczniki czasu lub ochronę przed ponownym odtworzeniem, przetestuj również te zasady. HMAC jest standaryzowaną konstrukcją uwierzytelniania wiadomości, ale jego istnienie nie potwierdza, że korzysta z niego konkretny dostawca śledzenia.

Testuj duplikaty, kolejność i odzyskiwanie

Przetwarzanie przesyłek powinno pozostać prawidłowe, gdy ta sama aktualizacja dociera wielokrotnie lub zdarzenia docierają w nieoczekiwanej kolejności. Są to defensywne scenariusze testowe, a nie twierdzenia dotyczące gwarancji dostarczania konkretnego dostawcy.

TestOczekiwane działanie aplikacji
Wyślij to samo zdarzenie dwukrotnieZachowaj jedno logiczne zdarzenie i unikaj zduplikowanych powiadomień dla klienta.
Wyślij starszy skan tranzytowy po doręczeniuZachowaj użyteczną historię bez automatycznego cofania stanu doręczenia.
Wyślij jednoczesne aktualizacjeStosuj spójne zmiany stanu mimo równoległego działania zadań roboczych.
Przerwij przetwarzanie po trwałym odbiorzeOdzyskaj i przetwórz zapisane zdarzenie bez wymagania nowego wywołania zwrotnego.
Awaria zapisu przed trwałym odbioremNie potwierdzaj fałszywie pomyślnego przyjęcia.
Wyślij nieznaną przesyłkęStosuj określoną zasadę kwarantanny lub odrzucenia; nigdy nie zgaduj powiązania z zamówieniem.

Gdy jest dostarczany, preferuj udokumentowany, stabilny identyfikator zdarzenia do deduplikacji. W przeciwnym razie zdefiniuj starannie ograniczoną tożsamość na podstawie odpowiednich pól i przetestuj kolizje. Sam numer śledzenia nie jest tożsamością zdarzenia, ponieważ jedna przesyłka może generować wiele prawidłowych aktualizacji.

Oddziel historię zdarzeń od bieżącego obrazu przesyłki. Zachowanie historycznych skanów nie wymaga, aby każdy późno przychodzący skan nadpisywał wyświetlany status. Reguła „użyj najnowszego znacznika czasu” również nie jest kompletna: korekty, przepływy zwrotne i różne znaczenia znaczników czasu wymagają jawnej obsługi.

W przypadku przetwarzania asynchronicznego potwierdzaj odbiór dopiero po dotarciu zdarzenia do trwałego punktu przekazania, takiego jak zatwierdzony rekord skrzynki odbiorczej lub trwała kolejka, zgodnie z architekturą. Przestrzegaj udokumentowanych przez dostawcę wymagań dotyczących potwierdzania odbioru. HTTP definiuje znaczenie kodów statusu, ale harmonogram ponowień konkretnego nadawcy musi wynikać z jego własnego kontraktu.

Wykonaj kontrolowany test na żywo i ustal kryteria wydania

Po przejściu testów deterministycznych zarejestruj autoryzowaną przesyłkę przez rzeczywistą integrację i potwierdź kompletną ścieżkę. Sprawdź, czy dostawca zaakceptował zamierzony rekord, konfiguracja wywołania zwrotnego wskazuje właściwe środowisko oraz czy dane przychodzące są mapowane na oczekiwaną przesyłkę.

Nie wymagaj, aby podczas tego testu na żywo pojawił się każdy status przesyłki. Rzeczywiste przesyłki nie są kontrolowanymi danymi testowymi. Użyj testu na żywo do zweryfikowania łączności i zgodności zaobserwowanego kontraktu; do rzadkich lub destrukcyjnych scenariuszy wykorzystuj dane testowe możliwe do odtworzenia.

Przed wydaniem wymagaj następujących rezultatów:

  • Obsługiwane są udokumentowane odpowiedzi powodzenia i błędów, w tym błędy na poziomie elementów, jeśli API obsługuje operacje zbiorcze.
  • Limity czasu nie uruchamiają bezwarunkowych ponowień tworzenia, gdy pierwsze żądanie mogło już zakończyć się powodzeniem.
  • Zduplikowane zdarzenia nie mogą tworzyć zduplikowanych działań biznesowych.
  • Nieprawidłowe wywołania zwrotne nie mogą zmieniać stanu przesyłki.
  • Błędy zadań roboczych pozostawiają zdarzenia możliwe do odzyskania zamiast cicho je gubić.
  • Ruch deweloperski nie może powiadamiać rzeczywistych klientów ani modyfikować zamówień produkcyjnych.
  • Dzienniki łączą żądania, odebrane zdarzenia, wyniki przetwarzania i próby wysłania powiadomień bez ujawniania sekretów.

Wydanie jest gotowe, gdy potrafisz wyjaśnić zarówno normalny przebieg, jak i sposób odzyskiwania systemu po niepewnym żądaniu, powtórzonym wywołaniu zwrotnym lub przerwaniu pracy zadania. Pojedyncze pomyślne wyszukanie przesyłki to za mało.

FAQ

Czy mogę przetestować integrację śledzenia bez piaskownicy?

Tak. Zasymuluj granicę wychodzącego API, odtwórz udokumentowane dane testowe wywołań zwrotnych oraz lokalnie przetestuj normalizację i reguły biznesowe. Następnie użyj autoryzowanej przesyłki na żywo, aby potwierdzić rzeczywistą łączność. Zapewnia to znaczne pokrycie, ale nie odtwarza nieudokumentowanego działania dostawcy.

Dlaczego moje żądanie śledzenia kończy się powodzeniem, ale nie zwraca żadnych zdarzeń?

Akceptacja żądania i dostępność danych śledzenia to różne rezultaty. Sprawdź szczegóły odpowiedzi dostawcy, wymagania rejestracyjne, zasady identyfikacji przewoźnika oraz udokumentowane działanie w przypadku przesyłek bez zdarzeń. Nie twórz informacji o ruchu ani doręczeniu, aby wypełnić pustą oś czasu.

Czy pomyślny symulowany webhook potwierdza, że rzeczywiste webhooki dotrą?

Nie. Potwierdza wyłącznie ścieżkę przetestowaną przez mock. Rzeczywiste dostarczanie zależy również od konfiguracji dostawcy, publicznej dostępności, TLS, uwierzytelniania i rzeczywistego kontraktu wywołania zwrotnego. Zweryfikuj je za pomocą obsługiwanego przez dostawcę testowego dostarczenia lub autoryzowanego przepływu na żywo.

Czy powinienem zwrócić HTTP 200 przed zakończeniem przetwarzania?

Postępuj zgodnie z udokumentowanym kontraktem potwierdzania odbioru dostawcy. W projekcie asynchronicznym potwierdź odbiór po trwałym przyjęciu, a następnie przetwarzaj dane w zadaniu roboczym. Zwrócenie powodzenia przed trwałym przyjęciem może spowodować utratę zdarzenia, jeśli proces natychmiast potem ulegnie awarii.

Jak powinienem testować powiadomienia dla klientów?

Wszystkie powiadomienia deweloperskie kieruj do kontrolowanego przechwytywacza. Sprawdzaj miejsce docelowe, szablon, wywołującą zmianę i liczbę wysyłek. Odtwórz to samo zdarzenie i zasymuluj ponowienia zadań roboczych, aby zweryfikować, że jedna aktualizacja przesyłki nie generuje wielokrotnych wiadomości dla klienta.

Źródła

  • 17TRACK Tracking API — oficjalny punkt wyjścia dla produktu tracking API.
  • Dokumentacja API 17TRACK — odniesienie dla specyficznego dla dostawcy kontraktu integracji; potwierdź tutaj odpowiednie wymagania dotyczące testowania i wywołań zwrotnych.
  • RFC 9110: Semantyka HTTP — semantyka odpowiedzi HTTP i kwestie związane z ponawianiem żądań.
  • RFC 2104: HMAC — standaryzowana konstrukcja uwierzytelniania wiadomości omówiona w wytycznych dotyczących bezpieczeństwa wywołań zwrotnych.