Skip to main content
EtusivuBlogiOppaat15 kysymystä, jotka kannattaa esittää seuranta-API-palveluntarjoajalle ennen tuotantoon siirtymistä

15 kysymystä, jotka kannattaa esittää seuranta-API-palveluntarjoajalle ennen tuotantoon siirtymistä

17TRACK

Ennen kuin viet seurantaan tarkoitetun API:n tuotantoon, selvitä, miten se käsittelee todellisia kuljetusyhtiöitäsi ja lähetystyyppejäsi, mitä sen tapahtumat tarkoittavat, miten päivitykset saapuvat ja mitä tapahtuu, kun tiedot tai integraatio eivät toimi. Alla olevat 15 kysymystä tarjoavat suunnittelu- ja operatiivisille tiimeille käytännöllisen tavan testata nämä vastaukset ennen kuin asiakkaat, tukihenkilöt tai automatisoidut työnkulut alkavat luottaa niihin.

15 kysymystä, jotka kannattaa esittää seurantapalvelun API-palveluntarjoajalle ennen käyttöönottoa

Onnistunut esittely ei ole tuotantotesti. Käytä edustavaa otosta lähetyksistä, mukaan lukien viivästyneet, palautetut ja vaikeasti tunnistettavat paketit. Pyydä jokaisesta vastauksesta dokumentaatio, esimerkkipayload tai testitulos. Kirjaa kaikki ratkaisemattomat asiat vastuuhenkilöineen ja päätöspäivineen sen sijaan, että olettaisit niiden ratkeavan käyttöönoton jälkeen.

Aloita lähetyssopivuudesta ja tietojen merkityksestä

1. Mitä todellisista lähetyksistämme voitte seurata, ja mitä kattavuus tarkoittaa?

Anna palveluntarjoajalle näyte käyttämistäsi kuljetusyhtiöistä, palveluista, lähtö- ja määränpääpareista sekä seurantanumeromuodoista. Pyydä sitä ilmoittamaan, mitkä lähetykset se voi hyväksyä, mitkä kuljetusyhtiöt se tunnistaa automaattisesti ja missä sinun on annettava kuljetusyhtiön koodi. Kuljetusyhtiön esiintyminen luettelossa ei osoita, että jokainen palvelu, luovutus tai lähetystyyppi tuottaa sovelluksesi tarvitsemat tapahtumat.

Testaa todellisia esimerkkejä suurivolyymisistä reiteistä ja toiminnan poikkeustilanteista. Sisällytä lähetys, joka vaihtaa kuljetusyhtiötä kuljetuksen aikana, jos näin tapahtuu liiketoiminnassasi. Kirjaa, hylkääkö API lähetyksen, hyväksyykö se sen löytämättä tapahtumia vai palauttaako se tapahtumia rajallisilla tiedoilla. Nämä tilanteet edellyttävät erilaisia käsittelytapoja tilaustenhallintajärjestelmässä.

2. Mitä lähetyksen rekisteröiminen edellyttää, ja miten estätte päällekkäiset rekisteröinnit?

Selvitä vaaditut tunnisteet, kuljetusyhtiön valintasäännöt, rekisteröinnin ajoitus sekä virheellisen tai vielä aktivoitumattoman seurantanumeron käsittely. Kysy, riittääkö käyttötapauksessasi pelkkä seurantanumero vai tarvitaanko lisätietoja. Varmista, mitä tapahtuu, jos sama lähetys lähetetään kahdesti joko samasta järjestelmästä tai erillisistä palveluista.

Rakenna yksi rekisteröintikulku, jossa vastuut ovat selkeät: mikä järjestelmä lähettää lähetykset, mikä tallentaa palveluntarjoajan tunnisteen ja mikä yrittää uudelleen epävarman lähetyksen. Jos pyyntö aikakatkaistaan sen jälkeen, kun palveluntarjoaja on käsitellyt sen, sokea uudelleenyritys ei saa huomaamatta luoda toista tietuetta tai päällekkäisiä jatkoilmoituksia.

3. Mitä tilannekuvauksenne tarkoittavat, ja voimmeko tarkastella taustalla olevia kuljetusyhtiön tapahtumia?

