UPS Tracking API: Aloittelijan opas alkuun pääsemiseen

UPS Tracking API:n avulla yritys voi noutaa lähetyksen tilan ja näyttää toimituspäivitykset omalla verkkosivustollaan, sovelluksessaan, tilaustenhallintajärjestelmässään tai asiakaspalvelutyökaluissaan. Aloittaminen edellyttää yleensä UPS-kehittäjätilin luomista, sovelluksen rekisteröintiä, todennustietojen hankkimista, seurantapyynnön lähettämistä ja vastauksen muuntamista hyödyllisiksi asiakkaille näkyviksi tapahtumiksi. Tässä oppaassa prosessi selitetään olettamatta aiempaa API-kokemusta.

Esimerkeissä keskitytään seurantaan eikä tarrojen luomiseen, hinnoitteluun tai osoitteen validointiin. UPS ylläpitää erillisiä API-tuotteita ja dokumentaatiota, joten varmista ennen tuotantoprosessien rakentamista, että rekisteröidyllä sovelluksella on tarvitsemasi seurantatoiminnon käyttöoikeus.

Mitä UPS Tracking API tekee

API on jäsennelty tapa, jolla yksi ohjelmistojärjestelmä voi pyytää tietoja toiselta. Seurantaprosessissa järjestelmäsi lähettää lähetyksen tunnisteen, kuten seurantanumeron, kuljetusyhtiölle tai seurantaympäristölle. Palvelu palauttaa lähetystietoja, jotka voivat sisältää nykyisen tilan, tilakuvauksen, sijaintitietoja, päivämääriä ja paketin etenemisvaiheita palvelusta, lähetyksestä ja pyynnön hetkellä saatavilla olevista vastauskentistä riippuen.

Näitä tietoja voidaan käyttää useisiin käytännön toimintoihin:

• Verkkokaupan myymälään upotettu seurantaverkkosivu.
• Lähetysten näkyvyys tilaustenhallinta- tai toiminnanohjausjärjestelmässä.
• Asiakaspalvelun näkymät, jotka vähentävät tarvetta tarkistaa kuljetusyhtiön verkkosivusto manuaalisesti.
• Sisäiset ilmoitukset toimituspoikkeuksista, viivästyksistä tai valmistuneista toimituksista.
• Oston jälkeiset viestit lähetyksen tapahtumien perusteella.

API ei korvaa sovelluslogiikkaasi. Sinun on edelleen päätettävä, kuinka usein päivityksiä pyydetään, miten vastaukset tallennetaan, miten puutteellisia tietoja käsitellään ja miten kuljetusyhtiön tilat selitetään asiakkaille.

UPS Tracking API verrattuna UPS-verkkosivustoon

UPS-verkkosivusto on suunniteltu henkilölle, joka syöttää seurantanumeron ja lukee tuloksen. API on suunniteltu ohjelmistoille. Se on hyödyllinen, kun seurantatietojen on näyttävä automaattisesti toisessa järjestelmässä tai käynnistettävä sisäinen prosessi.

Tämä ero on tärkeä, koska API-integraatio tuo mukanaan vastuita, joita manuaalinen haku ei aiheuta. Tiimisi on suojattava tunnistetiedot, validoitava käyttäjän syötteet, tallennettava pyynnöt ja vastaukset asianmukaisesti, käsiteltävä tilapäiset häiriöt ja valvottava, että integraatio toimii edelleen kuljetusyhtiön alustan muutosten jälkeen.

UPS:n kehittäjäalusta on oikea lähtökohta nykyisille rekisteröinti- ja teknisille vaatimuksille. Sen dokumentaation tulee olla vanhempia oppaita, koodiesimerkkejä tai keskustelupalstajulkaisuja tärkeämpi, koska todennusmenetelmät, API-versiot, vaaditut otsakkeet ja tuotteen käyttöoikeussäännöt voivat muuttua.

Mitä tarvitset ennen pyynnön lähettämistä

Valmistele seuraavat asiat ennen integraation kirjoittamista:

