Skip to main content
StartBlogPrzewodnikiTwoje pierwsze żądanie do Tracking API: przewodnik po Rest Client z użyciem Postman i Curl

Twoje pierwsze żądanie do Tracking API: przewodnik po Rest Client z użyciem Postman i Curl

17TRACK

Aby wykonać pierwsze żądanie do API śledzenia, skonfiguruj punkt końcowy, nagłówek uwierzytelniania i treść JSON w kliencie REST, wyślij żądanie, a następnie sprawdź zarówno status HTTP, jak i treść odpowiedzi. Ten przewodnik wykorzystuje Tracking API firmy 17TRACK, aby zademonstrować ten sam proces w Postmanie i curl: zarejestruj przesyłkę, pobierz informacje o jej śledzeniu i sprawdź, czy wynik jest gotowy do użycia przez aplikację.

Your First Tracking API Request a Rest Client Walkthrough with

Celem jest mały, powtarzalny test integracyjny, a nie wdrożenie produkcyjne. Potrzebujesz danych uwierzytelniających API oraz numeru śledzenia, który możesz legalnie przetwarzać. Poniższe polecenia wykorzystują wzorzec punktu końcowego v2.2; przed ich uruchomieniem potwierdź wersję punktu końcowego i wymagania dotyczące konta w dokumentacji API 17TRACK.

Zrozum, co powinno osiągnąć Twoje pierwsze żądanie

Integracja śledzenia przesyłek obejmuje dwa odrębne zadania: poinformowanie usługi, którą przesyłkę należy śledzić, oraz pobranie informacji o śledzeniu powiązanych z tą przesyłką. W przedstawionym tutaj procesie są to dwa osobne żądania. Rejestracja nie oznacza, że paczka została już wysłana, a pomyślna rejestracja nie gwarantuje, że zdarzenia przewoźnika będą natychmiast dostępne.

Do pierwszego testu użyj jednej przesyłki zamiast partii. Ułatwi to odizolowanie błędów uwierzytelniania, nieprawidłowych numerów śledzenia i problemów z interpretacją odpowiedzi. Pierwszym użytecznym etapem nie jest samo „otrzymałem HTTP 200”. Jest nim „API zaakceptowało zamierzoną operację, a ja potrafię wyjaśnić wynik dotyczący przesyłki”.

Postman udostępnia wizualny interfejs do edytowania żądań i analizowania odpowiedzi. curl umożliwia odtwarzanie tej samej wymiany HTTP z terminala. Żadne z tych narzędzi nie zmienia zasad uwierzytelniania API, danych przesyłki ani sposobu przetwarzania. Użyj tego, które ułatwia dokładniejsze zbadanie żądania, a następnie odtwórz działającą konfigurację w drugim narzędziu.

Przygotuj dane uwierzytelniające, przesyłkę i szczegóły żądania

Przed otwarciem któregokolwiek z klientów zbierz następujące informacje:

  • Autoryzowane dane uwierzytelniające API: uzyskaj je podczas konfiguracji konta API 17TRACK. Sesja konsumenckiego śledzenia nie zastępuje danych uwierzytelniających API.
  • Rzeczywisty numer śledzenia: użyj przesyłki, której jesteś właścicielem lub do której masz uprawniony dostęp. Niedawno aktywna przesyłka jest zwykle bardziej przydatna niż wymyślony numer podczas testowania rzeczywistych danych śledzenia.
  • Przewoźnik, jeśli jest znany: zachowaj nazwę przewoźnika na potrzeby diagnostyki. Jeśli w Twoim przypadku wymagany jest identyfikator przewoźnika, użyj wartości i pola zdefiniowanych w dokumentacji API, zamiast zgadywać.
  • Aktualny kontrakt żądania: potwierdź wersję API, nagłówek uwierzytelniania, schemat żądania i wszelkie ograniczenia konta.
  • Bezpieczne środowisko pracy: unikaj umieszczania danych uwierzytelniających, informacji klientów lub kompletnych odpowiedzi śledzenia w publicznych repozytoriach, zrzutach ekranu albo udostępnianych wiadomościach do pomocy technicznej.

Minimalne przykłady żądań używają następujących ustawień:

