Skip to main content
ПочетакБлогVodičiKako poslati više brojeva za praćenje u jednom API zahtevu (ograničenja serije i delimični neuspesi)

Kako poslati više brojeva za praćenje u jednom API zahtevu (ograničenja serije i delimični neuspesi)

17TRACK

Da biste poslali više brojeva za praćenje u jednom API zahtevu, koristite krajnju tačku Tracking API-ja koja izričito prihvata paketne zahteve, formatirajte svaku pošiljku prema njenoj šemi zahteva i podelite veće liste u pakete unutar dokumentovanih ograničenja. Zatim proverite i HTTP odgovor i rezultat svake pošiljke: uspešan HTTP zahtev ne znači nužno da je svaki broj za praćenje prihvaćen. Ponovite pokušaj samo za greške koje ispunjavaju uslove za ponovni pokušaj i uskladite neizvesne ishode pre nego što ponovo pošaljete ceo paket.

Kako poslati više brojeva za praćenje u jednom API zahtevu

Ovaj vodič je namenjen programerima koji povezuju praćenje pošiljaka sa sistemom za upravljanje porudžbinama, skladišnom platformom, aplikacijom za e-trgovinu ili internom kontrolnom tablom. Cilj nije samo slanje manjeg broja zahteva. Potrebno je evidentirati svaku pošiljku bez stvaranja duplog posla ili gubitka neuspešnih zapisa.

Prvo utvrdite šta paketna krajnja tačka zapravo radi

Integracija praćenja može obuhvatati nekoliko različitih operacija. Registrovanje pošiljki, preuzimanje njihovih najnovijih informacija o praćenju i primanje naknadnih ažuriranja nisu međusobno zamenljivi.

  • Registracija: Pošaljite pošiljke kako bi usluga mogla da započne ili nastavi njihovo praćenje.
  • Pretraga: Zatražite informacije o praćenju pošiljki, u skladu sa pravilima preuzimanja konkretne krajnje tačke.
  • Ažuriranje isporuke: Primajte naknadne promene putem podržanog mehanizma, kao što su vebhookovi, ili ih preuzimajte kroz planirane zahteve.

Proverite dokumentaciju za tačnu operaciju koja vam je potrebna. Krajnja tačka za registraciju koja prihvata više zapisa ne potvrđuje da krajnja tačka za pretragu prihvata isti broj zapisa, koristi istu šemu ili ima isto ograničenje brzine.

Za 17TRACK integraciju počnite od stranice proizvoda Tracking API, a zatim koristite zvaničnu API dokumentaciju da potvrdite operaciju, metod autentifikacije, format zahteva i polja odgovora. Primere u nastavku posmatrajte kao obrasce implementacije, a ne kao zamenu za ugovor tog API-ja.

Ograničenja paketa nisu samo maksimalan broj pošiljki

Ne postoji univerzalno ograničenje veličine paketa za Tracking API. Ograničenja se mogu razlikovati prema pružaocu usluge, krajnjoj tački, verziji API-ja i konfiguraciji naloga. Pre implementacije paketne obrade zabeležite ova ograničenja odvojeno.

OgraničenjeŠta treba potvrditiPosledica po implementaciju
Stavke po zahtevuMaksimalan broj zapisa za konkretnu operacijuPodelite ulaznu listu pre slanja
Veličina tela zahtevaSvako dokumentovano ograničenje u bajtovimaUzmite u obzir opciona polja i veličinu serijalizacije
Brzina zahtevaDozvoljen broj zahteva tokom određenog intervalaUskladite slanje zahteva kroz zajednički limiter
IstovremenostSvako ograničenje istovremenih zahtevaOgraničite broj aktivnih radnika
Evidentiranje korišćenjaDa li se korišćenje računa po zahtevu, pošiljci ili drugoj jediniciProcenite potrošnju odvojeno od obima zahteva

Na primer, ako hipotetička krajnja tačka dozvoljava 25 zapisa po zahtevu, za 63 zapisa potrebna su tri zahteva koji sadrže 25, 25 i 13 zapisa. Ovi brojevi samo ilustruju podelu na delove; oni nisu navedena ograničenja za 17TRACK.

Nemojte pretpostaviti da paketna obrada smanjuje naplativo korišćenje. Ona može smanjiti opterećenje HTTP zahtevima, ali svaki uticaj na troškove zavisi od stvarnih pravila obračuna pružaoca usluge. Isto tako, važeća veličina paketa ne daje pravo na neograničene paralelne zahteve.

Pripremite zapise pre izgradnje zahteva