1. UPS-kehittäjätili. Tutustu saatavilla oleviin API-rajapintoihin ja luo sovellus virallisen UPS Developer Portalin kautta.
2. Sovelluksen tunnistetiedot. Tarkat tunnistetietojen nimet ja todennusprosessi tulee ottaa ajantasaisesta UPS-dokumentaatiosta. Älä sijoita asiakassalaisuuksia selainkoodiin, mobiilisovelluksiin, julkisiin repositorioihin tai asiakkaille näkyville sivuille.
3. Kelvollinen seurantanumero testausta varten. Testaa lähetyksillä, joihin organisaatiollasi on valtuutus, ja vältä henkilökohtaisten tai kaupallisten lähetystietojen paljastamista lokeissa.
4. Palvelinpuolen integraatiopiste. Taustapalvelu on yleensä turvallisempi kuin kuljetusyhtiön kutsuminen suoraan julkiselta verkkosivulta, koska se voi pitää tunnistetiedot yksityisinä ja hallita pyyntöjen määrää.
5. Vastausten tallennussuunnitelma. Päätä, mitä kenttiä tarvitset, kuinka kauan niitä säilytetään ja miten kuljetusyhtiön tapahtuma yhdistetään sisäiseen tilaukseen.

Aloittelijaystävällinen integraatioprosessi

1. Vahvista liiketoimintavaatimus

Määritä ensin, mitä ”seuranta” tarkoittaa tuotteessasi. Asiakkaille näkyvä sivu saattaa tarvita vain nykyisen tilan ja arvioidun toimitustiedon. Varasto- tai tukipalvelun koontinäyttö saattaa tarvita myös skannaushistorian, aikaleimat, poikkeuskuvaukset ja alkuperäisen seurantanumeron.

Vältä kaikkien saatavilla olevien kenttien pyytämistä ilman perustetta. Pienempää tietomallia on helpompi ylläpitää, ja se paljastaa epätodennäköisemmin tietoja, joita käyttäjäsi eivät tarvitse.

2. Rekisteröi sovellus

Luo sovellus UPS:n kehitysympäristössä ja valitse ajantasaisten portaaliohjeiden mukainen seurantatuote. Tallenna sovelluksen tunniste turvallisesti. Jos UPS edellyttää tuotantokäyttöä varten hyväksyntää, tilin yhdistämistä tai lisäasetuksia, suorita nämä vaiheet ennen tuotannon julkaisupäivän lupaamista.

Käytä testaukselle ja tuotannolle erillisiä tunnistetietoja ja asetuksia aina, kun alusta tukee tällaista mallia. Tämä vähentää riskiä, että testiskripti vaikuttaa tuotantoprosessiin.

3. Toteuta todennus

Todennus osoittaa, että sovelluksellasi on lupa kutsua palvelua. Noudata nykyisessä UPS-dokumentaatiossa ilmoitettua todennusmenetelmää, tunnistepäätepistettä, käyttöaluevaatimuksia ja otsakemuotoa. Käsittele käyttöoikeustunnisteita väliaikaisina salaisuuksina äläkä kirjoita niitä sovelluslokeihin.

Järkevä toteutus pyytää tunnisteen vain tarvittaessa, käyttää sitä uudelleen sallitun voimassaoloajan ja hankkii uuden tunnisteen vanhenemisen jälkeen. Koodin tulee myös erottaa todennusvirhe seurantanumerovirheestä. Korjaustoimet ovat erilaiset: toinen edellyttää tunnistetietojen tai asetusten tarkistamista, kun taas toinen saattaa edellyttää syötteen validointia.

4. Lähetä seurantapyyntö

Lähetä todennuksen jälkeen pyyntö käyttäen UPS:n määrittämää seurantatoimintoa ja tunnistemuo​toa. Tarkka URL, HTTP-metodi, otsakkeet ja vastausskeema löytyvät valitsemasi API-version virallisesta dokumentaatiosta.

Käsitteellinen pyyntö näyttää tältä:

POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "trackingNumber": "YOUR_TRACKING_NUMBER"
}

Tämä on oppimisesimerkki, ei tuotantopyyntö, jonka voi kopioida ja liittää sellaisenaan. Korvaa toiminnon nimi, päätepiste, otsakkeet ja runko nykyisen UPS API -viitteen arvoilla. Jotkin API:t käyttävät polkuparametria tai erilaista pyyntörakennetta.

