UPS Tracking API:n käyttö: vaiheittainen käyttöönotto-opas

UPS Tracking API:n käyttämiseksi luo UPS Developer -tili, rekisteröi sovellus, hanki OAuth 2.0 -tunnistetiedot, pyydä käyttöoikeustunnus ja lähetä todennettuja seurantapyyntöjä kelvollisella UPS-seurantanumerolla. Portaalin tarkat nimet, hyväksyntävaiheet ja API-vaatimukset voivat muuttua, joten varmista ajantasaiset ohjeet virallisesta UPS Developer Portalista ennen tuotantointegraation käyttöönottoa.

Tämä opas on tarkoitettu kehittäjille ja verkkokauppojen operatiivisille tiimeille, jotka tarvitsevat lähetyksen tilan verkkokaupassa, tilaustenhallintajärjestelmässä, varastotyönkulussa, asiakaspalvelutyökalussa tai sisäisessä koontinäytössä. Oppaassa keskitytään integraation vaiheisiin, luotettavuuteen vaikuttaviin päätöksiin ja tarkistuksiin, joilla voidaan ehkäistä yleisiä seurantavirheitä.

Mitä UPS Tracking API tekee

API-integraation avulla ohjelmisto voi pyytää lähetystietoja UPS:ltä sen sijaan, että työntekijän tai asiakkaan pitäisi avata kuljetusyhtiön seurantasivu manuaalisesti. Sovellus voi käyttää vastausta viimeisimmän tunnetun tilan näyttämiseen, toimitustapahtumien tunnistamiseen, asiakaspalvelun selvitysten tukemiseen tai sisäisen työnkulun käynnistämiseen.

API ei ole sama asia kuin seurantaa varten tarkoitettu verkkosivu. Seurantasivu on suunniteltu ihmisen luettavaksi. API-vastaus on jäsenneltyä dataa, jonka ohjelmiston on jäsennettävä, tallennettava ja esitettävä. Järjestelmäsi vastaa edelleen todennuksesta, virheenkäsittelystä, kyselystä tai tapahtumien keräämisestä, tietojen säilytyksestä, käyttöliittymän suunnittelusta ja kaikista toimitustapahtumiin liittyvistä liiketoimintasäännöistä.

Ennen aloittamista

Valmistele seuraavat asiat ennen kehittäjäportaalin avaamista:

• UPS Developer -tili tai nykyisen UPS-käyttöönottoprosessin edellyttämä tilityyppi.
• Rekisteröity sovellus ja sille myönnetyt tunnistetiedot.
• Testiseurantanumero tai muu hyväksytty testausmenetelmä. Älä aloita oikeilla asiakastiedoilla, jos UPS:n dokumentaatio tarjoaa erillisen testiympäristön tai testausmenettelyn.
• Selkeä päätös siitä, mikä järjestelmä hallinnoi lähetystietoja, seurantatapahtumia ja asiakkaille näytettäviä tilaviestejä.
• Turvallinen paikka asiakastunnistetietojen ja käyttöoikeustunnusten säilyttämiseen. Älä koskaan sijoita salaisuuksia selainkoodiin, julkisiin tietovarastoihin, kuvakaappauksiin tai mobiilisovelluksiin, joita käyttäjät voivat tarkastella.

Päätä myös, tarvitseeko sovelluksesi vain seurantaa vai laajemman UPS-integraation. Seurannalla, hinnoittelulla, lähettämisellä, osoitteen vahvistamisella ja asiakirjapalveluilla voi olla erilaiset tuotteet, käyttöoikeudet, pyyntömuodot ja operatiiviset vaatimukset.

Vaihe 1: Avaa UPS Developer Portal

Aloita virallisesta UPS Developer Portalista. Tutustu nykyiseen API-luetteloon, todennusohjeisiin, käyttöönoton vaatimuksiin, ehtoihin ja ympäristötietoihin. Etsi nimenomaan Tracking API:n dokumentaatio äläkä oleta, että toisen UPS-palvelun ohjeet koskevat myös seurantaa.