Pyydä tilannesanasto ja edustavia raakatapahtumia. Ilmaisut kuten kuljetuksessa, jakelussa, poikkeus, toimitettu ja palautettu ovat hyödyllisiä yhteenvetoja, mutta liiketoimintasääntösi saattavat tarvita enemmän yksityiskohtia. Selvitä, toimittaako palveluntarjoaja alkuperäiset kuljetusyhtiön kuvaukset standardoitujen tilojen rinnalla ja miten se käsittelee tapahtuman, joka ei sovi selkeästi mihinkään luokkaan.

Sopikaa omasta sisäisestä tilamallistanne ennen käyttöönottoa. Päättäkää erityisesti, mikä tapahtuma voi sulkea lähetyksen, käynnistää toimitusviestin tai aloittaa poikkeustyönkulun. Älkää pitäkö laajaa tilatunnistetta todisteena tietystä fyysisestä tapahtumasta, ellei taustalla oleva tieto tue tätä tulkintaa.

4. Mitä aikaleimoja ja sijainteja toimitetaan, ja miten niitä pitäisi tulkita?

Erottakaa jokaisen tapahtuman kohdalla aika, jolloin kuljetusyhtiö ilmoittaa sen tapahtuneen, ajasta, jolloin palveluntarjoaja vastaanotti tai julkaisi sen. Kysy aikavyöhykkeistä, puuttuvista poikkeamista, sijainnin tarkkuudesta ja päivityksistä, jotka saapuvat myöhempien tapahtumien jälkeen. Äskettäin vastaanotettu tapahtuma voi kuvata vanhempaa skannausta; pelkkä vastaanottoajan mukaan lajittelu voi tuottaa harhaanjohtavan aikajanan.

Testaa payload tietokantakaavaasi ja asiakkaille näkyvää esitystapaa vasten. Päätä, miten tapahtuma näytetään, kun sen paikallisesta aikavyöhykkeestä ei ole varmuutta, ja vältä tarkan toimitusajan tai sijainnin esittämistä, jos lähde ei niitä ilmoita.

5. Miten poikkeukset, palautukset ja toimitustodisteet esitetään?

Pyydä esimerkkejä epäonnistuneista toimitusyrityksistä, tullipysäytyksistä, osoiteongelmista, lähettäjälle palautuvista lähetyksistä ja toimitetuista lähetyksistä. Kysy, mitkä tiedot ovat standardoituja, mitkä ovat kuljetusyhtiökohtaisia ja sisältääkö toimitusvahvistus tapauksissa, jotka ovat sinulle tärkeitä, tukevia todisteita. Älä oleta, että toimitettu-tila sisältää vastaanottajan nimen, allekirjoituksen, valokuvan tai muun todisteen.

Yhdistä jokainen poikkeus vastuuhenkilön tehtävään. Jotkin tapahtumat edellyttävät tukitiimin tarkastelua, kun taas toiset eivät vaadi asiakasviestiä ennen lisätietojen saapumista. Jos toimitustodiste on tarpeen riidanratkaisutyönkulussa, tee sen saatavuudesta ja muodosta erillinen hyväksymiskriteeri sen sijaan, että pitäisit sitä oletusarvoisesti osana seurantakattavuutta.

Testaa, miten päivitykset saavuttavat järjestelmäsi

6. Toimitatteko päivitykset webhookeilla, kyselyillä vai molemmilla, ja milloin kumpaakin pitäisi käyttää?

Pyydä dokumentoitu toimitusmalli, payload-esimerkit, tilauksen määritys ja ohjeet puuttuvien päivitysten palauttamiseen. Jos webhookeja tarjotaan, selvitä, ilmoittavatko ne muuttuneesta lähetyksestä, tarjoavatko ne täydellisen tilannekuvan vai välittävätkö ne yksittäisen tapahtuman. Jos kyselyitä tarvitaan tai käytetään varamenetelmänä, selvitä sopiva pyyntömalli ja tapa tunnistaa muuttuneet tietueet.

Valitse malli työnkulun perusteella. Asiakkaille näkyvä aikajana voi sietää erilaista päivitysviivettä kuin poikkeusjono. Arkkitehtuurisi ei saa luvata välittömiä hälytyksiä vain siksi, että integraatio käyttää webhookeja: kuljetusyhtiön on ensin asetettava tapahtuma saataville, ja jokaisen seuraavan järjestelmän on käsiteltävä se.

7. Mitä tapahtuu, kun ilmoitukset ovat päällekkäisiä, viivästyneitä tai saapuvat väärässä järjestyksessä?