UstawieniePrzykładowa konfiguracja
Podstawowy URLhttps://api.17track.net/track/v2.2
Operacja rejestracjiPOST /register
Operacja pobierania informacji o śledzeniuPOST /gettrackinfo
Nagłówek uwierzytelniania17token: YOUR_API_TOKEN
Format treściContent-Type: application/json, z tablicą JSON obiektów przesyłek

Przechowuj numery śledzenia jako ciągi znaków. Konwersja na typ liczbowy może usunąć początkowe zera lub w inny sposób zmienić wartość. Zastąp znajdujący się poniżej symbol zastępczy YOUR_TRACKING_NUMBER rzeczywistą testową przesyłką; nie jest to działający przykładowy numer.

Wykonaj żądanie rejestracji w Postmanie

1. Utwórz małe środowisko testowe

W Postmanie utwórz środowisko z trzema zmiennymi: base_url, tracking_token i tracking_number. Ustaw base_url na powyższy podstawowy URL, a w pozostałych zmiennych wpisz dane uwierzytelniające i numer przesyłki. Wybierz to środowisko przed wysłaniem żądania.

Używaj dostępnych w Postmanie mechanizmów obsługi poufnych danych dla tokenu i sprawdź, jakie dane udostępnia lub synchronizuje Twoje środowisko pracy. Ukrycie wartości w interfejsie nie zastępuje kontroli nad tym, kto może uzyskać do niej dostęp. Nie eksportuj uzupełnionych danych uwierzytelniających wraz z kolekcją przeznaczoną dla współpracowników lub do publicznej dokumentacji.

2. Skonfiguruj metodę, URL i nagłówki

Utwórz żądanie HTTP, wybierz POST i wprowadź {{base_url}}/register jako URL. Na karcie Headers dodaj:

17token: {{tracking_token}}
Content-Type: application/json

W tym przykładzie dane uwierzytelniające należy umieścić w niestandardowym nagłówku 17token. Nie zastępuj go konfiguracją tokenu Bearer tylko dlatego, że inne API używało tego wzorca. Sprawdź również, czy odziedziczone ustawienia kolekcji nie dodają niezamierzonego nagłówka Authorization.

3. Dodaj treść JSON

Otwórz Body, wybierz raw, a następnie JSON. Wprowadź:

[
  {
    "number": "{{tracking_number}}"
  }
]

Zewnętrzne nawiasy kwadratowe mają znaczenie: to żądanie używa tablicy, mimo że zawiera tylko jedną przesyłkę. Używaj podwójnych cudzysłowów, usuń końcowe przecinki i nie umieszczaj komentarzy w JSON. Jeśli dokumentacja wymaga dodatkowych informacji dotyczących przewoźnika lub przesyłki, dodaj udokumentowane pola przed wysłaniem.

4. Wyślij żądanie i przeanalizuj wynik

Kliknij Send. Najpierw sprawdź, czy w ogóle otrzymano odpowiedź HTTP. Błąd DNS, TLS, problem z serwerem proxy lub przekroczenie limitu czasu różnią się od odpowiedzi wyjaśniającej, że żądanie było nieprawidłowe. Następnie przeanalizuj treść odpowiedzi pod kątem wyniku operacji oraz informacji o zaakceptowaniu lub odrzuceniu przesyłki.

Zapisz żądanie jako „Register test shipment”. Zapisz status HTTP, wynik API i wszelkie komunikaty o błędach, nie kopiując tokenu. Jeśli rejestracja się nie powiedzie, rozwiąż ten problem przed przejściem dalej. Wielokrotne wysyłanie niezmienionego żądania utrudnia diagnostykę i może zużywać zasoby konta.

Odtwórz żądanie za pomocą curl

Poniższe polecenia używają powłoki w stylu POSIX, takiej jak Bash lub Zsh. PowerShell i Windows Command Prompt mają inne zasady dotyczące cudzysłowów i zmiennych. W PowerShell, w razie potrzeby, użyj curl.exe, aby wywołać plik wykonywalny curl zamiast aliasu polecenia właściwego dla powłoki.

Ustaw podstawowy URL i załaduj dane uwierzytelniające do zmiennej środowiskowej zgodnie ze swoim standardowym procesem obsługi sekretów:

export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.

Zmienna środowiskowa usuwa dane uwierzytelniające z przykładu przeznaczonego do ponownego użycia, ale nie jest kompletnym systemem zarządzania sekretami. Podczas lokalnych testów unikaj wpisywania prawdziwego tokenu do polecenia, które zostanie zachowane w historii powłoki. W automatyzacji używaj magazynu sekretów platformy i ograniczaj dane zapisywane w logach.