Portaali on ajantasaisten pyyntökenttien, valtuutusalueiden, vastausmääritelmien, nopeusrajoitusten, virhekoodien ja ympäristötietojen oikea lähde. Nämä tiedot voivat muuttua, ja kolmannen osapuolen koodiesimerkki voi käyttää vanhempaa UPS-rajapintaa tai vanhentunutta todennusmenetelmää.

Vaihe 2: Rekisteröi sovellus

Luo sovellus kehittäjäportaalissa ja valitse sen tarvitsemat UPS-API:t. Jos kyseessä on vain seurantaan tarkoitettu projekti, pyydä ainoastaan seurantatoiminto, ellei työnkulkusi edellytä lisäpalveluja. Käyttöoikeuksien rajoittaminen vähentää määritysten monimutkaisuutta ja helpottaa myöhempää vianmääritystä.

Tallenna sovellustunniste ja salaisuus palvelinpuolen salaisuuksien hallintaan tai suojattuun ympäristömuuttujajärjestelmään. Käsittele salaisuutta kuten salasanaa. Jos se paljastuu, kierrätä se UPS:n tarjoaman prosessin kautta ja tarkista lokeista luvaton käyttö.

Jos portaali pyytää tiliä, laskutusta, yritystä tai sovellusta koskevia tietoja, anna tarkat tiedot. Älä keksi tuotantokäyttötapausta tai käytä jonkun muun tilitietoja vain testin suorittamiseksi. Palvelun käyttöoikeus voi riippua tilin määrityksistä ja UPS:n kulloisestakin hyväksyntäprosessista.

Vaihe 3: Ota OAuth 2.0 -todennus käyttöön

UPS:n nykyinen kehittäjädokumentaatio käyttää API-rajapinnoissaan OAuth-pohjaista todennusta. Palvelimesi vaihtaa yleensä sovelluksen tunnistetiedot dokumentoidun tunnusprosessin kautta ja vastaanottaa käyttöoikeustunnuksen. Sen jälkeen se sisällyttää tunnuksen API-pyynnön valtuutusotsakkeeseen.

Pidä todennus erillään seurant逻ikasta. Käytännöllisessä suunnittelussa yksi komponentti hankkii ja välimuistittaa kelvollisen tunnuksen ja toinen kutsuu seurantapäätepistettä. Tunnuskomponentin tulisi:

• Lähettää tunnistetiedot vain dokumentoituun UPS:n valtuutuspäätepisteeseen.
• Käyttää nykyisessä UPS-dokumentaatiossa määritettyä sisältötyyppiä ja grant-parametreja.
• Tallentaa tunnuksen tilapäisesti ja käyttää sitä uudelleen sen vanhenemiseen asti sen sijaan, että jokaiselle seurantanumerolle pyydettäisiin uusi tunnus.
• Päivittää tai hankkia tunnuksen uudelleen, kun dokumentoitu vanhenemisehto täyttyy.
• Poistaa tunnistetiedot ja tunnukset sovelluslokeista, virheraporteista ja tukipyynnöistä.

Älä kopioi selaimen istunnosta saatua tunnusta pysyvään integraatioon. Taustapalvelu on yleensä turvallisempi paikka tunnistetietojen hallintaan, koska se pitää salaisuudet poissa julkisesta asiakaskoodista.

Vaihe 4: Rakenna seurantapyyntö

Käytä virallisessa Tracking API -viitteessä esitettyä pyyntömuotoa. Tyypillinen pyyntö sisältää seurantanumeron polussa tai pyyntöparametreissa, käyttöoikeustunnuksen valtuutusotsakkeessa sekä UPS-API:n edellyttämät otsakkeet. Älä oleta, että seurantanumero on ainoa vaadittu arvo: nykyinen viite voi määrittää version, tapahtuman, sisältötyypin tai korrelaation otsakkeet.

Yksinkertaistettu pyyntömalli näyttää tältä:

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