Većina izbegljivih grešaka u paketnoj obradi počinje pripremom ulaznih podataka. Proverite svaku pošiljku pre dodavanja u paket, ali izbegavajte pravila koja mogu slučajno odbaciti legitimne brojeve za praćenje različitih prevoznika.

  1. Čuvajte brojeve za praćenje kao stringove. Pretvaranje u brojeve može ukloniti početne nule ili promeniti duge identifikatore.
  2. Uklonite slučajne razmake na početku i kraju. Nemojte uklanjati unutrašnje znakove niti menjati velika i mala slova, osim ako relevantna specifikacija dozvoljava takvu normalizaciju.
  3. Proverite obavezna polja. Neki tokovi rada mogu zahtevati identifikator prevoznika ili dodatne informacije o pošiljci. Koristite samo dokumentovane nazive i vrednosti polja.
  4. Odredite jasan opseg uklanjanja duplikata. Ponovljeni broj za praćenje nije automatski duplikat kod svakog prevoznika, trgovca ili istorijske pošiljke.
  5. Čuvajte lokalni identifikator pošiljke. Sačuvajte vezu između poslate stavke i zapisa porudžbine ili pošiljke, čak i kada API ne prihvata prilagođena referentna polja.

Za Carrier Tracking kroz više mreža nemojte zaključivati o prevozniku samo na osnovu dužine ili prefiksa broja za praćenje, osim ako je takav zaključak pouzdan za vaš konkretni tok rada. Kada API podržava identifikaciju prevoznika, pratite njegovo dokumentovano ponašanje pri rešavanju nejasnoća.

Ilustrativna struktura zahteva

Sledeći JSON prikazuje koncept korisnog tereta paketnog zahteva. Omotač, nazivi svojstava i identifikatori su ilustrativni, a ne šema zahteva za 17TRACK. Neki API-ji očekuju niz na najvišem nivou umesto objekta koji sadrži niz.

{
  "shipments": [
    {
      "tracking_number": "EXAMPLE000001",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    },
    {
      "tracking_number": "EXAMPLE000002",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    }
  ]
}

Izgradite korisni teret pomoću JSON serijalizatora, umesto spajanja stringova. Šaljite akreditive za autentifikaciju putem dokumentovanog mehanizma i ne čuvajte ih u sistemu za kontrolu izvornog koda, kodu koji se isporučuje pregledaču ili u uobičajenim zapisnicima.

Obradite odgovor na dva nivoa

Paketni zahtev ima ishod na nivou transporta i ishod na nivou aplikacije. Vaša integracija mora proceniti oba.

Nivo 1: Da li je zahtev dobio upotrebljiv odgovor?

Počnite od HTTP statusa, zaglavlja odgovora i tela odgovora. Greške autentifikacije, neispravni zahtevi, ograničenje brzine i greške servera mogu sprečiti uobičajenu obradu stavki. Mrežno prekoračenje vremena je drugačije: klijent možda ne zna da li je server primio ili obradio zahtev.

HTTP semantika je definisana u RFC 9110. Međutim, dokumentacija pružaoca usluge određuje kako se njegova polja rezultata na nivou aplikacije mapiraju na stvarne ishode pošiljki.

Nivo 2: Šta se dogodilo sa svakom pošiljkom?

Ako odgovor podržava rezultate na nivou stavki, klasifikujte svaki poslati zapis. Nemojte pretpostaviti da HTTP 200 znači da je svaki zapis uspešan ili da lista rezultata čuva redosled zahteva, osim ako ugovor to izričito garantuje.

  • Prihvaćeno: Operacija je uspešna prema dokumentovanoj definiciji krajnje tačke.
  • Trajni ulazni neuspeh: Ispravite zapis ili ga istražite pre sledećeg pokušaja.
  • Neuspeh za ponovni pokušaj: Zakažite novi pokušaj u skladu sa smernicama pružaoca usluge.
  • Neizvestan ishod: Odgovor nedostaje, nepotpun je ili se ne može bezbedno povezati sa poslatim zapisom.

Odgovore poput „već registrovano“ ili druge slične odgovore povezane sa duplikatima držite odvojeno dok ne razumete njihovo dokumentovano značenje. Oni mogu ukazivati na to da željeno stanje već postoji, ali ih ne treba automatski tretirati kao potvrdu uspešnog vlasništva, konfiguracije ili pretplate.

Nakon obrade odgovora, svaki ulazni zapis treba da ima tačno jedan lokalni ishod. Korisna provera usklađivanja glasi: poslati zapisi jednaki su prihvaćenim zapisima plus trajni neuspesi plus neuspesi za ponovni pokušaj plus neizvesni ishodi. Ovo je lokalno pravilo obračuna, a ne obavezni format API odgovora.

Obradite delimične neuspehe bez ponovnog slanja uspešnih zapisa

