Skip to main content
StartBlogPrzewodnikiJak zweryfikować numery śledzenia przed przesłaniem do API: 7 zasad, których należy przestrzegać

Jak zweryfikować numery śledzenia przed przesłaniem do API: 7 zasad, których należy przestrzegać

17TRACK

Przed wysłaniem numeru śledzenia do interfejsu API śledzenia należy przeprowadzić wielopoziomową walidację: znormalizować dane wejściowe, sprawdzić ich podstawową strukturę, potwierdzić kontekst przewoźnika, zastosować sumę kontrolną tylko wtedy, gdy przewoźnik ją określa, oraz odrzucić wartości, które są wyraźnie niebezpieczne lub niekompletne. Nie należy polegać na jednym uniwersalnym wyrażeniu regularnym. Formaty numerów śledzenia różnią się w zależności od przewoźnika, usługi, kraju i rodzaju przesyłki, dlatego skuteczny walidator powinien zapobiegać błędnym żądaniom, nie blokując prawidłowych numerów wykorzystujących nieznany format.

Jak walidować numery śledzenia przed wysłaniem do interfejsu API — 7 zasad

Ten przewodnik jest przeznaczony dla programistów i zespołów operacyjnych integrujących śledzenie przesyłek z systemem zarządzania zamówieniami, procesem magazynowym, portalem klienta lub aplikacją e-commerce. Celem nie jest potwierdzenie przed wysłaniem, że przesyłka istnieje. Walidacja składni i walidacja statusu przesyłki to odrębne kroki.

Co walidacja może — a czego nie może — potwierdzić

Walidator działający przed wysłaniem może wykryć typowe problemy z danymi wejściowymi, takie jak pusta wartość, przypadkowe spacje, nieobsługiwane znaki, nadmierna długość lub numer śledzenia umieszczony w niewłaściwym polu. Może również wskazać prawdopodobnego przewoźnika, gdy przewoźnik jest znany, a format został udokumentowany.

Zwykle nie może potwierdzić, że numer należy do rzeczywistej przesyłki, że paczka została przyjęta przez przewoźnika ani że numer można obecnie śledzić. Do rozstrzygnięcia tych kwestii potrzebne jest wyszukanie informacji u przewoźnika lub na platformie śledzenia. Numer może przejść kontrolę formatu, a mimo to być nieużywany, subtelnie błędnie wpisany, wygasły lub powiązany z inną usługą.

Siedem zasad

1. Normalizuj wartość bez zmiany jej znaczenia

Użytkownicy i systemy nadrzędne często dodają spacje na początku lub końcu, podziały wiersza, twarde spacje albo znaki formatowania. Przed walidacją należy bezpiecznie znormalizować te dane. Typowym pierwszym krokiem jest usunięcie otaczających białych znaków i zamiana niedrukowalnych białych znaków na zwykłe spacje. Jeśli udokumentowany format przewoźnika dopuszcza spacje wewnętrzne lub łączniki, należy zdecydować, czy usunąć je na potrzeby żądania do interfejsu API, czy zachować oryginalną wartość do wyświetlania i audytu.

W miarę możliwości przechowuj dwie wartości: oryginalne dane wejściowe i wartość kanoniczną. Oryginał pomaga zespołom wsparcia analizować problemy z jakością danych, natomiast wartość kanoniczna służy do walidacji i wysłania. Unikaj przekształceń, które mogą zmienić identyfikatory. Nie zamieniaj automatycznie liter na cyfry, nie zastępuj niejednoznacznych znaków ani nie usuwaj wszystkich znaków interpunkcyjnych, chyba że odpowiednia dokumentacja przewoźnika lub interfejsu API wyraźnie dopuszcza takie działanie.

Obsługa Unicode wymaga szczególnej uwagi. Znak z innego alfabetu, który wygląda podobnie, może nie być akceptowany przez interfejs API, nawet jeśli przypomina literę lub cyfrę ASCII. Ograniczenie wartości kanonicznej do zestawu znaków dozwolonego przez wybraną integrację może zapobiec trudnym do zrozumienia błędom w dalszym przetwarzaniu.

2. Odrzucaj wartości, które nie przechodzą podstawowych kontroli strukturalnych

Przed zastosowaniem logiki właściwej dla przewoźnika sprawdź, czy wartość istnieje i jest wiarygodna. Przydatne kontrole obejmują minimalną i maksymalną długość, dozwolone klasy znaków oraz sprawdzenie, czy wartość zawiera wyłącznie białe znaki lub symbol zastępczy, taki jak „N/A”, „TBD” albo „test”. Dokładne limity powinny wynikać z umowy interfejsu API lub dokumentacji przewoźnika. Nie twórz uniwersalnego limitu maksymalnego tylko dlatego, że większość przykładów jest krótka.