Tämä on rakenteellinen esimerkki, ei suoraan kopioitava päätepiste. Käytä sovelluksesi kohdalla UPS:n dokumentaatiossa julkaistua päätepistettä, versiota, otsakkeita ja parametrien nimiä. Pidä seurantanumero oman tilaustietosi sääntöjen mukaisesti normalisoituna, mutta älä poista merkkejä, ellei kuljetusyhtiön dokumentaatio vahvista sen olevan turvallista.

Vaihe 5: Jäsennä tapahtumat tietomalliisi

Kuljetusyhtiöiden vastaukset sisältävät usein enemmän tietoa kuin yhden tilimerkinnän. Ennen asiakkaille näkyvän sivun koodaamista yhdistä vastaus sisäiseen malliin, joka voi sisältää esimerkiksi lähetyksen tunnisteen, kuljetusyhtiön, viimeisimmän tilan, tapahtumakoodin, tapahtuman kuvauksen, tapahtuma-ajan, sijainnin, arvioidut toimitustiedot ja toimitusajan, jos ne ovat saatavilla.

Säilytä alkuperäinen kuljetusyhtiön vastaus, jos säilytys- ja tietosuojakäytäntösi sallivat sen. Raakavastaus voi auttaa kartoitusvirheen selvittämisessä tai selittää, miksi normalisoitu tilasi poikkeaa kuljetusyhtiön sanamuodosta. Älä kuitenkaan näytä teknisiä tapahtumakoodeja asiakkaille ilman ymmärrettävää selitystä.

Älä käsittele jokaista tilaa lopullisena toimitustuloksena. Esimerkiksi kuljetuksessa oleva lähetys, poikkeus, toimitusyritys ja toimitettu lähetys eivät saa johtaa samaan asiakasviestiin. Luo selkeät kartoitukset ja määritä, mitä tapahtuu, kun UPS lisää tapahtuma-arvon, jota koodisi ei tunnista.

Vaihe 6: Lisää uudelleenyritykset, vahvistus ja valvonta

Tuotantointegraatio tarvitsee muutakin kuin onnistuneen pyynnön kehityskonsolissa. Lisää vahvistukset ja operatiiviset suojatoimet:

• Syötteen vahvistus: hylkää tyhjät, virheelliset tai ilmeisen puutteelliset seurantanumerot ennen pyyntöjen lähettämistä.
• Aikakatkaisut: estä hitaan kuljetusyhtiön vastauksen koko kassa-, tuki- tai varastotyönkulun estäminen.
• Uudelleenyrityssäännöt: yritä tilapäisiä verkko- tai palveluvirheitä uudelleen harkiten ja viiveellä. Älä yritä toistuvasti uudelleen todennusvirheitä tai virheellisiä seurantanumeroita.
• Rajoitusten huomiointi: noudata UPS:n dokumentaation rajoituksia ja käyttösääntöjä. Välimuistita viimeaikaiset tulokset, kun liiketoimintaprosessisi sallii sen.
• Tuntemattomat tilat: säilytä tunnistamaton tapahtuma tarkistettavaksi sen sijaan, että merkitsisit sen virheellisesti toimitetuksi tai kadonneeksi.
• Havainnointi: tallenna pyynnön ajoitus, vastausluokka ja korrelaatiotiedot kirjaamatta salaisuuksia tai tarpeettomia henkilötietoja.

Seurantajärjestelmän tulee myös määrittää, kuinka usein se päivittää lähetyksen. Liian tiheä kysely voi aiheuttaa vältettävää kuormaa eikä välttämättä tuota uutta tietoa. Liian harva kysely voi saada asiakkaille näkyvän sivun vaikuttamaan vanhentuneelta. Valitse aikaväli lähetysmäärän, operatiivisen kiireellisyyden, kuljetusyhtiön sääntöjen ja käyttäjien todellisesti tarvitsemien tietojen ajantasaisuuden perusteella.

Vaihe 7: Testaa realistisilla tilanteilla