Kysy, yrittääkö palveluntarjoaja epäonnistuneita toimituksia uudelleen, kuinka pitkään ja minkä vastauksen se odottaa päätepisteeltäsi. Pyydä vakaa tapahtuma- tai lähetyskohtainen tunniste, jos sellainen on saatavilla. Testaa sitten sama ilmoitus kahdesti, lähetä vanhempi tapahtuma uudemman jälkeen ja palauta väliaikaisesti virhe päätepisteeltäsi.

Vastaanottimesi tulee kuitata vain se, minkä se on turvallisesti hyväksynyt, käsitellä uudelleenyritykset toistamatta asiakasviestejä ja rakentaa oikea aikajana uudelleen, kun tapahtumat saapuvat väärässä järjestyksessä. Jos ehdotettu suunnittelu perustuu siihen, että jokainen ilmoitus toimitetaan täsmälleen kerran, kyseenalaista tämä oletus ennen julkaisua.

8. Miten mittaamme tietojen tuoreutta, ja mitkä tekijät vaikuttavat siihen?

Kysy, mitä palveluntarjoaja voi mitata kussakin vaiheessa: kuljetusyhtiön tapahtuma-aika, palveluntarjoajan vastaanottoaika ja toimitusaika järjestelmääsi. Erota nämä mittaukset kaikista palveluntarjoajan antamista sitoumuksista. Pitkä viive fyysisen liikkeen ja sovelluksesi päivityksen välillä voi syntyä lähdejärjestelmässä, palveluntarjoajan käsittelyssä tai omassa jonossasi.

Mittaa pilottijakson aikana nämä viiveet edustavista lähetyksistä ja tutki poikkeamat. Aseta hälytysrajat sen mukaan, mitä työnkulkusi todella edellyttää. Jos viivästynyt skannaus voisi aiheuttaa haitallisen asiakasviestin tai jääneen eskaloinnin, määritä varamenetelmäksi esimerkiksi vanhentuneiden tietojen tunniste tai manuaalinen tarkistus.

9. Miten API-tunnistetiedot ja webhook-pyynnöt suojataan?

Pyydä todennus- ja tunnistetietojen hallintaa koskeva dokumentaatio. Varmista, miten tunnistetiedot myönnetään, rajataan, vaihdetaan ja peruutetaan, ovatko testi- ja tuotantotunnistetiedot erillisiä ja miten webhook-vastaanotin voi varmistaa pyynnön aitouden. Kysy myös, mitä suojauksia on saatavilla uudelleenlähetettyjä webhook-pyyntöjä vastaan.

Pyydä tietoturvatiimiä tarkastamaan ehdotettu toteutus, ei vain palveluntarjoajan ominaisuusluetteloa. Pidä salaisuudet poissa asiakaspuolen koodista ja lokeista, rajoita tuotantotunnistetietojen käyttöoikeuksia ja harjoittele tunnistetietojen vaihtamista. Jos sovelluksesi ei voi varmistaa saapuvan ilmoituksen aitoutta dokumentoidulla menetelmällä, se estää webhook-pohjaisen työnkulun julkaisun.

10. Mitä lähetys- ja asiakastietoja säilytätte, ja minne ne päätyvät?

Luettele kaikki kentät, jotka integraatiosi lähettäisi, mukaan lukien seurantanumerot, tilausviitteet, osoitteet, yhteystiedot ja mukautetut metatiedot. Kysy, mitkä kentät ovat pakollisia, kuinka kauan tietoja ja lokeja säilytetään, miten poistopyynnöt toimivat ja mitkä alueet tai alikäsittelijät ovat organisaatiosi vaatimusten kannalta merkityksellisiä. Hanki sopimus- tai tietoturvadokumentaatio aina, kun tarkastelusi sitä edellyttää.

Minimoi siirtämäsi tiedot. Seurannan integraation ei pitäisi saada asiakastietoja vain siksi, että koko tilausobjektin välittäminen on kätevää. Tietosuoja-, laki- ja tietoturvatiimiesi tulee päättää, sopiiko palveluntarjoajan dokumentoitu tietojenkäsittely niille markkinoille, joilla toimit.

Varaudu häiriöihin ja toiminnan muutoksiin

11. Mitkä ovat nopeusrajoitukset, ja miten asiakkaiden pitäisi reagoida virheisiin?

