Skip to main content
StartBlogPrzewodnikiJak zarejestrować numer śledzenia za pośrednictwem API: pola żądania, kody przewoźników i odpowiedzi

Jak zarejestrować numer śledzenia za pośrednictwem API: pola żądania, kody przewoźników i odpowiedzi

17TRACK

Aby zarejestrować numer przesyłki za pośrednictwem API, wyślij uwierzytelnione żądanie rejestracji zawierające numer śledzenia przesyłki oraz, gdy jest to wymagane, identyfikator przewoźnika. Następnie sprawdź odpowiedź dla każdej przesłanej przesyłki — nie tylko status HTTP — i zapisz, czy rejestracja zakończyła się powodzeniem, niepowodzeniem czy pozostała niepewna. Rejestracja rozpoczyna proces śledzenia; nie potwierdza, że przewoźnik zeskanował paczkę ani że zdarzenia śledzenia są już dostępne.

Jak zarejestrować numer śledzenia za pomocą pól żądania API

Ten przewodnik jest przeznaczony dla deweloperów integrujących system zarządzania zamówieniami, aplikację magazynową lub platformę e-commerce z API śledzenia. Jako konkretny przykład integracji wykorzystuje 17TRACK i wyjaśnia, które szczegóły należy sprawdzić w dokumentacji wybranej wersji API.

Co daje rejestracja — a czego nie zapewnia

Żądanie rejestracji informuje usługę śledzenia, którą przesyłkę ma śledzić. Różni się ono od zakupu etykiety wysyłkowej, zlecenia odbioru lub poproszenia przewoźnika o utworzenie przesyłki. W typowej integracji proces wysyłki najpierw generuje numer śledzenia, a aplikacja rejestruje ten numer później.

W aplikacji rozdziel te trzy zdarzenia:

  • Utworzenie przesyłki: system wysyłkowy przypisał numer śledzenia.
  • Akceptacja rejestracji: usługa śledzenia zaakceptowała przesyłkę do śledzenia.
  • Otrzymanie informacji o śledzeniu: zdarzenia przewoźnika stały się dostępne za pośrednictwem usługi śledzenia.

Nie aktualizuj zamówienia do statusu „w transporcie” tylko dlatego, że rejestracja zakończyła się powodzeniem. Nowo utworzona etykieta może jeszcze nie mieć fizycznego skanu przyjęcia. Status przesyłki widoczny dla klienta powinien wynikać ze zdarzeń śledzenia interpretowanych zgodnie z regułami mapowania statusów, a nie z odpowiedzi rejestracyjnej.

W przypadku integracji z 17TRACK zacznij od przeglądu Tracking API i korzystaj z oficjalnej dokumentacji API jako źródła informacji o punktach końcowych, definicjach pól, uwierzytelnianiu i kodach odpowiedzi. Poniższe przykłady dotyczą rejestracji, a nie oddzielnych zadań pobierania wyników lub otrzymywania aktualizacji.

Przygotuj pola żądania przed napisaniem wywołania API

Najbardziej użyteczne przygotowanie to niewielki kontrakt pól między systemem wysyłkowym a integracją śledzenia. Określ, skąd pochodzi każda wartość, czy może być pominięta i jak będzie walidowana.

Pole lub wartośćPrzeznaczenieReguła implementacji
Numer śledzeniaIdentyfikuje przesyłkę do śledzenia.Przechowuj i przesyłaj jako ciąg znaków; zachowaj początkowe zera.
Identyfikator przewoźnikaIdentyfikuje przewoźnika w systemie dostawcy śledzenia.Używaj identyfikatora udokumentowanego przez dostawcę, a nie wewnętrznego kodu magazynowego.
Wewnętrzny numer referencyjnyŁączy rejestrację z rekordem przesyłki.Jeśli jest dostępne, użyj obsługiwanego pola referencyjnego; niezależnie od tego zachowaj własne mapowanie w bazie danych.
Dodatkowe dane identyfikacyjneMogą pomóc zidentyfikować przesyłkę, gdy przewoźnik wymaga czegoś więcej niż numeru śledzenia.Przesyłaj wyłącznie pola udokumentowane dla danej integracji i przewoźnika.
Dane uwierzytelniające APIUwierzytelniają konto wywołujące.Przechowuj je na serwerze i wyklucz z logów aplikacji.

Traktuj numer śledzenia jako identyfikator

Nigdy nie konwertuj numeru śledzenia na liczbę całkowitą. Konwersja numeryczna może usunąć początkowe zera, a duże wartości mogą w niektórych środowiskach programistycznych utracić precyzję. Usuń przypadkowe spacje z początku i końca, ale nie usuwaj znaków interpunkcyjnych ani nie zmieniaj wielkości liter, chyba że odpowiednia dokumentacja lub format przewoźnika zezwala na taką normalizację.