Testaa muutakin kuin onnistunutta toimitettua lähetystä. Sisällytä testiin tuntematon seurantanumero, kuljetuksessa oleva lähetys, poikkeus, useita tapahtumia sisältävä lähetys, vanhentunut tunnus, aikakatkaisu, valtuutusvirhe ja vastaus, joka sisältää jäsenninlogiikalle tuntemattomia kenttiä. Jos UPS tarjoaa erillisen testiympäristön tai testitunnukset, noudata ensin kyseistä menettelyä.

Tarkista koko polku pyynnöstä käyttöliittymään. Varmista, että oikea tilaus saa oikean lähetyksen, aikaleimat näytetään tarkoitetulla aikavyöhykkeellä, päällekkäiset tapahtumat eivät luo päällekkäisiä asiakasviestejä ja kuljetusyhtiön käyttökatkos ei korvaa aiemmin kelvollista tilaa harhaanjohtavalla tekstillä.

Milloin usean kuljetusyhtiön Tracking API sopii paremmin

Suora UPS-integraatio voi olla sopiva, kun toiminta käyttää pääasiassa UPS:ää ja tarvitsee tarkkaa hallintaa kuljetusyhtiön työnkulkuun. Se muuttuu vähemmän käteväksi, kun tilaukset voivat kulkea useiden kuljetusyhtiöiden, markkinapaikkojen, postitoimijoiden tai alueellisten toimitusyritysten kautta. Tällöin erilliset tunnistetiedot, vastausmuodot, tilasanastot ja uudelleenyrityssäännöt voivat lisätä ylläpitotyötä.

Usean kuljetusyhtiön palvelu, kuten 17TRACK Tracking API, voi tarjota vaihtoehtoisen integraatiomallin sovelluksille, jotka tarvitsevat useiden kuljetusyhtiöiden seurantaa. Sen kehittäjädokumentaatio tulee tarkistaa suoraan tuettujen kuljetusyhtiöiden, pyyntömuotojen, todennuksen, käyttöehtojen ja saatavilla olevien ominaisuuksien osalta. Tämä ei tee siitä automaattisesti parempaa kuin suora UPS-yhteys: oikea valinta riippuu kuljetusyhtiöiden yhdistelmästä, tietovaatimuksista, integraation hallinnasta sekä kaupallisista tai vaatimustenmukaisuuteen liittyvistä rajoitteista.

Kuluttajille tarkoitetussa haussa kehittäjäintegraation sijaan 17TRACKin seurantataulu voi olla sopivampi kuin API-yhteyden rakentaminen. Jos kyseessä on verkkokauppa, joka tarvitsee brändättyjä oston jälkeisiä päivityksiä, tarkista kyseinen alustaintegraatio erikseen sen sijaan, että lisäisit API-työtä, jota kauppa ei tarvitse.

Yleiset toteutusvirheet

• Vanhojen esimerkkien käyttäminen: koodiesimerkki voi viitata käytöstä poistettuun versioon, vanhaan todennusmenetelmään tai eri UPS-palveluun.
• Salaisuuksien sijoittaminen käyttöliittymäkoodiin: kaikkea selaimeen toimitettavaa tulee käsitellä tarkasteltavissa olevana.
• Tyhjän tuloksen tulkitseminen lähetyksen puuttumiseksi: tarkista seurantanumero, tilin käyttöoikeudet, ympäristö ja vastausviesti ennen liiketoimintajohtopäätöksen tekemistä.
• Vain tekstin kartoittaminen: tilakuvaukset voivat vaihdella. Käytä dokumentoituja koodeja ja säilytä tuntemattomat arvot tarkistettaviksi.
• Tili- ja käyttövaatimusten sivuuttaminen: tekninen koodi voi olla oikein, vaikka sovellusta ei olisi määritetty pyydettyä palvelua varten.
• Päivittäminen ilman liiketoimintasääntöä: tarpeeton kysely voi lisätä kustannuksia, kuormaa ja operatiivista hälyä parantamatta asiakaskokemusta.

Käytännöllinen tuotantoonvientitarkistuslista