Kontrola strukturalna powinna być celowo zachowawcza. Na przykład reguła dopuszczająca wyłącznie cyfry odrzuci prawidłowe identyfikatory alfanumeryczne. Reguła wymagająca jednej stałej długości może odrzucać warianty usług lub formaty międzynarodowe. Używaj ogólnych kontroli do wykrywania oczywistych błędów, a bardziej szczegółowe kontrole stosuj tylko wtedy, gdy znany jest przewoźnik i usługa.

Waliduj również typ danych na granicy aplikacji. Numer śledzenia powinien być zwykle traktowany jako ciąg znaków, a nie liczba całkowita. Konwersja na typ liczbowy może usunąć początkowe zera i powodować problemy z precyzją w systemach używających typów liczbowych o stałej szerokości. Po zatwierdzonej normalizacji zachowuj wartość dokładnie jako ciąg znaków.

3. Korzystaj z kontekstu przewoźnika zamiast zgadywać wyłącznie na podstawie numeru

Numer śledzenia bez informacji o przewoźniku jest niejednoznacznymi danymi wejściowymi. Różni przewoźnicy mogą używać nakładających się długości, prefiksów lub zestawów znaków, a format wiarygodny dla jednego przewoźnika może być nieprawidłowy dla innego. Jeśli zamówienie, etykieta, system magazynowy lub konto sprzedawcy już identyfikuje przewoźnika, przekazuj ten kontekst wraz z numerem śledzenia, gdy tylko interfejs API to obsługuje.

Kontekst przewoźnika poprawia zarówno walidację, jak i kierowanie żądań. Umożliwia aplikacji wybranie odpowiednich reguł formatu, ogranicza liczbę fałszywych dopasowań i pozwala tworzyć bardziej użyteczne komunikaty o błędach. Zapobiega również traktowaniu wyniku automatycznego wykrywania jako faktu, gdy kilku przewoźników może akceptować podobnie wyglądającą wartość.

Jeśli przewoźnik jest nieznany, zastosuj podejście dwuetapowe. Najpierw wykonaj ogólne kontrole bezpieczeństwa. Następnie wyślij wartość wyłącznie za pośrednictwem procesu API, który wyraźnie obsługuje wykrywanie przewoźnika, albo umieść ją w kolejce do weryfikacji, gdy proces biznesowy wymaga potwierdzonego przewoźnika. Nie przypisuj po cichu przewoźnika wyłącznie na podstawie prefiksu, chyba że takie mapowanie jest utrzymywane i udokumentowane.

4. Stosuj sumy kontrolne tylko wtedy, gdy reguła jest udokumentowana

Niektóre systemy identyfikatorów używają cyfr kontrolnych, ale numery śledzenia nie podlegają jednemu uniwersalnemu standardowi sum kontrolnych. Suma kontrolna może wykrywać niektóre błędy przepisywania, ale nie dowodzi istnienia przesyłki. Co ważniejsze, zastosowanie niewłaściwego algorytmu sumy kontrolnej może odrzucać prawidłowe numery.

Implementuj sumę kontrolną tylko wtedy, gdy odpowiedni przewoźnik, usługa, specyfikacja etykiety lub dokumentacja interfejsu API określa algorytm oraz część danych wejściowych, której on dotyczy. Zapisz wersję reguły i przetestuj ją na oficjalnych przykładach. Jeśli nie ma wiarygodnej reguły, pomiń sumę kontrolną zamiast zgadywać na podstawie wzorców zaobserwowanych w małej próbce.

Traktuj wynik sumy kontrolnej jako jeden z sygnałów, a nie jako pełną decyzję walidacyjną. Nieudana kontrola może uzasadniać zablokowanie wysłania, gdy reguła jest wiarygodna. Udana kontrola powinna przenieść wartość do następnego etapu, a nie oznaczać jej jako aktywnej przesyłki.

5. Oddziel walidację formatu od kwalifikacji do interfejsu API

