Jak wysyłać wiele numerów śledzenia w jednym żądaniu API (limity partii i częściowe niepowodzenia)
Aby wysłać wiele numerów śledzenia w jednym żądaniu API, użyj punktu końcowego Tracking API, który wyraźnie obsługuje żądania zbiorcze, sformatuj każdą przesyłkę zgodnie ze schematem żądania i podziel większe listy na partie mieszczące się w udokumentowanych limitach. Następnie sprawdź zarówno odpowiedź HTTP, jak i wynik każdej przesyłki: pomyślne żądanie HTTP nie musi oznaczać, że każdy numer śledzenia został zaakceptowany. Ponawiaj próbę tylko w przypadku kwalifikujących się błędów i uzgodnij niepewne wyniki przed ponownym wysłaniem całej partii.

Ten przewodnik jest przeznaczony dla programistów łączących śledzenie przesyłek z systemem zarządzania zamówieniami, platformą magazynową, aplikacją e-commerce lub wewnętrznym panelem. Celem nie jest po prostu wysyłanie mniejszej liczby żądań. Chodzi o uwzględnienie każdej przesyłki bez tworzenia zduplikowanej pracy ani utraty nieudanych rekordów.
Najpierw ustal, co właściwie robi punkt końcowy obsługujący partie
Integracja śledzenia może obejmować kilka odrębnych operacji. Rejestrowanie przesyłek, pobieranie ich najnowszych informacji o śledzeniu oraz odbieranie późniejszych aktualizacji nie są czynnościami wymiennymi.
- Rejestracja: Prześlij przesyłki, aby usługa mogła rozpocząć lub kontynuować ich śledzenie.
- Wyszukiwanie: Zażądaj informacji o śledzeniu przesyłek, zgodnie z zasadami pobierania obowiązującymi dla danego punktu końcowego.
- Aktualizacja dostawy: Otrzymuj późniejsze zmiany za pośrednictwem obsługiwanego mechanizmu, takiego jak webhooki, lub pobieraj je za pomocą zaplanowanych żądań.
Sprawdź dokumentację, aby ustalić dokładnie potrzebną operację. Punkt końcowy rejestracji akceptujący wiele rekordów nie oznacza, że punkt końcowy wyszukiwania akceptuje tę samą liczbę rekordów, używa tego samego schematu lub ma ten sam limit żądań.
W przypadku integracji z 17TRACK zacznij od strony produktu Tracking API i skorzystaj z oficjalnej dokumentacji API, aby potwierdzić operację, metodę uwierzytelniania, format żądania i pola odpowiedzi. Traktuj poniższe przykłady jako wzorce implementacyjne, a nie zamiennik umowy określającej działanie tego API.
Limity partii to coś więcej niż maksymalna liczba przesyłek
Nie istnieje uniwersalny limit partii dla Tracking API. Limity mogą różnić się w zależności od dostawcy, punktu końcowego, wersji API i konfiguracji konta. Przed wdrożeniem obsługi partii zapisz te ograniczenia osobno.
| Ograniczenie | Co należy potwierdzić | Konsekwencja implementacyjna |
|---|---|---|
| Liczba elementów w żądaniu | Maksymalna liczba rekordów dla określonej operacji | Podziel listę wejściową przed wysłaniem |
| Rozmiar treści żądania | Każdy udokumentowany limit bajtów | Uwzględnij pola opcjonalne i rozmiar serializacji |
| Częstotliwość żądań | Dozwolona liczba żądań w określonym przedziale | Kontroluj tempo żądań za pomocą współdzielonego limitera |
| Współbieżność | Każde ograniczenie dotyczące jednoczesnych żądań | Ogranicz liczbę aktywnych procesów roboczych |
| Rozliczanie użycia | Czy użycie jest liczone według żądania, przesyłki czy innej jednostki | Oszacuj zużycie niezależnie od liczby żądań |
Przykładowo, jeśli hipotetyczny punkt końcowy zezwala na 25 rekordów w jednym żądaniu, 63 rekordy wymagają trzech żądań zawierających odpowiednio 25, 25 i 13 rekordów. Liczby te ilustrują wyłącznie dzielenie na fragmenty; nie są limitami 17TRACK.
Nie zakładaj, że grupowanie zmniejsza rozliczane użycie. Może ograniczyć narzut związany z żądaniami HTTP, ale wpływ na opłaty zależy od rzeczywistych zasad rozliczania dostawcy. Podobnie prawidłowy rozmiar partii nie zezwala na nieograniczoną liczbę równoległych żądań.
Przygotuj rekordy przed utworzeniem żądania
Większość możliwych do uniknięcia błędów partii zaczyna się od przygotowania danych wejściowych. Zweryfikuj każdą przesyłkę przed dodaniem jej do partii, ale unikaj reguł, które przypadkowo odrzucają prawidłowe numery śledzenia różnych przewoźników.
- Zachowaj numery śledzenia jako ciągi znaków. Konwersja na liczby może usunąć początkowe zera lub zmienić długie identyfikatory.
- Usuń przypadkowe białe znaki wokół wartości. Nie usuwaj znaków wewnętrznych ani nie zmieniaj wielkości liter, chyba że odpowiednia specyfikacja zezwala na taką normalizację.
- Zweryfikuj wymagane pola. Niektóre procesy mogą wymagać identyfikatora przewoźnika lub dodatkowych informacji o przesyłce. Używaj wyłącznie udokumentowanych nazw i wartości pól.
- Określ jawny zakres usuwania duplikatów. Powtórzony numer śledzenia nie jest automatycznie duplikatem dla każdego przewoźnika, sprzedawcy lub historycznej przesyłki.
- Zachowaj lokalny identyfikator przesyłki. Przechowuj powiązanie między wysyłanym elementem a rekordem zamówienia lub przesyłki, nawet jeśli API nie przyjmuje niestandardowych pól referencyjnych.
W przypadku Carrier Tracking obejmującego wiele sieci nie wyciągaj wniosków o przewoźniku wyłącznie na podstawie długości lub prefiksu numeru śledzenia, chyba że takie wnioskowanie jest wiarygodne w konkretnym procesie. Jeśli API obsługuje identyfikację przewoźnika, postępuj zgodnie z udokumentowanym sposobem obsługi niejednoznaczności.
Przykładowa struktura żądania
Poniższy JSON pokazuje koncepcję ładunku partii. Obiekt opakowujący, nazwy właściwości i identyfikatory są przykładowe, a nie zgodne ze schematem żądania 17TRACK. Niektóre API wymagają tablicy najwyższego poziomu zamiast obiektu zawierającego tablicę.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Twórz ładunek za pomocą serializatora JSON, zamiast łączyć ciągi znaków. Wysyłaj dane uwierzytelniające za pomocą udokumentowanego mechanizmu i nie umieszczaj ich w kontroli wersji, kodzie dostarczanym do przeglądarki ani rutynowych logach.
Przetwarzaj odpowiedź na dwóch poziomach
Żądanie partii ma wynik na poziomie transportu oraz wynik na poziomie aplikacji. Integracja musi oceniać oba.
Poziom 1: Czy żądanie otrzymało użyteczną odpowiedź?
Rozpocznij od statusu HTTP, nagłówków odpowiedzi i jej treści. Błędy uwierzytelniania, nieprawidłowe żądania, ograniczenie częstotliwości i awarie serwera mogą uniemożliwić normalne przetwarzanie elementów. Przekroczenie limitu czasu sieci jest czymś innym: klient może nie wiedzieć, czy serwer otrzymał lub przetworzył żądanie.
Semantykę HTTP definiuje RFC 9110. Jednak dokumentacja dostawcy określa, jak pola wyników na poziomie aplikacji przekładają się na rzeczywiste wyniki dotyczące przesyłek.
Poziom 2: Co stało się z każdą przesyłką?
Jeśli odpowiedź obsługuje wyniki na poziomie elementów, sklasyfikuj każdy przesłany rekord. Nie zakładaj, że HTTP 200 oznacza powodzenie każdego rekordu ani że lista wyników zachowuje kolejność żądania, chyba że umowa wyraźnie to gwarantuje.
- Zaakceptowane: Operacja zakończyła się powodzeniem zgodnie z udokumentowaną definicją punktu końcowego.
- Trwały błąd danych wejściowych: Popraw rekord lub zbadaj go przed kolejną próbą.
- Błąd możliwy do ponowienia: Zaplanuj kolejną próbę zgodnie z wytycznymi dostawcy dotyczącymi ponawiania.
- Nieznany wynik: Odpowiedź jest nieobecna, niekompletna lub nie można jej bezpiecznie dopasować do przesłanego rekordu.
Trzymaj odpowiedzi typu „już zarejestrowano” lub podobne odpowiedzi związane z duplikatami osobno, dopóki nie zrozumiesz ich udokumentowanego znaczenia. Mogą wskazywać, że żądany stan już istnieje, ale nie powinny być automatycznie traktowane jako potwierdzenie pomyślnego przypisania, konfiguracji lub subskrypcji.
Po przetworzeniu odpowiedzi każdy rekord wejściowy powinien mieć dokładnie jeden lokalny wynik. Przydatna kontrola uzgodnienia wygląda następująco: przesłane rekordy równe są zaakceptowanym rekordom plus trwałe błędy plus błędy możliwe do ponowienia plus nieznane wyniki. Jest to lokalna zasada księgowania, a nie wymagany format odpowiedzi API.
Obsługuj częściowe błędy bez ponownego odtwarzania pomyślnych rekordów
Załóżmy, że przykładowa partia zawiera dziesięć przesyłek: siedem zostaje zaakceptowanych, dwie mają nieprawidłowe wymagane pola, a jedna napotyka udokumentowany błąd tymczasowy. Zapisz siedem pomyślnych wyników, skieruj dwa nieprawidłowe rekordy do poprawy i ponów próbę wyłącznie dla błędu tymczasowego.
Ponowne wysłanie wszystkich dziesięciu rekordów tworzy niepotrzebny ruch i może komplikować obsługę duplikatów. Utrudnia również odróżnienie pierwotnego odrzucenia od późniejszej odpowiedzi związanej z duplikatem.
| Wynik | Zalecane działanie |
|---|---|
| Nieprawidłowe pole lub nieobsługiwana wartość | Popraw dane wejściowe; nie ponawiaj próby bez zmian |
| Błąd uwierzytelniania lub uprawnień | Wstrzymaj dotknięte zadania i napraw dane uwierzytelniające lub dostęp |
| Odpowiedź o ograniczeniu częstotliwości | Opóźnij zgodnie z udokumentowanymi wytycznymi i odpowiednimi nagłówkami odpowiedzi |
| Tymczasowy błąd na poziomie elementu | Ponów próbę dla tego elementu z ograniczoną liczbą prób i mechanizmem backoff |
| Przekroczenie limitu czasu po wysłaniu | Oznacz jako niepewne; uzgodnij wynik lub użyj udokumentowanych gwarancji bezpieczeństwa ponowienia |
| Nierozpoznany lub niekompletny wynik | Zachowaj dowody i zbadaj sprawę zamiast zakładać powodzenie |
HTTP 429 oznacza zbyt wiele żądań, a odpowiedź może zawierać nagłówek Retry-After, jak opisano w RFC 6585. Nie zakładaj, że ten nagłówek jest zawsze obecny. Gdy nie podano wyraźnego opóźnienia ponowienia, zastosuj ograniczoną politykę backoff zgodną z dokumentacją API.
Dodaj jitter, aby rozłożyć ponowienia wielu procesów roboczych, ustaw maksymalną liczbę prób lub maksymalny wiek ponawiania i przekazuj wyczerpane rekordy do kolejki przeglądu. Nieskończone ponawianie może ukryć trwały problem z konfiguracją.
Dlaczego przekroczenia limitu czasu wymagają szczególnego traktowania
Przekroczenie limitu czasu nie dowodzi odrzucenia. Serwer mógł zaakceptować partię przed zerwaniem połączenia. Automatyczne ponowne wysłanie żądania zmieniającego stan może więc powtórzyć pracę.
Jeśli punkt końcowy obsługuje udokumentowane klucze idempotencji, postępuj zgodnie z jego zasadami, w tym zakresem i czasem przechowywania klucza. Nie wymyślaj nagłówka idempotencji i nie zakładaj, że serwer go respektuje. W przeciwnym razie użyj obsługiwanego procesu wyszukiwania lub uzgadniania, aby ustalić, czy żądany stan istnieje, zanim ponownie wyślesz żądanie. Lokalne usuwanie duplikatów pomaga koordynować własne procesy robocze, ale nie gwarantuje idempotencji po stronie serwera.
Praktyczny proces przetwarzania partii
Przechowuj szczegóły specyficzne dla dostawcy w adapterze, aby kolejka, harmonogram ponowień i logika monitorowania nie zależały od surowych nazw pól odpowiedzi.
zweryfikuj rekordy i zachowaj lokalne identyfikatory przesyłek
rozwiąż duplikaty w zamierzonym zakresie biznesowym
podziel rekordy zgodnie z udokumentowanymi limitami elementów i ładunku
dla każdej partii za pośrednictwem ograniczonej puli procesów roboczych:
zapisz rekord próby przed wysłaniem
zaczekaj na współdzielony limiter częstotliwości
wyślij za pomocą adaptera specyficznego dla dostawcy
jeśli wynik jest niepewny:
umieść zadanie uzgodnienia w kolejce
kontynuuj
sklasyfikuj wyniki na poziomie żądania i elementu
zapisz jeden wynik dla każdego przesłanego rekordu
zaplanuj ponowienie tylko dla kwalifikujących się błędów
skieruj nieprawidłowe lub wyczerpane rekordy do przeglądu
Zapis wyników i planowanie ponowień powinny być możliwe do odzyskania. Na przykład trwały rekord zadania lub transakcyjny wzorzec kolejkowania może zapobiec utracie decyzji o ponowieniu po awarii procesu. Po ponownym uruchomieniu procesy robocze powinny móc odróżnić niewysłaną pracę od pracy, której zdalny wynik jest nadal niepewny.
Traktuj rozmiar partii jako konfigurowalne ustawienie powiązane z odpowiednim punktem końcowym, a nie jako stałą rozproszoną w całej bazie kodu. Mniejsza partia może być przydatna podczas rozwiązywania problemów lub izolowania wadliwych rekordów; największa dozwolona partia nie jest automatycznie najlepszym rozmiarem operacyjnym.
Monitoruj wyniki przesyłek, a nie tylko dostępność HTTP
API Monitoring powinien pokazywać, czy przesyłki osiągają zamierzony stan. Panel pokazujący wyłącznie wskaźniki pomyślnych żądań HTTP może przeoczyć częściowe błędy w pozornie pomyślnych odpowiedziach.
- Wskaźnik akceptacji elementów: Zaakceptowane rekordy podzielone przez przesłane rekordy, z jasno określonym sposobem traktowania ponowień.
- Rozkład błędów: Liczby według punktu końcowego, udokumentowanego kodu błędu i odpowiedniego kontekstu przewoźnika.
- Nieznane wyniki: Nieuzgodnione rekordy oraz czas, przez jaki pozostają nierozstrzygnięte.
- Zaległości ponowień: Oczekujące ponowienia, wiek najstarszego ponowienia i wyczerpane próby.
- Kondycja żądań: Opóźnienia, przekroczenia limitu czasu, ograniczenie częstotliwości i błędy serwera.
- Aktualność śledzenia: Czy zaakceptowane przesyłki otrzymują później użyteczne informacje o śledzeniu.
Akceptacja rejestracji nie jest dowodem nowego skanu przewoźnika. Oddziel status przetwarzania API od ruchu przesyłki i aktualności danych, aby nie mylić incydentu integracyjnego z opóźnieniem dostawy.
Rejestruj lokalne identyfikatory partii, referencje przesyłek, liczbę prób, udokumentowane kody błędów i identyfikatory żądań dostawcy, gdy są dostępne. Maskuj dane uwierzytelniające i zbędne informacje osobowe. Używaj identyfikatorów śledzenia tylko wtedy, gdy jest to konieczne operacyjnie, i unikaj umieszczania surowych identyfikatorów przesyłek w etykietach metryk o wysokiej kardynalności.
Przetestuj te przypadki przed wdrożeniem produkcyjnym
Jeśli jest dostępne, użyj udokumentowanego środowiska sandbox lub kontrolowanego środowiska testowego. Nie zakładaj, że wymyślone numery śledzenia dadzą przewidywalne odpowiedzi produkcyjne.
- Wyślij prawidłową partię o udokumentowanym limicie elementów, a następnie sprawdź, jak klient zapobiega utworzeniu zbyt dużej partii.
- Sprawdź, czy numery śledzenia z początkowymi zerami przetrwają serializację i przechowywanie.
- Przetestuj mieszane elementy zaakceptowane i odrzucone bez ponawiania pomyślnych rekordów.
- Symuluj ograniczenie częstotliwości i potwierdź, że wiele procesów roboczych respektuje ten sam limit.
- Symuluj przekroczenie limitu czasu po wysłaniu i zweryfikuj ścieżkę uzgadniania.
- Uruchom ponownie proces roboczy między odebraniem odpowiedzi a jej lokalnym zapisaniem.
- Przetestuj brakujące, nieznane lub niemożliwe do dopasowania wyniki elementów.
- Potwierdź, że nieprawidłowe rekordy trafiają do widocznej kolejki korekt zamiast być ponawiane bez końca.
Gotowa produkcyjnie integracja potrafi wyjaśnić stan każdej przesłanej przesyłki, w tym tych, których wynik jest tymczasowo nieznany. Zmniejszenie liczby żądań jest użyteczne, ale zachowanie tej rozliczalności jest ważniejszym celem projektowym.
FAQ
Ile numerów śledzenia mogę wysłać w jednym żądaniu?
Użyj limitu udokumentowanego dla dokładnego punktu końcowego i wersji API. Sprawdź również rozmiar żądania, limity częstotliwości i ograniczenia dotyczące konkretnego konta. Nie ma jednej bezpiecznej liczby, którą można zastosować do wszystkich API śledzenia ani do różnych operacji w ramach jednego API.
Czy jeden nieprawidłowy numer śledzenia może spowodować niepowodzenie całej partii?
Tak, zależnie od zasad walidacji punktu końcowego. Niektóre API zwracają indywidualne odrzucenia, a inne mogą odrzucić żądanie przed przetworzeniem elementów. Sprawdź zarówno błędy na poziomie żądania, jak i wyniki na poziomie elementów; nie zakładaj, że każdy punkt końcowy obsługujący partie wspiera częściową akceptację.
Czy powinienem ponowić partię, gdy odpowiedź HTTP jest pomyślna?
Nie automatycznie. Najpierw przeanalizuj udokumentowany status na poziomie aplikacji i wyniki elementów. Zapisz pomyślne rekordy i ponów próbę wyłącznie dla kwalifikujących się błędów. Jeśli wyniku nie można bezpiecznie zinterpretować, sklasyfikuj go jako niepewny i zbadaj sprawę.
Czy mogę mieszać przewoźników w tej samej partii?
Tylko wtedy, gdy punkt końcowy obsługuje taką strukturę żądania. Potwierdź, czy informacje o przewoźniku są podawane dla każdej przesyłki, czy obsługiwana jest automatyczna identyfikacja oraz co się dzieje przy niejednoznacznej identyfikacji. Sama usługa wielu przewoźników nie określa zasad grupowania obowiązujących dla każdego punktu końcowego.
Czy grupowanie sprawia, że aktualizacje śledzenia docierają szybciej?
Grupowanie może zmniejszyć liczbę żądań wysyłanych przez aplikację, ale samo w sobie nie sprawia, że zdarzenia przewoźnika pojawiają się wcześniej. Rejestracja, pobieranie danych, dostępność skanów przewoźnika i dostarczanie aktualizacji to odrębne części procesu.
Źródła
- 17TRACK Tracking API — oficjalny punkt wejścia do produktu dla programistów oceniających integrację śledzenia.
- Dokumentacja 17TRACK API — źródło informacji o specyficznej dla dostawcy umowie punktów końcowych, limitach, uwierzytelnianiu i obsłudze odpowiedzi.
- RFC 9110: Semantyka HTTP — semantyka statusów HTTP, idempotencja, automatyczne ponowienia i Retry-After.
- RFC 6585: Dodatkowe kody statusu HTTP — definicja HTTP 429 Too Many Requests i opcjonalnego nagłówka Retry-After.


