Skip to main content
EtusivuBlogiOppaatKuinka lähettää useita seurantatunnuksia yhdessä API-pyynnössä (eräkohtaiset rajoitukset ja osittaiset epäonnistumiset)

Kuinka lähettää useita seurantatunnuksia yhdessä API-pyynnössä (eräkohtaiset rajoitukset ja osittaiset epäonnistumiset)

17TRACK

Jos haluat lähettää useita seurantanumeroita yhdessä API-pyynnössä, käytä Tracking API -päätepistettä, joka hyväksyy erän nimenomaisesti, muotoile jokainen lähetys sen pyyntöskeeman mukaisesti ja jaa suuremmat luettelot dokumentoitujen rajojen mukaisiin eriin. Tarkista sen jälkeen sekä HTTP-vastaus että jokaisen lähetyksen tulos: onnistunut HTTP-pyyntö ei välttämättä tarkoita, että kaikki seuranumerot hyväksyttiin. Yritä uudelleen vain siihen oikeutettuja epäonnistuneita lähetyksiä ja selvitä epävarmat tulokset ennen koko erän lähettämistä uudelleen.

Useiden seuranumeroiden lähettäminen yhdessä API-pyynnössä

Tämä opas on tarkoitettu kehittäjille, jotka yhdistävät lähetysten seurannan tilaustenhallintajärjestelmään, varastoalustaan, verkkokauppasovellukseen tai sisäiseen hallintapaneeliin. Tavoitteena ei ole ainoastaan lähettää vähemmän pyyntöjä, vaan käsitellä jokainen lähetys ilman päällekkäistä työtä tai epäonnistuneiden tietueiden menettämistä.

Tunnista ensin, mitä eräpäätepiste todella tekee

Seurannan integrointi voi sisältää useita erillisiä toimintoja. Lähetysten rekisteröinti, niiden uusimpien seurantatietojen hakeminen ja myöhempien päivitysten vastaanottaminen eivät ole keskenään vaihdettavia toimintoja.

  • Rekisteröinti: Lähetysten lähettäminen palveluun, jotta se voi aloittaa tai ylläpitää niiden seurantaa.
  • Haku: Lähetysten seurantatietojen pyytäminen päätepisteen hakusääntöjen mukaisesti.
  • Toimituksen päivitys: Myöhempien muutosten vastaanottaminen tuetulla tavalla, kuten webhookien kautta, tai niiden hakeminen ajoitetuilla pyynnöillä.

Tarkista dokumentaatiosta tarvitsemasi tarkka toiminto. Useita tietueita hyväksyvä rekisteröintipäätepiste ei tarkoita, että hakupäätepiste hyväksyy saman määrän, käyttää samaa skeemaa tai noudattaa samaa nopeusrajoitusta.

Jos kyseessä on 17TRACK-integraatio, aloita Tracking API -tuotesivulta ja varmista toiminto, todennusmenetelmä, pyyntömuoto sekä vastauskentät virallisesta API-dokumentaatiosta. Käsittele alla olevia esimerkkejä toteutusmalleina, ei kyseisen API-sopimuksen korvikkeena.

Erärajoitukset ovat muutakin kuin lähetysten enimmäismäärä

Tracking API:lle ei ole yleispätevää erärajoitusta. Rajat voivat vaihdella palveluntarjoajan, päätepisteen, API-version ja tilin asetusten mukaan. Tallenna nämä rajoitteet erikseen ennen eräkäsittelyn toteuttamista.

RajoiteMitä on vahvistettavaVaikutus toteutukseen
Kohteet pyyntöä kohtiTietyn toiminnon sallima tietueiden enimmäismääräJaa syöteluettelo ennen lähettämistä
Pyynnön rungon kokoDokumentoitu tavurajoitusHuomioi valinnaiset kentät ja sarjallistamisen koko
PyyntötahtiSallittujen pyyntöjen määrä tietyllä aikavälilläRytmitä pyynnöt yhteisen rajoittimen avulla
SamanaikaisuusMahdollinen samanaikaisten pyyntöjen rajoitusRajoita aktiivisten työntekijöiden määrää
Käytön laskentaLasketaanko käyttö pyyntöjen, lähetysten vai jonkin muun yksikön perusteellaArvioi kulutus erikseen pyyntömäärästä