Utwórz plik o nazwie shipment.json i zastąp symbol zastępczy testowym numerem śledzenia:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Wyślij żądanie rejestracji:

curl --request POST \
  --url "$TRACKING_BASE_URL/register" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output register-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Spowoduje to zapisanie treści odpowiedzi w pliku register-response.json i wyświetlenie statusu HTTP osobno. Limity czasu połączenia i całkowitego wykonania są ustawieniami lokalnego testu, a nie gwarancjami usługi 17TRACK. Otwórz zapisany plik, aby przeanalizować wynik API; sama linia statusu jest niewystarczająca.

curl może pomyślnie zakończyć transfer, nawet gdy serwer zwróci odpowiedź HTTP z błędem. Z drugiej strony błąd transportu może uniemożliwić otrzymanie użytecznej odpowiedzi API. W skryptach traktuj kod wyjścia curl, status HTTP i wynik na poziomie aplikacji jako odrębne sygnały.

Pobierz informacje o śledzeniu przesyłki

Po potwierdzeniu rejestracji zduplikuj żądanie w Postmanie i zmień URL na {{base_url}}/gettrackinfo. Zachowaj metodę POST, nagłówek uwierzytelniania, typ treści i treść przesyłki. Zapisz je osobno, aby przypadkowo nie zarejestrować przesyłki ponownie, gdy zamierzasz pobrać dane.

Równoważne żądanie curl wygląda następująco:

curl --request POST \
  --url "$TRACKING_BASE_URL/gettrackinfo" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output tracking-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Nie zakładaj, że nowo zarejestrowana przesyłka natychmiast zwróci kompletną historię zdarzeń. Dostępność danych zależy od przesyłki i przetwarzania przez usługę. Jeśli informacje nie są jeszcze dostępne, postępuj zgodnie z udokumentowanymi wskazówkami dotyczącymi pobierania i aktualizacji, zamiast wielokrotnie rejestrować ten sam numer lub uruchamiać zbyt intensywną pętlę odpytywania.

Czytaj odpowiedź na trzech poziomach

  1. Transport: czy klient nawiązał połączenie i otrzymał odpowiedź HTTP?
  2. Operacja: czy API zaakceptowało żądanie i czy poszczególna przesyłka została pomyślnie przetworzona?
  3. Informacje o przesyłce: czy zwrócone dane identyfikują właściwą paczkę i co faktycznie potwierdza jej status lub historia zdarzeń?

Użyj oficjalnego schematu odpowiedzi, aby znaleźć pola statusu, przewoźnika i zdarzeń. Zachowaj rozróżnienie między znormalizowanym statusem przesyłki a oryginalnym opisem zdarzenia przewoźnika. Pomyślne wyszukanie nie jest dowodem dostawy, a brak zdarzeń nie jest dowodem zagubienia paczki.

Podczas przechowywania znaczników czasu zachowaj podane informacje o strefie czasowej lub przesunięciu. Unikaj sortowania surowych ciągów dat w różnych formatach i zakładania, że tworzą prawidłową sekwencję chronologiczną. Rozróżniaj również czas pobrania rekordu przez aplikację od czasu wystąpienia zdarzenia przesyłki.

Rozwiązuj problemy, nie zmieniając wszystkiego naraz

  • Brak odpowiedzi: sprawdź nazwę hosta, dostęp do sieci, ustawienia serwera proxy, konfigurację TLS i lokalny limit czasu. Nie wyłączaj rutynowo weryfikacji certyfikatu jako rozwiązania.
  • Błąd uwierzytelniania: potwierdź, że token jest aktywny, nagłówek 17token jest obecny, a wybrane środowisko Postmana prawidłowo rozwiązuje zmienną. Sprawdź przypadkowe białe znaki.
  • Nieprawidłowe żądanie: zweryfikuj wersję API, ścieżkę operacji, metodę POST, typ treści i strukturę tablicy JSON w dokumentacji.
  • Odrzucona przesyłka: odczytaj błąd dotyczący konkretnej przesyłki. Sprawdź numer i wymagane informacje o przewoźniku, zamiast traktować każde odrzucenie jako problem z uwierzytelnianiem.
  • Brak zdarzeń śledzenia: potwierdź rejestrację i tożsamość właściwej przesyłki. Sprawdź, czy potrzebne są informacje o przewoźniku i czy aktualizacje są dostępne przed ponowną próbą.
  • Postman działa, ale curl nie: porównaj rozwiązany URL, rzeczywiste nagłówki i bajty treści. Cudzysłowy powłoki oraz nieustawione zmienne środowiskowe często powodują rozbieżności między żądaniami.