Pretpostavimo da ilustrativni paket sadrži deset pošiljki: sedam je prihvaćeno, dve imaju nevažeća obavezna polja, a jedna nailazi na dokumentovanu privremenu grešku. Sačuvajte sedam uspešnih ishoda, prosledite dva nevažeća zapisa na ispravku i ponovite pokušaj samo za privremeno neuspešnu pošiljku.

Ponovno slanje svih deset zapisa stvara nepotreban saobraćaj i može otežati obradu duplikata. Takođe otežava razlikovanje prvobitnog odbijanja od kasnijeg odgovora povezanog sa duplikatom.

IshodPreporučena radnja
Nevažeće polje ili nepodržana vrednostIspravite ulaz; ne ponavljajte nepromenjen zahtev
Neuspeh autentifikacije ili dozvolaPauzirajte pogođeni rad i popravite akreditive ili pristup
Odgovor o ograničenju brzineOdgodite u skladu sa dokumentovanim smernicama i relevantnim zaglavljima odgovora
Privremena greška na nivou stavkePonovite pokušaj za tu stavku uz ograničen broj pokušaja i eksponencijalno čekanje
Prekoračenje vremena nakon slanjaOznačite kao neizvesno; uskladite ili koristite dokumentovane garancije bezbednosti ponovnog pokušaja
Neprepoznat ili nepotpun rezultatSačuvajte dokaze i istražite slučaj umesto da pretpostavite uspeh

HTTP 429 označava preveliki broj zahteva, a odgovor može sadržati zaglavlje Retry-After, kako je opisano u RFC 6585. Nemojte pretpostaviti da je to zaglavlje uvek prisutno. Kada nije naveden izričit period čekanja, koristite ograničenu politiku čekanja u skladu sa dokumentacijom API-ja.

Dodajte slučajnu vremensku komponentu kako biste rasporedili ponovne pokušaje više radnika, postavite maksimalan broj pokušaja ili maksimalnu starost ponovnog pokušaja i pošaljite zapise za koje su pokušaji iscrpljeni u red za proveru. Beskonačno ponavljanje može sakriti trajan problem sa konfiguracijom.

Zašto prekoračenja vremena zahtevaju poseban tretman

Prekoračenje vremena ne dokazuje odbijanje. Server je možda prihvatio paket pre nego što je veza prekinuta. Automatsko ponovno slanje zahteva koji menja stanje zato može ponoviti radnju.

Ako krajnja tačka podržava dokumentovane ključeve idempotentnosti, pratite njena pravila, uključujući opseg ključa i vreme čuvanja. Nemojte izmišljati idempotentno zaglavlje i pretpostaviti da ga server poštuje. U suprotnom, koristite podržani tok pretrage ili usklađivanja da utvrdite da li željeno stanje postoji pre ponovnog slanja. Lokalno uklanjanje duplikata pomaže u koordinaciji vaših radnika, ali ne garantuje idempotentnost na strani servera.

Praktičan tok rada paketne obrade

Detalje specifične za pružaoca usluge držite u adapteru kako red čekanja, planer ponovnih pokušaja i logika nadzora ne bi zavisili od sirovih naziva polja u odgovorima.

validate records and retain local shipment IDs
resolve duplicates within the intended business scope
split records using documented item and payload limits

for each batch through a bounded worker pool:
    persist an attempt record before sending
    wait for the shared rate limiter
    send using the provider-specific adapter

    if the outcome is uncertain:
        enqueue reconciliation
        continue

    classify request-level and item-level outcomes
    persist one outcome for every submitted record
    schedule only eligible failures for retry
    route invalid or exhausted records for review

Omogućite oporavak čuvanja ishoda i zakazivanja ponovnih pokušaja. Na primer, trajni zapis posla ili transakcioni obrazac stavljanja u red može sprečiti da pad procesa izgubi odluku o ponovnom pokušaju. Kada se radnici ponovo pokrenu, treba da mogu razlikovati neposlati rad od rada čiji je udaljeni ishod još neizvestan.

Veličinu paketa koristite kao podesivu postavku povezanu sa relevantnom krajnjom tačkom, a ne kao konstantu rasutu po bazi koda. Manji paket može biti koristan pri rešavanju problema ili izolovanju problematičnih zapisa; najveći dozvoljeni paket nije automatski i najbolja radna veličina.

Nadzirite ishode pošiljki, a ne samo dostupnost HTTP-a