Wartość może być prawidłowo sformatowana, a mimo to nie nadawać się do punktu końcowego, z którym się łączysz. Przed wysłaniem sprawdź w dokumentacji interfejsu API wymagane pola, akceptowane identyfikatory przewoźników, wymagania dotyczące uwierzytelniania, limity żądań, sposób obsługi duplikatów oraz ewentualne ograniczenia dotyczące typów usług lub miejsc docelowych. Są to reguły integracji, a nie reguły numeru śledzenia, ale decydują o tym, czy prawidłowy identyfikator może zostać pomyślnie przetworzony.

Dokumentacja 17TRACK Tracking API pokazuje, dlaczego to rozróżnienie ma znaczenie: programiści muszą stosować model żądań platformy i obsługiwane zasady integracji, zamiast tworzyć żądanie na podstawie wyglądu numeru śledzenia. Aktualne wymagania dotyczące punktów końcowych i obsługi odpowiedzi znajdziesz w dokumentacji 17TRACK API.

Oddziel błędy walidacji od błędów transportu i uwierzytelniania. Komunikaty „Nieprawidłowy format numeru śledzenia”, „Nieznany przewoźnik”, „Osiągnięto limit liczby żądań” i „Uwierzytelnianie nie powiodło się” wymagają różnych działań. Jeden ogólny komunikat „Wysyłanie nie powiodło się” utrudnia ponawianie prób i wiarygodne raportowanie operacyjne.

6. Chroń interfejs API za pomocą ograniczonych danych wejściowych, usuwania duplikatów i bezpiecznego ponawiania prób

Walidacja jest również zabezpieczeniem operacyjnym. Wymuś ograniczenie długości danych wejściowych przed ich analizowaniem lub rejestrowaniem. Odrzucaj znaki sterujące i nieoczekiwane struktury danych. Stosuj limity liczby żądań na granicy własnej aplikacji, aby błędny import nie generował niekontrolowanego wzrostu liczby żądań.

Przed wysłaniem usuwaj duplikaty, gdy proces biznesowy nie wymaga wielokrotnej rejestracji. Przydatny klucz deduplikacji może obejmować kanoniczny numer śledzenia, przewoźnika, konto i kontekst przesyłki. Właściwy klucz zależy od procesu pracy; ten sam identyfikator może czasami być ponownie użyty w różnych usługach lub rekordach biznesowych, dlatego nie zakładaj, że sam numer zawsze jest globalnie unikatowy.

Stosuj ograniczoną liczbę ponowień z narastającym opóźnieniem w przypadku tymczasowych awarii i unikaj ponawiania trwałych błędów walidacji. Przechowuj rekord idempotencji lub wysłania, jeśli interfejs API i architektura na to pozwalają. Rejestruj wystarczająco dużo informacji, aby rozwiązywać problemy, ale chroń dane uwierzytelniające, dane klientów i wrażliwe szczegóły przesyłek. Walidator powinien ograniczać liczbę powtarzających się awarii, a nie tworzyć kolejny problem bezpieczeństwa przez nadmierne rejestrowanie danych.

7. Potwierdzaj wynik po wysłaniu i monitoruj fałszywe wyniki

Ostatnia zasada polega na traktowaniu walidacji przed wysłaniem jako bramki, a nie werdyktu. Po zaakceptowaniu żądania przeanalizuj odpowiedź interfejsu API i zapisz jej status, identyfikator żądania, powiązanie z przewoźnikiem oraz udokumentowany kod błędu. Jeśli platforma zaakceptuje żądanie, ale nie może jeszcze zwrócić zdarzeń dotyczących przemieszczania przesyłki, może to oznaczać opóźnienie przetwarzania, a nie nieprawidłowy numer.

Zdefiniuj zasady dalszego postępowania dla numerów, które pozostają nierozstrzygnięte. Okno czasowe powinno uwzględniać przewoźnika, usługę, miejsce nadania przesyłki i zasady obsługi klienta; nie ma uniwersalnego okresu, który dowodziłby nieprawidłowości numeru. Eskaluj rekordy z brakującym przewoźnikiem, powtarzającymi się błędami dostawcy, sprzecznymi wynikami przewoźników lub statusem niezgodnym z rekordem zamówienia.

Mierz liczbę fałszywych odrzuceń i fałszywych akceptacji. Ścisłe wyrażenie regularne może ograniczyć liczbę nieprawidłowych wysłań, jednocześnie błędnie blokując prawidłowe przesyłki. Liberalny walidator może zwiększyć liczbę zaakceptowanych żądań, ale powodować zakłócenia w dalszym przetwarzaniu. Analizuj nieudane próbki według przewoźnika i usługi, aktualizuj udokumentowane reguły za pomocą kontroli wersji oraz testuj zmiany na reprezentatywnym, bezpiecznym pod względem prywatności zestawie danych testowych.