Przed wywołaniem API sprawdź oczywiste błędy danych wejściowych: puste ciągi, nieoczekiwane znaki końca wiersza oraz numer zamówienia wprowadzony w polu numeru śledzenia. Unikaj narzucania jednej uniwersalnej reguły długości lub znaków dla wszystkich przewoźników. Reguła pasująca do jednego przewoźnika może odrzucać prawidłowe numery innego.

Oddziel numery zamówień od identyfikatorów przesyłek

Zamówienie może obejmować wiele paczek, a przesyłka zastępcza może otrzymać kolejny numer śledzenia. Modeluj rejestrację na poziomie przesyłki lub paczki, zamiast zakładać jeden numer śledzenia na zamówienie.

Jeśli używasz obsługiwanego przez dostawcę pola tagu lub numeru referencyjnego, preferuj nieprzejrzysty identyfikator przesyłki zamiast adresu e-mail lub adresu ulicznego klienta. Własna baza danych powinna pozostać źródłem prawdy dla powiązań między zamówieniami, przesyłkami, numerami śledzenia i mapowaniami przewoźników.

Wybierz właściwy kod przewoźnika

Kod przewoźnika nie musi być uniwersalnym identyfikatorem branżowym. Wartość rozpoznawana przez platformę śledzenia może różnić się od nazwy przewoźnika zapisanej w oprogramowaniu wysyłkowym. Nawet dwa systemy korzystające z kodów numerycznych mogą przypisać różne numery temu samemu przewoźnikowi.

Utrzymuj jawne mapowanie między usługą wysyłkową a identyfikatorem przewoźnika używanym przez dostawcę śledzenia. W razie potrzeby rozróżniaj regionalną działalność lub usługę przewoźnika od jego szerszej marki. Mapowanie oparte wyłącznie na nazwie wyświetlanej może stać się niejednoznaczne, gdy systemy wysyłkowe używają aliasów.

  • Gdy przewoźnik jest znany: używaj udokumentowanego identyfikatora przewoźnika, jeśli jest obsługiwany, szczególnie gdy formaty numerów śledzenia się nakładają.
  • Gdy przewoźnik jest nieznany: korzystaj z automatycznego wykrywania wyłącznie za pośrednictwem udokumentowanego mechanizmu. Nie zakładaj, że pominięcie pola, pusty ciąg, zero i null oznaczają to samo.
  • Gdy wynik wygląda nieprawidłowo: przed wielokrotną rejestracją tego samego numeru sprawdź oryginalną etykietę, usługę wysyłkową i mapowanie.

Automatyczne wykrywanie jest przydatne, ale nie stanowi dowodu, że konkretny przewoźnik fizycznie posiada przesyłkę. Podobnie prawidłowy kod przewoźnika nie gwarantuje, że podany numer śledzenia należy do tego przewoźnika.

Przechowuj mapowania przewoźników w konfiguracji, zamiast rozpraszać je w kodzie aplikacji. Zapisuj datę ostatniego sprawdzenia mapowania i uwzględniaj znaną przesyłkę w testach regresji przy każdej jego zmianie.

Przykład: wyślij żądanie rejestracji 17TRACK

Poniższy przykład przedstawia punkt końcowy rejestracji 17TRACK v2.2, nagłówek uwierzytelniania 17token oraz tablicę zawierającą jeden obiekt numeru śledzenia. Przed wdrożeniem potwierdź, że ta wersja i wymagania dotyczące żądania odpowiadają Twojemu kontu oraz oficjalnej dokumentacji. Numer śledzenia jest symbolem zastępczym i musi zostać zastąpiony rzeczywistym identyfikatorem przesyłki.

curl --request POST \
  --url 'https://api.17track.net/track/v2.2/register' \
  --header "17token: ${TRACKING_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "number": "YOUR_TRACKING_NUMBER"
    }
  ]'

Ten minimalny przykład nie pokazuje wyboru przewoźnika ani dodatkowych pól zależnych od przewoźnika. Sprawdź dokumentację rejestracji, aby ustalić, jak działa wykrywanie przewoźnika po pominięciu pola przewoźnika oraz czy Twoja przesyłka wymaga dodatkowych informacji. Jeśli podajesz przewoźnika, użyj udokumentowanego pola carrier i identyfikatora oczekiwanego przez daną wersję API.