Jos esimerkiksi kuvitteellinen päätepiste sallii 25 tietuetta pyyntöä kohti, 63 tietuetta vaatii kolme pyyntöä, joissa on 25, 25 ja 13 tietuetta. Nämä luvut havainnollistavat vain jakamista; ne eivät ole ilmoitettuja 17TRACK-rajoja.

Älä oleta, että erien käyttö vähentää laskutettavaa käyttöä. Se voi vähentää HTTP-pyyntöjen aiheuttamaa kuormaa, mutta vaikutus veloituksiin riippuu palveluntarjoajan todellisista laskentasäännöistä. Samoin kelvollinen eräkoko ei oikeuta rajattomaan rinnakkaisten pyyntöjen määrään.

Valmistele tietueet ennen pyynnön muodostamista

Useimmat vältettävissä olevat erävirheet alkavat syötteen valmistelusta. Vahvista jokainen lähetys ennen sen lisäämistä erään, mutta vältä sääntöjä, jotka hylkäävät vahingossa eri kuljetusyhtiöiden laillisia seuranumeroita.

  1. Säilytä seuranumerot merkkijonoina. Niiden muuntaminen numeroiksi voi poistaa alkunollat tai muuttaa pitkiä tunnisteita.
  2. Poista vahingossa mukana olevat ympäröivät välilyönnit. Älä poista sisäisiä merkkejä tai muuta kirjainkokoa, ellei asiaankuuluva määrittely salli tällaista normalisointia.
  3. Vahvista pakolliset kentät. Jotkin työnkulut voivat vaatia kuljetusyhtiön tunnisteen tai muita lähetystietoja. Käytä vain dokumentoituja kenttänimiä ja arvoja.
  4. Määritä deduplikoinnin laajuus erikseen. Toistuva seuranumero ei automaattisesti ole kaksoiskappale kaikkien kuljetusyhtiöiden, kauppiaiden tai aiempien lähetysten yhteydessä.
  5. Säilytä paikallinen lähetyksen tunniste. Tallenna lähtevän kohteen ja tilaus- tai lähetystietueesi välinen yhteys, vaikka API ei hyväksyisi mukautettuja viitekenttiä.

Kun käytät Carrier Tracking -seurantaa useissa verkoissa, älä päättele kuljetusyhtiötä pelkästään seuranumeron pituuden tai etuliitteen perusteella, ellei päättely ole luotettava juuri kyseisessä työnkulussa. Jos API tukee kuljetusyhtiön tunnistamista, noudata sen dokumentoitua toimintaa epäselvissä tapauksissa.

Esimerkinomainen pyyntörakenne

Seuraava JSON havainnollistaa erähyötykuorman käsitettä. Ympäröivä rakenne, ominaisuuksien nimet ja tunnisteet ovat esimerkinomaisia eivätkä muodosta 17TRACK-pyyntöskeemaa. Jotkin API:t odottavat ylimmän tason taulukkoa sellaisen objektin sijaan, joka sisältää taulukon.

{
  \u0022shipments\u0022: [
    {
      \u0022tracking_number\u0022: \u0022EXAMPLE000001\u0022,
      \u0022carrier_id\u0022: \u0022DOCUMENTED_CARRIER_ID\u0022
    },
    {
      \u0022tracking_number\u0022: \u0022EXAMPLE000002\u0022,
      \u0022carrier_id\u0022: \u0022DOCUMENTED_CARRIER_ID\u0022
    }
  ]
}

Muodosta hyötykuorma JSON-sarjallistajan avulla merkkijonojen yhdistämisen sijaan. Lähetä todennustiedot dokumentoidulla tavalla ja pidä ne poissa lähdekoodin hallinnasta, selaimelle toimitettavasta koodista ja tavallisista lokeista.

Käsittele vastaus kahdella tasolla

Eräpyynnöllä on siirtotason tulos ja sovellustason tulos. Integraation on arvioitava molemmat.

Taso 1: Saiko pyyntö käyttökelpoisen vastauksen?