1. Varmista, että sovellus käyttää ajantasaista UPS-dokumentaatiota ja hyväksyttyä ympäristöä.
2. Varmista, että tunnistetiedot tallennetaan palvelinpuolella ja että ne voidaan kierrättää.
3. Testaa todennusvirheet, kuljetusyhtiön virheet, virheelliset syötteet ja aikakatkaisut.
4. Vertaa normalisoituja tiloja alkuperäiseen vastaukseen edustavien lähetysten osalta.
5. Määritä päivityskäytäntö ja seuraa pyyntömäärää.
6. Määritä vastuut tunnistamattomista tapahtumista, viivästyneistä päivityksistä ja asiakkaiden eskaloinneista.
7. Dokumentoi integraatio, jotta toinen kehittäjä voi päivittää tunnistetiedot, päätepisteversiot ja tilakartoitukset turvallisesti.

Usein kysytyt kysymykset

Tarvitsenko UPS-tilin Tracking API:n käyttämiseen?

Tarkista nykyiset UPS:n käyttöönotto- ja käyttöoikeusvaatimukset Developer Portalista. API-käyttöoikeus voi riippua sovelluksen rekisteröinnistä, tunnistetiedoista, tilin määrityksistä ja pyydetystä palvelusta. Älä oleta, että julkisen seurantataulun kirjautuminen vastaa kehittäjän API-käyttöoikeutta.

Onko UPS Tracking API ilmainen?

Älä oleta, ettei API-käyttöön liity kaupallisia ehtoja tai käyttörajoituksia. UPS julkaisee ajantasaiset palvelu- ja tilitiedot virallisissa kanavissaan, ja jotkin vaatimukset voivat riippua tuotteesta, tilistä tai sopimuksesta. Vahvista sovellettavat ehdot suoraan ennen tuotantobudjetin suunnittelua.

Voinko kutsua UPS API:a suoraan selaimen JavaScriptistä?

Selainpohjainen kutsu voi paljastaa sovelluksen tunnistetiedot ja aiheuttaa ristialkuperä-, tietoturva- ja käytönhallintaongelmia. Palvelinpuolen integraatio on yleensä turvallisempi tapa säilyttää salaisuuksia, hankkia tunnuksia, soveltaa uudelleenyrityssääntöjä ja rajoittaa pääsyä lähetystietoihin.

Kuinka usein sovellukseni pitäisi pyytää seurantapäivityksiä?

Käytä päivityskäytäntöä, joka perustuu kuljetusyhtiön dokumentoituihin rajoihin, lähetysmäärään, operatiiviseen kiireellisyyteen ja käyttäjien tarvitsemaan ajantasaisuuteen. Välimuistita viimeaikaiset tulokset tarvittaessa, käytä viivettä tilapäisten virheiden jälkeen ja vältä toistuvan kyselyn pitämistä dokumentoidun tapahtuma- tai ilmoitusominaisuuden korvikkeena.

Pitäisikö minun käyttää suoraa UPS-integraatiota vai usean kuljetusyhtiön API:a?

Suora UPS-integraatio voi sopia UPS-keskeiseen työnkulkuun, joka tarvitsee kuljetusyhtiökohtaisen hallinnan. Usean kuljetusyhtiön API voi vähentää integraatioiden määrää, kun lähetyksissä käytetään useita kuljetusyhtiöitä. Vertaa tuettuja kuljetusyhtiöitä, todennusta, tietokenttiä, luotettavuusvaatimuksia, käyttöehtoja ja toteutustyötä ennen valintaa.

Lähteet

• UPS Developer Portal — virallinen API-luettelo, sovellusten käyttöoikeudet, todennus ja kehittäjädokumentaatio.
• UPS Technology Integration — viralliset tiedot UPS-teknologian integroimisesta liiketoimintajärjestelmiin.
• 17TRACK Tracking API — virallinen tuote- ja kehittäjäaloitussivu usean kuljetusyhtiön seurantaan.
• 17TRACK API Documentation — virallinen API-dokumentaatio todennuksesta, pyynnöistä ja vastausten käsittelystä.