Wykonuj to żądanie w środowisku po stronie serwera. Nie umieszczaj tokenu w publicznym sklepie, skrypcie przeglądarkowym ani aplikacji mobilnej dystrybuowanej klientom. Zmienna środowiskowa jest wygodna w lokalnym przykładzie; wdrożenia produkcyjne powinny korzystać z mechanizmów zarządzania sekretami w organizacji.

Przed zwiększeniem skali przetestuj jedną znaną przesyłkę i sprawdź pełną odpowiedź. Następnie przetestuj nieprawidłowe dane wejściowe oraz partię zawierającą elementy prawidłowe i nieprawidłowe. Dzięki tym kontrolom sprawdzisz, czy integracja obsługuje wyniki na poziomie elementów, a nie tylko rozpoznaje odpowiedź HTTP oznaczającą powodzenie.

Odczytuj odpowiedź na trzech poziomach

Niezawodny moduł obsługi odpowiedzi odpowiada na trzy odrębne pytania: czy żądanie dotarło do usługi, czy usługa zaakceptowała operację oraz co stało się z każdą przesyłką?

1. Wynik HTTP i transportu

Przekroczenie limitu czasu połączenia, błąd TLS lub przerwana odpowiedź nie muszą oznaczać, czy serwer przetworzył żądanie. Oznacz taki wynik jako niepewny do czasu jego uzgodnienia. Pomyślny status HTTP potwierdza udaną wymianę HTTP, ale nadal trzeba sprawdzić odpowiedź aplikacji.

2. Wynik na poziomie żądania

Sprawdź udokumentowany wynik najwyższego poziomu API oraz pola błędów. Błędy uwierzytelniania, nieprawidłowy JSON i ograniczenia konta wymagają różnych działań. Zapisuj oryginalny kod i komunikat błędu dostawcy, zamiast sprowadzać każdą awarię do komunikatu „śledzenie niedostępne”.

Nie zakładaj, że numeryczny kod aplikacji ma takie samo znaczenie jak kod statusu HTTP. Ich znaczenia pochodzą z różnych warstw i muszą być interpretowane osobno.

3. Wynik na poziomie przesyłki

W przypadku rejestracji zbiorczej uwzględnij każdy przesłany element. Odpowiedź może rozróżniać przesyłki zaakceptowane i odrzucone; parser powinien stosować dokładny schemat udokumentowany dla wybranej wersji. Nie oznaczaj całej partii jako zarejestrowanej tylko dlatego, że jeden element zakończył się powodzeniem.

Normalizuj odpowiedzi dostawcy do własnych stabilnych stanów aplikacji. Na przykład baza danych może używać wartości accepted, rejected i uncertain. Są to sugerowane stany wewnętrzne, a nie dosłowne wartości odpowiedzi 17TRACK. Zachowuj oryginalną odpowiedź dostawcy zgodnie z odpowiednią polityką przechowywania i dostępu, aby deweloperzy mogli badać rozbieżności.

Użyteczny rekord rejestracji zawiera wewnętrzny identyfikator przesyłki, przesłany numer, wybór przewoźnika, czas próby, wersję API, wynik i szczegóły błędu dostawcy. Oddziel status rejestracji od statusu doręczenia.

Obsługuj ponowienia bez tworzenia nieskończonej pętli

Polityka ponowień powinna zależeć od rodzaju awarii, a nie tylko od tego, czy wystąpił wyjątek.

  • Nieprawidłowe dane wejściowe: popraw pole przed ponowieniem. Powtarzanie niezmienionego nieprawidłowego żądania prawdopodobnie nie pomoże.
  • Błąd uwierzytelniania: sprawdź dane uwierzytelniające i konfigurację konta. Unikaj wielokrotnego przesyłania tej samej nieudanej partii.
  • Ograniczenie liczby żądań: przestrzegaj udokumentowanych limitów i odpowiednich instrukcji ponowienia. Używaj ograniczonego wycofywania zamiast natychmiastowych równoległych ponowień.
  • Tymczasowa awaria usługi: ponawiaj próbę w ramach określonego limitu prób i czasu.
  • Przekroczenie limitu czasu po wysłaniu: uzgodnij stan rejestracji przesyłki zgodnie z udokumentowanym działaniem API, zanim uznasz pierwszą próbę za nieudaną.
  • Odpowiedź dotycząca duplikatu: sprawdź, czy przesyłka jest już zarejestrowana i prawidłowo powiązana z rekordem aplikacji.

Nie zakładaj, że rejestracja jest idempotentna, chyba że dokumentacja definiuje takie działanie. Deduplicacja po stronie aplikacji ogranicza przypadkowe wielokrotne wysłanie, ale nie określa zasad obsługi duplikatów przez dostawcę.