5. Normalisoi vastaus

Kuljetusyhtiöiden vastauksia ei aina kirjoiteta asiakkaidesi odottamalla kielellä. Luo sisäinen tapahtumamalli, jossa on vakaat kentät, kuten:

• Sisäinen tilaus- tai lähetys-ID.
• Kuljetusyhtiön nimi ja seurantanumero.
• Kuljetusyhtiön viimeisin tilakoodi ja raakakuvaus.
• Sovelluksesi käyttämä normalisoitu tila.
• Tapahtuman aikaleima ja, jos toimitettu, sijainti.
• Viimeisimmän onnistuneen päivityksen ajankohta.

Säilytä alkuperäinen kuljetusyhtiön tila aina kun mahdollista. Normalisoitu tunniste, kuten ”Kuljetuksessa”, on hyödyllinen asiakasnäkymässä, mutta raakakuvaus voi auttaa tukihenkilöstöä tutkimaan epätavallista tapahtumaa.

6. Päätä, miten päivitykset noudetaan

Jotkin järjestelmät käyttävät ajoitettua kyselyä: taustapalvelu tarkistaa kelvolliset lähetykset tietyin väliajoin ja tallentaa muutokset. Toiset käyttävät tapahtumailmoituksia, jos kyseinen alusta tukee niitä. Älä oleta, että kaikki UPS:n seurantatuotteet tarjoavat saman ilmoitusmekanismin. Vahvista nykyinen dokumentaatio ja kaupalliset ehdot ennen webhook-pohjaisen prosessin suunnittelua.

Kyselyjen tulee olla valikoivia. Äskettäin lähetetyt tai aktiivisesti liikkuvat paketit saattavat edellyttää tiheämpiä tarkistuksia kuin toimitetut tai peruutetut lähetykset. Käytä väliaikaisissa häiriöissä uudelleenyrityksiä kasvavilla viiveillä, noudata dokumentoituja rajoituksia ja lopeta tarpeettomat pyynnöt pääte​tilan jälkeen, ellei liiketoimintaprosessisi edellytä myöhempää vahvistusta.

Yleiset virheet ja niiden käsittely

Tärkein käyttökokemusta koskeva sääntö on, ettei puuttuvia tietoja muuteta varmaksi johtopäätökseksi. ”Uutta skannausta ei ole” ei automaattisesti tarkoita ”kadonnut”, eikä ”tarra luotu” välttämättä tarkoita ”kuljetuksessa”. Määritä tilat huolellisesti ja pidä poikkeusten käsittely näkyvänä tukitiimeille.

Milloin usean kuljetusyhtiön API sopii paremmin

Suora UPS-integraatio voi olla järkevä valinta, kun lähetyksesi käsitellään pääasiassa UPS:n kautta ja tiimisi haluaa hallita kuljetusyhtiöyhteyttä suoraan. Haittapuolena on, että jokainen uusi kuljetusyhtiö saattaa edellyttää erilaista todennusmallia, tietoskeemaa, virhekäytäntöä ja ylläpitoprosessia.

Jos toimintasi käyttää useita kuljetusyhtiöitä, usean kuljetusyhtiön palvelu voi vähentää erillisten integraatioiden määrää. 17TRACK's Tracking API on suunniteltu sovelluspohjaiseen lähetysten seurantaan, ja sen virallisessa kehittäjädokumentaatiossa kuvataan saatavilla oleva integraatiomalli. Sitä kannattaa arvioida, kun todellinen vaatimus ei ole vain UPS-seuranta vaan yhtenäinen seurantakerros useille kuljetusyhtiöille.

Tämä ei ole automaattinen syy korvata suoraa UPS-yhteyttä. Vertaile tarvitsemaasi kuljetusyhtiöiden kattavuutta, tapahtumien yksityiskohtaisuutta, tietojen säilytysvaatimuksia, todennusmallia, toiminnallisia rajoituksia, tukiprosessia ja toteutuksen kokonaispanosta. Palveluntarjoajan julkista dokumentaatiota tulee pitää teknisen konseptitodistuksen lähtökohtana, ei oman lähetysdatasi testaamisen korvikkeena.

