Skip to main content
StartBlogPrzewodnikiJak wysyłać wiele numerów śledzenia w jednym żądaniu API (limity partii i częściowe niepowodzenia)

Jak wysyłać wiele numerów śledzenia w jednym żądaniu API (limity partii i częściowe niepowodzenia)

17TRACK

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.

Jak wysłać wiele numerów śledzenia w jednym żądaniu API

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.

OgraniczenieCo należy potwierdzićKonsekwencja implementacyjna
Liczba elementów w żądaniuMaksymalna liczba rekordów dla określonej operacjiPodziel listę wejściową przed wysłaniem
Rozmiar treści żądaniaKażdy udokumentowany limit bajtówUwzględnij pola opcjonalne i rozmiar serializacji
Częstotliwość żądańDozwolona liczba żądań w określonym przedzialeKontroluj 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życiaCzy użycie jest liczone według żądania, przesyłki czy innej jednostkiOszacuj 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.

  1. Zachowaj numery śledzenia jako ciągi znaków. Konwersja na liczby może usunąć początkowe zera lub zmienić długie identyfikatory.
  2. 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ę.
  3. 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.
  4. 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.
  5. 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.

WynikZalecane 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ściOpóźnij zgodnie z udokumentowanymi wytycznymi i odpowiednimi nagłówkami odpowiedzi
Tymczasowy błąd na poziomie elementuPonów próbę dla tego elementu z ograniczoną liczbą prób i mechanizmem backoff
Przekroczenie limitu czasu po wysłaniuOznacz jako niepewne; uzgodnij wynik lub użyj udokumentowanych gwarancji bezpieczeństwa ponowienia
Nierozpoznany lub niekompletny wynikZachowaj 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.

  1. Wyślij prawidłową partię o udokumentowanym limicie elementów, a następnie sprawdź, jak klient zapobiega utworzeniu zbyt dużej partii.
  2. Sprawdź, czy numery śledzenia z początkowymi zerami przetrwają serializację i przechowywanie.
  3. Przetestuj mieszane elementy zaakceptowane i odrzucone bez ponawiania pomyślnych rekordów.
  4. Symuluj ograniczenie częstotliwości i potwierdź, że wiele procesów roboczych respektuje ten sam limit.
  5. Symuluj przekroczenie limitu czasu po wysłaniu i zweryfikuj ścieżkę uzgadniania.
  6. Uruchom ponownie proces roboczy między odebraniem odpowiedzi a jej lokalnym zapisaniem.
  7. Przetestuj brakujące, nieznane lub niemożliwe do dopasowania wyniki elementów.
  8. 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