API Monitoring treba da pokaže da li pošiljke dostižu željeno stanje. Kontrolna tabla koja prikazuje samo stope uspešnih HTTP zahteva može propustiti delimične neuspehe unutar inače uspešnih odgovora.

  • Stopa prihvatanja stavki: Prihvaćeni zapisi podeljeni brojem poslatih zapisa, uz jasno definisan tretman ponovnih pokušaja.
  • Raspodela grešaka: Brojevi po krajnjoj tački, dokumentovanom kodu greške i relevantnom kontekstu prevoznika.
  • Neizvesni ishodi: Neusaglašeni zapisi i vreme tokom kog su ostali nerešeni.
  • Zaostatak ponovnih pokušaja: Čekajući ponovni pokušaji, starost najstarijeg ponovnog pokušaja i iscrpljeni pokušaji.
  • Stanje zahteva: Latencija, prekoračenja vremena, ograničenje brzine i greške servera.
  • Svežina praćenja: Da li prihvaćene pošiljke naknadno dobijaju upotrebljive informacije o praćenju.

Prihvatanje registracije nije dokaz novog skeniranja kod prevoznika. Status obrade API-ja držite odvojeno od kretanja pošiljke i svežine podataka, kako se incident integracije ne bi pomešao sa kašnjenjem isporuke.

Zabeležite lokalne ID-jeve paketa, reference pošiljki, broj pokušaja, dokumentovane kodove grešaka i ID-jeve zahteva pružaoca usluge kada su dostupni. Sakrijte akreditive i nepotrebne lične podatke. Identifikatore praćenja koristite samo kada su operativno neophodni i izbegavajte postavljanje sirovih identifikatora pošiljki u oznake metrika velike kardinalnosti.

Testirajte ove slučajeve pre produkcije

Koristite dokumentovano sandbox ili kontrolisano testno okruženje kada je dostupno. Nemojte pretpostaviti da će izmišljeni brojevi za praćenje proizvesti predvidljive produkcione odgovore.

  1. Pošaljite važeći paket na dokumentovanom ograničenju broja stavki, a zatim testirajte kako klijent sprečava preveliki paket.
  2. Proverite da li brojevi za praćenje sa početnim nulama preživljavaju serijalizaciju i čuvanje.
  3. Testirajte mešavinu prihvaćenih i odbijenih stavki bez ponovnog slanja uspešnih zapisa.
  4. Simulirajte ograničenje brzine i potvrdite da više radnika poštuje isto ograničenje.
  5. Simulirajte prekoračenje vremena nakon slanja i proverite tok usklađivanja.
  6. Ponovo pokrenite radnika između prijema odgovora i lokalnog čuvanja.
  7. Testirajte nedostajuće, nepoznate ili rezultate stavki koje nije moguće povezati.
  8. Potvrdite da nevažeći zapisi dospevaju u vidljiv red za ispravke, umesto da se pokušaji ponavljaju zauvek.

Integracija spremna za produkciju može objasniti stanje svake poslate pošiljke, uključujući one čiji je ishod privremeno nepoznat. Smanjenje broja zahteva je korisno; očuvanje te odgovornosti važniji je cilj dizajna.

Česta pitanja

Koliko brojeva za praćenje mogu da pošaljem u jednom zahtevu?

Koristite ograničenje dokumentovano za tačnu krajnju tačku i verziju API-ja. Takođe proverite veličinu zahteva, ograničenja brzine i sva ograničenja specifična za nalog. Ne postoji bezbedan univerzalan broj koji se može primeniti na sve API-je za praćenje ili na različite operacije unutar jednog API-ja.

Može li jedan nevažeći broj za praćenje prouzrokovati neuspeh celog paketa?

Da, u zavisnosti od pravila validacije krajnje tačke. Neki API-ji vraćaju pojedinačna odbijanja, dok drugi mogu odbiti zahtev pre obrade stavki. Proverite i greške na nivou zahteva i rezultate na nivou stavki; nemojte pretpostaviti da svaka paketna krajnja tačka podržava delimično prihvatanje.

Da li treba ponovo da pošaljem paket kada je HTTP odgovor uspešan?

Ne automatski. Najpre analizirajte dokumentovani status na nivou aplikacije i rezultate stavki. Sačuvajte uspešne zapise i ponovite pokušaj samo za greške koje ispunjavaju uslove. Ako se rezultat ne može bezbedno protumačiti, klasifikujte ga kao neizvestan i istražite.

Mogu li da mešam prevoznike u istom paketu?

Samo kada krajnja tačka podržava takvu strukturu zahteva. Potvrdite da li se informacije o prevozniku navode za svaku pošiljku, da li je podržana automatska identifikacija i šta se dešava kada je identifikacija nejasna. Usluga za više prevoznika sama po sebi ne potvrđuje pravila paketne obrade svake krajnje tačke.

Da li paketna obrada ubrzava pristizanje ažuriranja praćenja?

Paketna obrada može smanjiti broj zahteva koje vaša aplikacija šalje, ali sama po sebi ne omogućava da događaji prevoznika stignu ranije. Registracija, preuzimanje podataka, dostupnost skeniranja kod prevoznika i isporuka ažuriranja zasebni su delovi toka rada.

Izvori