Stosuj wewnętrzną regułę unikalności odpowiednią dla modelu przesyłek. Sam numer śledzenia może nie być wystarczającym stałym kluczem dla wielu przewoźników i długich okresów przechowywania. Zachowaj kontekst przewoźnika oraz własny identyfikator przesyłki i opisz sposób obsługi przesyłek zastępczych oraz poprawionych numerów.

Monitoruj rejestrację niezależnie od aktualizacji śledzenia

Monitorowanie API powinno odróżniać awarię integracji od przesyłki, dla której po prostu nie ma nowego zdarzenia przewoźnika. Warunki te wymagają różnych osób odpowiedzialnych i różnych działań naprawczych.

W przypadku rejestracji monitoruj liczbę akceptacji i odrzuceń, kategorie błędów, niepewne wyniki, kolejkę ponowień i opóźnienie odpowiedzi. W przypadku późniejszego śledzenia osobno monitoruj odbieranie aktualizacji lub błędy ich pobierania. Nie ustalaj liczbowych progów alertów, dopóki nie poznasz normalnego ruchu i udokumentowanych limitów operacyjnych dostawcy.

Praktyczna kontrola produkcyjna powinna odpowiadać na pytania:

  1. Czy każda przesyłka oczekująca na śledzenie ma rekord rejestracji?
  2. Czy każdą zaakceptowaną rejestrację można powiązać z właściwą paczką?
  3. Czy odrzucone elementy są kierowane do osoby, która może poprawić dane źródłowe?
  4. Czy niepewne żądania są uzgadniane, zamiast porzucane lub ponawiane bez końca?
  5. Czy statusy widoczne dla klientów wynikają ze zdarzeń przesyłki, a nie z akceptacji rejestracji?
  6. Czy dane uwierzytelniające i zbędne dane osobowe są wykluczone z logów?

W operacjach e-commerce przekazanie operacyjne jest równie ważne jak samo wywołanie API. Deweloperzy powinni odpowiadać za błędy transportu i parsowania; zespoły wysyłkowe lub realizacji zamówień powinny móc badać nieprawidłowe etykiety, mapowania przewoźników i brakujące informacje o przesyłkach.

FAQ

Czy mogę zarejestrować numer śledzenia przed pierwszym skanem przewoźnika?

Rejestracja i skany przewoźnika to odrębne zdarzenia. Usługa może zaakceptować numer, zanim zdarzenia śledzenia staną się dostępne, zgodnie ze swoimi regułami walidacji. Nie interpretuj akceptacji jako dowodu, że przewoźnik otrzymał paczkę.

Czy zawsze muszę podawać kod przewoźnika?

Zależy to od udokumentowanego sposobu wykrywania przewoźnika przez API oraz od konkretnej przesyłki. Jeśli przewoźnik jest znany, jawny i prawidłowo zmapowany identyfikator może ograniczyć niejednoznaczność. Jeśli jest nieznany, użyj udokumentowanej metody automatycznego wykrywania zamiast wymyślać wartość przewoźnika.

Dlaczego API zwróciło powodzenie HTTP, mimo że przesyłka nie powiodła się?

Żądanie HTTP może zakończyć się powodzeniem, podczas gdy aplikacja odrzuci pojedynczy element. Odczytaj wynik aplikacji najwyższego poziomu oraz wyniki na poziomie przesyłek. To rozróżnienie jest szczególnie ważne dla żądań zbiorczych.

Co zrobić, gdy żądanie rejestracji przekroczy limit czasu?

Potraktuj wynik jako niepewny. Serwer mógł przetworzyć żądanie przed zerwaniem połączenia. Sprawdź udokumentowane zasady obsługi duplikatów przez dostawcę oraz dostępne metody wyszukiwania rejestracji lub śledzenia, a następnie uzgodnij wynik lub ponów próbę w ramach ograniczonej polityki.

Czy rejestracja automatycznie konfiguruje powiadomienia o śledzeniu?

Nie zakładaj, że tak jest. Rejestracja, pobieranie danych śledzenia i konfiguracja webhooków to odrębne kwestie integracyjne. Sprawdź odpowiednią dokumentację i przetestuj pełną ścieżkę aktualizacji, zanim zaczniesz polegać na niej przy powiadomieniach dla klientów.

Źródła

  • Dokumentacja API 17TRACK — źródło informacji o punktach końcowych rejestracji, uwierzytelnianiu, polach żądań, identyfikatorach przewoźników, schematach odpowiedzi i obsłudze błędów. Dopasuj szczegóły implementacji do wdrażanej wersji API.
  • Przegląd 17TRACK Tracking API — oficjalny punkt wyjścia do produktu Tracking API i zasobów integracyjnych dla deweloperów.