Aloita HTTP-tilasta, vastausotsakkeista ja vastausrungosta. Todennusvirheet, virheelliset pyynnöt, nopeusrajoitukset ja palvelinvirheet voivat estää normaalin kohteiden käsittelyn. Verkon aikakatkaisu on erilainen tapaus: asiakas ei ehkä tiedä, vastaanottiko tai käsitteliko palvelin pyynnön.

HTTP-semantiikka määritellään dokumentissa RFC 9110. Palveluntarjoajan dokumentaatio kuitenkin määrittää, miten sovellustason tuloskentät vastaavat todellisia lähetysten tuloksia.

Taso 2: Mitä kullekin lähetykselle tapahtui?

Jos vastaus tukee kohdetason tuloksia, luokittele jokainen lähetetty tietue. Älä oleta, että HTTP 200 tarkoittaa jokaisen tietueen onnistumista tai että tulosluettelo säilyttää pyyntöjärjestyksen, ellei sopimus sitä nimenomaisesti takaa.

  • Hyväksytty: Toiminto onnistui päätepisteen dokumentoidun määritelmän mukaisesti.
  • Pysyvä syötevirhe: Korjaa tietue tai tutki sitä ennen uutta yritystä.
  • Uudelleenyrityskelpoinen virhe: Ajoita uusi yritys palveluntarjoajan uudelleenyritysohjeiden mukaisesti.
  • Tuntematon tulos: Vastaus puuttuu, on puutteellinen tai sitä ei voida turvallisesti yhdistää lähetettyyn tietueeseen.

Pidä ”jo rekisteröity” ja vastaavat kaksoiskappaleisiin liittyvät vastaukset erillään, kunnes ymmärrät niiden dokumentoidun merkityksen. Ne voivat tarkoittaa, että haluttu tila on jo olemassa, mutta niitä ei pidä automaattisesti käsitellä onnistuneena omistajuuden, asetusten tai tilauksen vahvistuksena.

Vastauksen käsittelyn jälkeen jokaisella syötetietueella tulisi olla täsmälleen yksi paikallinen tulos. Hyödyllinen täsmäytystarkistus on: lähetetyt tietueet = hyväksytyt tietueet + pysyvät virheet + uudelleenyrityskelpoiset virheet + tuntemattomat tulokset. Tämä on paikallinen laskentasääntö, ei vaadittu API-vastausmuoto.

Käsittele osittaiset virheet toistamatta onnistuneita tietueita

Oletetaan, että esimerkkierässä on kymmenen lähetystä: seitsemän hyväksytään, kahdessa on virheellisiä pakollisia kenttiä ja yhdessä ilmenee dokumentoitu väliaikainen virhe. Tallenna seitsemän onnistunutta tulosta, ohjaa kaksi virheellistä tietuetta korjattaviksi ja yritä uudelleen vain väliaikaista virhettä.

Kaikkien kymmenen tietueen lähettäminen uudelleen aiheuttaa tarpeetonta liikennettä ja voi vaikeuttaa kaksoiskappaleiden käsittelyä. Lisäksi alkuperäisen hylkäyksen erottaminen myöhemmästä kaksoiskappaleisiin liittyvästä vastauksesta vaikeutuu.

TulosSuositeltu toimenpide
Virheellinen kenttä tai tukematon arvoKorjaa syöte; älä yritä muuttamatta sitä
Todennus- tai käyttöoikeusvirheKeskeytä kyseinen työ ja korjaa tunnistetiedot tai käyttöoikeudet
NopeusrajoitusvastausOdota dokumentoidun ohjeistuksen ja soveltuvien vastausotsakkeiden mukaisesti
Väliaikainen kohdetason virheYritä kyseistä kohdetta uudelleen rajatulla yritysmäärällä ja viiveellä
Aikakatkaisu lähettämisen jälkeenMerkitse epävarmaksi; täsmäytä tulos tai käytä dokumentoituja uudelleenyrityksen turvallisuustakuita
Tunnistamaton tai puutteellinen tulosSäilytä todisteet ja tutki asiaa sen sijaan, että olettaisit onnistumisen

HTTP 429 tarkoittaa liian montaa pyyntöä, ja vastaus voi sisältää Retry-After-otsakkeen, kuten dokumentissa RFC 6585 kuvataan. Älä oleta, että otsake on aina mukana. Jos erillistä uudelleenyritysviivettä ei ilmoiteta, käytä rajattua viivekäytäntöä API-dokumentaation mukaisesti.