Kysy rajoitukset päätepisteen, tunnistetiedon ja ympäristön mukaan sekä mahdolliset samanaikaisuussäännöt ja suositeltu uudelleenyrityskäytäntö. Erota virheellinen pyyntö tilapäisestä palveluongelmasta ja pyynnöstä, jonka nopeusrajoitus on tullut vastaan. HTTP-rajapinnoissa tilakoodien merkityksillä on väliä: RFC 6585 määrittelee koodin 429 liian monille pyynnöille, kun taas RFC 9110 kuvaa HTTP-semantiikkaa, mukaan lukien palvelinvirheet.

Laske odotettu liikenne tavallisina päivinä ja ruuhkahuipuissa ja testaa asiakas, joka hidastaa pyyntöjä, jonottaa työt ja hälyttää pitkittyneistä virheistä. Varmista, voidaanko epävarma kirjoitusyritys turvallisesti uusia. Uudelleenyrityskäytäntö, joka moninkertaistaa liikenteen häiriön aikana, voi vaikeuttaa palautumista.

12. Miten kaava-, tila- ja kuljetusyhtiöintegraatioiden muutoksista ilmoitetaan?

Kysy API-versioinnista, vanhentumisilmoituksista, muutoslokeista ja siitä, voidaanko tapahtumakenttiä lisätä ilman version vaihtamista. Kuljetusyhtiöiden toimittamat kuvaukset ja seurantakäyttäytyminen voivat myös muuttua. Selvitä, miten palveluntarjoaja ilmoittaa muutoksesta, joka vaikuttaa yhteen kuljetusyhtiöön tai reittiin koko API:n sijaan.

Kirjoita valinnaisille kentille ja tuntemattomille tila-arvoille sallivat jäsentimet, mutta älä muuta tuntematonta arvoa hiljaa toimitetuksi tai epäonnistuneeksi. Tallenna riittävästi lähdetietoja muuttuneen yhdistämisen selvittämiseksi. Nimeä henkilö tarkistamaan palveluntarjoajan ilmoitukset ja päivittämään integraatiotestit ennen muutoksen näkymistä asiakkaille.

13. Mitä voimme testata ennen tuotantoa, ja kuinka hyvin testiympäristö vastaa tuotantokäyttäytymistä?

Pyydä pääsy dokumentaatioon, mahdolliseen testiympäristöön, esimerkkivastauksiin ja tapaan testata virhepolkuja. Kysy, mitkä tilanteet simuloidaan ja mitkä edellyttävät todellisia lähetyksiä. Hiekkalaatikko voi osoittaa, että koodisi käsittelee payloadin, mutta se kertoo vain vähän kuljetusyhtiön tapahtumien kattavuudesta, päivitysten ajoituksesta tai alueellisesta sopivuudesta.

Suorita kahdenlaisia testejä: deterministisiä integraatiotestejä jäsentämiselle, uudelleenyrityksille ja tietoturvalle sekä rajattu todellisten lähetysten pilotti toiminnallisen käyttäytymisen arvioimiseksi. Sisällytä päällekkäiset lähetykset, palveluntarjoajan aikakatkaisu, viivästynyt skannaus, palautus ja tuntematon tila. Edellytä sekä suunnittelun että poikkeuksiin reagoivan tiimin hyväksyntää tuloksille.

14. Mitkä tuki- ja häiriösitoumukset koskevat tilannetta, jossa seuranta lakkaa päivittymästä?

Kysy, mitä tukikanavia tililläsi on käytettävissä, miten häiriöistä ilmoitetaan ja mitkä sopimukseen perustuvat palvelusitoumukset, jos sellaisia on, koskevat API:a tai ilmoitusten toimitusta. Selvitä, kattaako käytettävyyslupaus API-päätepisteen, seurantapäivitysten toimituksen vai molemmat. Kyse ei ole samasta toiminnallisesta lopputuloksesta.

Laadi oma toimintaohje: kuka havaitsee häiriön, kuka ottaa yhteyttä palveluntarjoajaan, milloin kyselyitä tai muuta varamenetelmää käytetään ja mitä asiakkaat näkevät päivitysten viivästyessä. Pyydä prosessi sekä lähetyskohtaisen tietojenkäsittelyongelman että koko alustan kattavan käyttökatkon ratkaisemiseksi. Testaa eskalointipolkusi ennen kuin tarvitset sitä.

15. Miten käyttö ja kustannukset lasketaan, ja mitä tapahtuu, jos lopetamme palvelun?