Zmieniaj jedną zmienną na test i prowadź krótką dokumentację wyników. Jeśli sprawdzasz konsolę Postmana lub używasz szczegółowego wyjścia curl, traktuj je jako poufne: nagłówki żądania mogą ujawniać dane uwierzytelniające. Usuń sekrety i informacje klientów przed udostępnieniem diagnostyki.

Dowiedz się, kiedy przewodnik jest ukończony

Wykonałeś wartościowy pierwszy test integracyjny, gdy oba klienty wysyłają zamierzone żądanie, rejestracja jest zrozumiała, pobieranie zwraca możliwy do zinterpretowania wynik, a Ty potrafisz odróżnić błąd API od przesyłki bez nowych informacji. Same zgodne kody statusu HTTP nie dowodzą, że oba klienty działały identycznie.

Przed przeniesieniem procesu do aplikacji przechowuj dane uwierzytelniające na serwerze, waliduj dane wejściowe i stosuj ustrukturyzowaną obsługę błędów. Zapoznaj się z udokumentowanymi limitami szybkości, limitami partii, wskazówkami dotyczącymi ponawiania oraz opcjami dostarczania aktualizacji dla Twojego konta. Nie zakładaj, że po przekroczeniu limitu czasu można bez zastanowienia ponowić rejestrację: serwer mógł przetworzyć żądanie, mimo że klient nie otrzymał odpowiedzi.

Dodaj testy dla nieprawidłowych danych uwierzytelniających, niepoprawnego JSON, nieprawidłowego numeru przesyłki, już zarejestrowanej przesyłki, niedostępnych danych śledzenia i przekroczenia limitu czasu sieci. Każdy przypadek powinien prowadzić do zamierzonego rezultatu aplikacji, a nie do nieobsłużonego wyjątku lub mylącego statusu widocznego dla klienta.

FAQ

Czy mogę testować bez prawdziwego numeru śledzenia?

Możesz przetestować niektóre zachowania walidacji żądania przy użyciu nieprawidłowej wartości, ale nie zweryfikuje to śledzenia przesyłki. Aby testować rzeczywiste zdarzenia, użyj autoryzowanej przesyłki lub udokumentowanego urządzenia testowego, jeśli usługa je udostępnia. Nie zakładaj, że dowolne przykładowe numery należą do środowiska sandbox.

Dlaczego odpowiedź HTTP 200 nadal zawiera błąd?

Status HTTP i wyniki aplikacji opisują różne poziomy. Serwer może pomyślnie odebrać i przetworzyć żądanie, jednocześnie informując, że pojedyncza przesyłka została odrzucona. Czytaj treść odpowiedzi i udokumentowany wynik dotyczący przesyłki, a nie tylko status HTTP.

Dlaczego do pobierania informacji o śledzeniu używa się POST?

Używaj metody określonej w kontrakcie punktu końcowego. Ten przykład pobierania przyjmuje identyfikatory przesyłek w treści żądania JSON za pośrednictwem POST. Zmiana na GET tylko dlatego, że operacja odczytuje dane, nie zachowuje udokumentowanego żądania.

Czy powinienem umieścić token API w JavaScript przeglądarki?

Nie umieszczaj prywatnych danych uwierzytelniających API w publicznie dostarczanym kodzie frontendowym. Kieruj żądania przez autoryzowany backend, który chroni dane uwierzytelniające, sprawdza dane wejściowe i kontroluje, do jakich informacji o przesyłkach może uzyskać dostęp każdy użytkownik.

Czy do produkcji potrzebuję zarówno Postmana, jak i curl?

Nie. Są to przydatne narzędzia testowe i diagnostyczne. Aplikacja produkcyjna może używać odpowiedniego klienta HTTP. Zachowaj oczyszczone żądanie Postmana lub polecenie curl jako powtarzalny punkt odniesienia, bez aktywnego tokenu i zbędnych danych klientów.

Źródła