Tuotantovalmiuden tarkistuslista

• Tunnistetiedot tallennetaan salaisuuksien hallintajärjestelmään eikä niitä koskaan paljasteta selaimelle.
• Testi- ja tuotantoympäristöt on erotettu selkeästi.
• Pyynnöillä on aikakatkaisut, hallitut uudelleenyritykset ja hyödyllinen virhelokitus.
• Seurantanumerot validoidaan ennen niiden lähettämistä.
• Järjestelmä tallentaa viimeisimmän onnistuneen päivityksen eikä korvaa sitä tyhjällä vastauksella.
• Kuljetusyhtiön raakaviestit ja asiakkaille näkyvät tunnisteet käsitellään erillään.
• Kyselytiheys noudattaa palveluntarjoajan julkaisemia rajoituksia ja toiminnallista tarvetta.
• Valvonta havaitsee todennusvirheet, kohonneet virhemäärät ja vanhentuneet lähetykset.
• Tukihenkilöstö näkee riittävästi tietoja asiakkaan kysymyksen tutkimiseksi.
• Integraatio testataan uudelleen, kun UPS muuttaa dokumentaatiota, tunnistetietoja, päätepisteitä tai vastauskenttiä.

Aloita yhdestä täydellisestä polusta: todenna, seuraa yhtä testilähetystä, tallenna vastaus, näytä yksinkertainen tila ja käsittele virhe. Laajenna vasta, kun tämä polku toimii luotettavasti. Tämä lähestymistapa on yleensä turvallisempi kuin laajan asiakasnäkyvän seurantakokemuksen rakentaminen ennen kuin taustalla olevat tiedot ja virhekäyttäytyminen tunnetaan.

Usein kysytyt kysymykset

Tarvitsenko API:n, jos seuraan vain muutamaa pakettia?

Yleensä et. Manuaalinen seuranta kuljetusyhtiön verkkosivustolla voi olla käytännöllisempää satunnaisissa hauissa. API on arvokkaampi, kun seuranta on osa toistettavaa työnkulkua tai sen on näyttävä toisessa sovelluksessa.

Voinko kutsua UPS Tracking API:a Shopify-teemasta tai selaimesta?

Suora selainkutsu voi paljastaa tunnistetiedot ja vaikeuttaa pyyntöjen hallintaa. Palvelinpuolen palvelu tai vakiintunut seurantaintegraatio on yleensä turvallisempi. Vahvista tekniset vaatimukset ja sallittu arkkitehtuuri nykyisestä UPS-dokumentaatiosta.

Luoko tracking API toimitustarroja?

Ei välttämättä. Seuranta, tarrojen luominen, hinnoittelu, osoitteen validointi ja muut logistiikkatoiminnot voivat olla erillisiä API-tuotteita. Valitse tarvitsemaasi toimintoa vastaava tuote.

Miksi kelvollinen seurantanumero saattaa palauttaa vain vähän tietoja?

Pakettia ei ehkä ole vielä skannattu ensimmäistä kertaa, tiedot eivät ehkä ole vielä saatavilla tai pyyntö ei ehkä vastaa API:n edellyttämää muotoa tai käyttöoikeuksia. Käsittele tyhjää tai rajoitettua vastausta tutkittavana tilana, älä todisteena lähetyksen katoamisesta.

Pitäisikö minun valita suora UPS-yhteys vai usean kuljetusyhtiön tracking API?

Valitse suora yhteys, kun UPS on pääasiallinen kuljetusyhtiö ja haluat keskittyneen integraation. Harkitse usean kuljetusyhtiön palvelua, kun toiminnallinen tavoitteesi on yksi seurantaprosessi useille kuljetusyhtiöille. Testaa tarvittavat kuljetusyhtiöt ja tapahtumaskenaariot ennen lopullisen päätöksen tekemistä.

Lähteet

• UPS Developer Portal
• UPS Tracking API -dokumentaatio ja tuotemateriaalit
• 17TRACK Tracking API
• 17TRACK API -dokumentaatio