Kysy, mitkä toiminnot lasketaan laskutukseen tai käyttörajoihin: lähetykset, seurattavat lähetykset, pyynnöt, ilmoitukset vai jokin muu yksikkö. Varmista, miten päällekkäiset rekisteröinnit, uudelleenyritykset, passiiviset lähetykset, ylitykset ja testiliikenne käsitellään ehdotetussa sopimuksessa. Hanki sovellettavat ehdot kirjallisina sen sijaan, että arvioisit kustannuksia API-esittelyn perusteella.

Suunnittele myös palvelun päättäminen. Selvitä, miten voit viedä lähetyshistoriat, kuinka kauan käyttöoikeus säilyy ja mitä aktiivisille seurantatietueille tapahtuu. Toimiva poistumissuunnitelma ei tarkoita, että ennustat vaihtavasi palveluntarjoajaa; se on tapa välttää jo matkalla olevien lähetysten näkyvyyden menettäminen.

Muunna vastaukset tuotantopäätökseksi

Aidosti hyödyllinen käyttöönoton arviointi tuottaa kolme tulosta:

  • Lähetyssopivuuden tulos: testattu näyte, joka osoittaa, mitkä seurantatietueet hyväksyttiin ja tukevatko niiden tapahtumat suunniteltuja asiakas- ja toimintatyönkulkuja.
  • Integraation tulos: todennettu tapa käsitellä todennus, päällekkäisyydet, uudelleenyritykset, viivästyneet tapahtumat, kaavavaihtelut ja puuttuvien päivitysten palauttaminen.
  • Toimintaa koskeva sopimus: dokumentoidut rajoitukset, tietojenkäsittelyehdot, tukiyhteyshenkilöt, kustannusoletukset ja ratkaisemattomien riskien vastuuhenkilöt.

17TRACK on yksi arvioitava palveluntarjoaja, jos usean kuljetusyhtiön seurantaan tarkoitettu API sopii käyttötapaukseesi; sen Tracking API -sivu ja API-dokumentaatio ovat lähtökohtia, kun tarkistat integraatiota näiden kysymysten avulla. Samaa standardia tulee soveltaa kaikkiin palveluntarjoajiin: dokumentaatio osoittaa, miten rajapinnan on tarkoitus toimia, kun taas omat edustavat lähetystestisi osoittavat, toimiiko se tuotantotyönkulussasi. Älä julkaise asiakasilmoitusta tai poikkeusautomaatiota, ennen kuin sen käynnistävät tapahtumat on validoitu.

Usein kysytyt kysymykset

Riittääkö hiekkalaatikkotesti seurantaan tarkoitetun API:n hyväksymiseen tuotantoon?

Ei. Hiekkalaatikko voi validoida pyyntömuodot ja osan virheenkäsittelystä, mutta todellisia lähetyksiä tarvitaan kuljetusyhtiökohtaisten tapahtumien, ajoituksen ja poikkeustietojen hyödyllisyyden arvioimiseen todellisilla reiteilläsi. Käytä molempia erillisillä hyväksymiskriteereillä.

Pitäisikö meidän käyttää webhookeja vai kysellä seurantapäivityksiä?

Päätä dokumentoitujen toimitusvaihtoehtojen ja työnkulkusi viiveensietokyvyn perusteella. Webhookit voivat vähentää toistuvien tarkistusten tarvetta, kun niitä tuetaan, mutta vastaanottimesi tarvitsee silti uudelleenyritys- ja päällekkäisyyskäsittelyn. Kyselyt voivat soveltua ensisijaiseksi menetelmäksi tai palautuspoluksi dokumentoitujen rajoitusten puitteissa.

Mikä on yleisin virhe seurantatilojen yhdistämisessä?

Yhden laajan tilan käyttäminen tietyn liiketoimintaväitteen käynnistämiseen. Esimerkiksi toimitettu-tunniste yksinään ei välttämättä tarjoa riittävää todistetta riidan ratkaisemiseksi. Määritä käynnistimet niiden taustalla olevien tapahtumatietojen avulla, joita palveluntarjoajasi tosiasiassa toimittaa.

Kenen pitäisi hyväksyä integraatio ennen käyttöönottoa?

Suunnittelun tulee hyväksyä luotettavuus ja tietoturva; operatiivisen tiimin tai tuen tulee hyväksyä tapahtumien ja poikkeustyönkulkujen hyödyllisyys; ja asianmukaisten tietosuoja-, laki- ja hankintavastuuhenkilöiden tulee tarkistaa tietojenkäsittely ja kaupalliset ehdot. Nimeä vastuuhenkilö jokaiselle avoimeksi jäävälle puutteelle.

Lähteet