Lisää hajontaa, jotta useiden työntekijöiden uudelleenyritykset jakautuvat, määritä yritysten enimmäismäärä tai uudelleenyritysten enimmäisikä ja lähetä loppuun käytetyt tietueet tarkistusjonoon. Rajaton uudelleen yrittäminen voi peittää pysyvän asetusten määritysongelman.

Miksi aikakatkaisut vaativat erityiskäsittelyä

Aikakatkaisu ei todista hylkäystä. Palvelin on voinut hyväksyä erän ennen yhteyden katkeamista. Tilaa muuttavan pyynnön automaattinen uudelleenlähetys voi siksi toistaa työn.

Jos päätepiste tukee dokumentoituja idempotenssiavaimia, noudata sen sääntöjä, mukaan lukien avaimen laajuus ja säilytysaika. Älä keksi idempotenssiotsaketta ja oleta palvelimen tukevan sitä. Käytä muuten tuettua hakua tai täsmäytysprosessia selvittääksesi, onko haluttu tila olemassa, ennen uudelleenlähetystä. Paikallinen deduplikointi auttaa koordinoimaan omia työntekijöitä, mutta ei takaa palvelinpuolen idempotenssia.

Käytännöllinen eräkäsittelyn työnkulku

Säilytä palveluntarjoajakohtaiset yksityiskohdat sovittimessa, jotta jono, uudelleenyritysten ajoitus ja valvontalogiikka eivät riipu raakojen vastauskenttien nimistä.

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

Tee tulosten tallennuksesta ja uudelleenyritysten ajoituksesta palautuvaa. Esimerkiksi pysyvä työ tietueena tai tapahtumankäsittelyyn perustuva jonotusmalli voi estää prosessin kaatumista hukkaamasta uudelleenyrityspäätöstä. Työntekijöiden käynnistyessä uudelleen niiden on pystyttävä erottamaan lähettämätön työ työstä, jonka etätulos on edelleen epävarma.

Käytä eräkokoa määritettävänä asetuksena, joka on sidottu asiaankuuluvaan päätepisteeseen, älä kaikkialle koodipohjaan hajautettuna vakiona. Pienempi erä voi olla hyödyllinen vianmäärityksessä tai ongelmallisten tietueiden eristämisessä; suurin sallittu erä ei automaattisesti ole paras toimintakoko.

Valvo lähetysten tuloksia, ei vain HTTP-käytettävyyttä

API Monitoring -valvonnan tulisi näyttää, saavuttavatko lähetykset tavoitellun tilan. Koontinäyttö, joka raportoi vain HTTP-onnistumisasteen, voi jättää onnistuneiden vastausten sisäiset osittaiset virheet huomaamatta.

  • Kohteiden hyväksymisaste: Hyväksyttyjen tietueiden määrä jaettuna lähetettyjen tietueiden määrällä, ja uudelleenyritysten käsittely määriteltynä selkeästi.
  • Virheiden jakauma: Määrät päätepisteen, dokumentoidun virhekoodin ja asiaankuuluvan kuljetusyhtiökontekstin mukaan.
  • Tuntemattomat tulokset: Täsmäyttämättömät tietueet ja niiden selvittämättäoloaika.
  • Uudelleenyritysjonon koko: Odottavat uudelleenyritykset, vanhimman uudelleenyrityksen ikä ja loppuun käytetyt yritykset.
  • Pyyntöjen tila: Viive, aikakatkaisut, nopeusrajoitukset ja palvelinvirheet.
  • Seurantatietojen ajantasaisuus: Saavatko hyväksytyt lähetykset myöhemmin käyttökelpoisia seurantatietoja.

Rekisteröinnin hyväksyminen ei todista uutta kuljetusyhtiön skannausta. Pidä API-käsittelyn tila erillään lähetyksen liikkeestä ja tietojen ajantasaisuudesta, jotta integraatiohäiriötä ei sekoiteta toimitusviiveeseen.