Praktyczna sekwencja walidacji

Możliwa do utrzymania implementacja może korzystać z następującej sekwencji:

  1. Sprawdź, czy żądanie zawiera wartość tekstową i prawidłowy rekord biznesowy.
  2. Zapisz oryginalne dane wejściowe, a następnie utwórz udokumentowaną postać kanoniczną.
  3. Odrzuć puste wartości, symbole zastępcze, niebezpieczne znaki oraz wartości wykraczające poza udokumentowany zakres długości.
  4. Ustal przewoźnika na podstawie zaufanych danych zamówienia lub użyj jawnie obsługiwanego procesu wykrywania.
  5. Stosuj składnię właściwą dla przewoźnika i reguły sum kontrolnych tylko wtedy, gdy potwierdza je wiarygodna dokumentacja.
  6. Sprawdź wymagania punktu końcowego, stan duplikatów i możliwość ponowienia próby.
  7. Wyślij żądanie, sklasyfikuj odpowiedź, zapisz wynik i zaplanuj dalsze działania dla nierozstrzygniętych rekordów.

Ta sekwencja ułatwia testowanie walidatora, ponieważ każda decyzja ma inną przyczynę. Zapewnia również zespołom operacyjnym użyteczne kategorie błędów zamiast jednego nieprzejrzystego komunikatu.

Lista kontrolna implementacji

  • Przechowuj numery śledzenia jako ciągi znaków, aby zachować początkowe zera.
  • Gdy ważna jest możliwość audytu, przechowuj oddzielnie wartości oryginalne i kanoniczne.
  • Utrzymuj reguły przewoźników jako wersjonowaną konfigurację, a nie rozproszone warunki zakodowane na stałe.
  • Testuj litery, cyfry, łączniki, białe znaki, podobne znaki Unicode, symbole zastępcze i graniczne długości.
  • Korzystaj z zaufanego kontekstu przewoźnika, gdy jest dostępny.
  • Nie wnioskuj o istnieniu przesyłki na podstawie pomyślnego dopasowania wyrażenia regularnego.
  • Oddzielaj trwałe błędy walidacji od tymczasowych błędów interfejsu API lub sieci.
  • Przed zmianą reguł formatu lub logiki żądań zapoznaj się z dokumentacją dostawcy.

Najczęściej zadawane pytania

Czy wyrażenie regularne może zwalidować numer śledzenia?

Może zwalidować ograniczony wzorzec, gdy format przewoźnika i usługi jest znany. Nie może potwierdzić, że numer istnieje, należy do konkretnej przesyłki lub jest obecnie aktywny. Uniwersalne wyrażenie prawdopodobnie spowoduje fałszywe odrzucenia lub fałszywe dopasowania.

Czy numer wyglądający na nieprawidłowy należy wysłać do interfejsu API?

Wyraźnie puste, niebezpieczne lub strukturalnie niemożliwe wartości należy zazwyczaj zatrzymać przed wysłaniem. Nieznany, ale poza tym bezpieczny format nie powinien być odrzucany wyłącznie dlatego, że nie pasuje do wewnętrznego założenia. Najpierw sprawdź dokumentację przewoźnika lub skorzystaj z obsługiwanego procesu wykrywania.

Czy suma kontrolna wystarczy do potwierdzenia przesyłki?

Nie. Suma kontrolna, gdy ma zastosowanie, sprawdza jedynie, czy wartość spełnia regułę matematyczną. Nie potwierdza, że przewoźnik wydał numer ani że paczka weszła do sieci przewoźnika.

Co zrobić, gdy przewoźnik jest nieznany?

Wykonaj ogólne kontrole bezpieczeństwa i użyj procesu API, który wyraźnie obsługuje wykrywanie przewoźnika, jeśli jest dostępny. W przeciwnym razie zachowaj rekord do wzbogacenia danych lub ręcznej weryfikacji, zamiast po cichu zgadywać przewoźnika.

Jak należy obsługiwać błędy interfejsu API?

Klasyfikuj je według przyczyny. Napraw nieprawidłowe dane wejściowe i nieobsługiwane wartości przewoźnika; ponawiaj tymczasowe awarie sieci lub dostawcy z ograniczeniami i narastającym opóźnieniem; błędy uwierzytelniania lub limitów przekazuj właścicielowi integracji. Przechowuj szczegóły odpowiedzi potrzebne do diagnozy, nie ujawniając danych poufnych.

Źródła