Kirjaa paikalliset erätunnukset, lähetysviitteet, yrityskerrat, dokumentoidut virhekoodit ja palveluntarjoajan pyyntötunnukset, kun ne ovat saatavilla. Piilota tunnistetiedot ja tarpeettomat henkilötiedot. Käytä seurantatunnisteita vain, kun se on toiminnan kannalta tarpeellista, ja vältä raakojen lähetystunnisteiden sijoittamista korkean kardinaliteetin metriikkatunnisteisiin.

Testaa nämä tapaukset ennen tuotantoa

Käytä dokumentoitua hiekkalaatikkoa tai hallittua testiympäristöä, jos sellainen on saatavilla. Älä oleta, että keksityt seuranumerot tuottavat ennakoitavia tuotantovastauksia.

  1. Lähetä kelvollinen erä dokumentoidulla kohderajalla ja testaa sitten, miten asiakas estää liian suuren erän.
  2. Varmista, että alkunollia sisältävät seuranumerot säilyvät sarjallistamisen ja tallennuksen aikana.
  3. Testaa hyväksyttyjen ja hylättyjen kohteiden yhdistelmä ilman onnistuneiden tietueiden uudelleenyritystä.
  4. Simuloi nopeusrajoitus ja varmista, että useat työntekijät noudattavat samaa rajaa.
  5. Simuloi lähettämisen jälkeinen aikakatkaisu ja varmista täsmäytyspolku.
  6. Käynnistä työntekijä uudelleen vastauksen vastaanottamisen ja paikallisen tallennuksen välissä.
  7. Testaa puuttuvat, tuntemattomat tai yhdistämättömissä olevat kohdetulokset.
  8. Varmista, että virheelliset tietueet päätyvät näkyvään korjausjonoon eivätkä uudelleenyritykseen ikuisesti.

Tuotantovalmis integraatio pystyy selittämään jokaisen lähetetyn lähetyksen tilan, myös niiden, joiden tulos on tilapäisesti tuntematon. Pyyntöjen määrän vähentäminen on hyödyllistä, mutta vastuun säilyttäminen on tärkeämpi suunnittelutavoite.

Usein kysytyt kysymykset

Kuinka monta seuranumeroa voin lähettää yhdessä pyynnössä?

Käytä juuri kyseiselle päätepisteelle ja API-versiolle dokumentoitua rajaa. Tarkista myös pyynnön koko, nopeusrajoitukset ja tilikohtaiset rajoitteet. Tracking API -rajapinnoille tai yhden API:n eri toiminnoille ei ole turvallista yleislukua.

Voiko yksi virheellinen seuranumero aiheuttaa koko erän epäonnistumisen?

Kyllä, päätepisteen validointisäännöistä riippuen. Jotkin API:t palauttavat yksittäisiä hylkäyksiä, kun taas toiset voivat hylätä pyynnön ennen kohteiden käsittelyä. Tarkista sekä pyyntötason virheet että kohdetason tulokset; älä oleta, että jokainen eräpäätepiste tukee osittaista hyväksyntää.

Pitäisikö minun yrittää erää uudelleen, kun HTTP-vastaus onnistuu?

Ei automaattisesti. Jäsennä ensin dokumentoitu sovellustason tila ja kohdetulokset. Tallenna onnistuneet tietueet ja yritä uudelleen vain siihen oikeutettuja epäonnistuneita tietueita. Jos tulosta ei voida tulkita turvallisesti, luokittele se epävarmaksi ja tutki asia.

Voinko yhdistää eri kuljetusyhtiöitä samaan erään?

Vain jos päätepiste tukee kyseistä pyyntörakennetta. Vahvista, toimitetaanko kuljetusyhtiön tiedot lähetyskohtaisesti, tuetaanko automaattista tunnistamista ja mitä tapahtuu tunnistamisen ollessa epäselvä. Usean kuljetusyhtiön palvelu ei yksin määritä kaikkien päätepisteiden eräsääntöjä.

Saapuvatko seurantapäivitykset nopeammin erien avulla?

Erät voivat vähentää sovelluksesi lähettämien pyyntöjen määrää, mutta ne eivät itsessään saa kuljetusyhtiön tapahtumia näkymään aikaisemmin. Rekisteröinti, tietojen haku, kuljetusyhtiön skannausten saatavuus ja päivitysten toimitus ovat työnkulun erillisiä osia.

Lähteet