Mikä on Ups Address Validation Api ja miten se toimii?

UPS Address Validation API on kehittäjäpalvelu, joka tarkistaa toimitusosoitteen UPS:n osoitetietoja vasten ja palauttaa tietoja, joiden avulla sovellus voi tunnistaa, korjata tai täydentää osoitteen ennen lähetyksen luomista. Se on suunniteltu ohjelmistoprosesseihin, kuten kassavaiheeseen, tilausten hallintaan, lähetystarrojen luomiseen ja asiakaspalvelutyökaluihin. Sitä tulee pitää osoitteen laadun tarkistuspalveluna, ei takeena paketin onnistuneesta toimituksesta.

Tyypillisessä työnkulussa yritys lähettää osoitekentät UPS API:lle, vastaanottaa vastauksen, joka sisältää tarkistustuloksia ja mahdollisia osoite-ehdotuksia, ja päättää sitten, hyväksytäänkö alkuperäinen osoite, pyydetäänkö asiakasta valitsemaan korjaus vai keskeytetäänkö tilaus manuaalista tarkistusta varten. Tarkat vastauskentät ja tuetut vaihtoehdot tulee varmistaa nykyisestä UPS:n kehittäjädokumentaatiosta ennen käyttöönottoa.

Mitä UPS Address Validation API tekee

Osoitteen tarkistus vertaa sovelluksen lähettämiä tietoja kuljetusyrityksen saatavilla oleviin osoitetietoihin. Pyynnöstä ja osoitteesta riippuen vastaus voi osoittaa, tunnistetaanko osoite, ja palauttaa standardoidun tai korjatun version. Tämä voi auttaa sovellusta havaitsemaan yleisiä ongelmia, kuten:

• Puuttuvat katutiedot tai keskeneräinen osoiterivi
• Virheelliset tai keskenään ristiriitaiset kaupungin, osavaltion, maakunnan tai postinumeron arvot
• Kirjoitusasujen vaihtelut ja muotoiluerot
• Useat mahdolliset osumat samalle asiakkaan syöttämälle osoitteelle
• Osoite, jota ei voida luotettavasti yhdistää saatavilla oleviin kuljetusyrityksen tietoihin

Käytännön tavoitteena on parantaa osoitetta ennen toimituksen käsittelyä. Selkeämpi osoite voi vähentää vältettävissä olevia toimituspoikkeuksia, mutta tarkistus ei poista kaikkia toimitusriskejä. Oikein muotoiltu osoite voi silti olla saavuttamattomissa, suljettu, toisen vastaanottajan käytössä tai paikallisten toimitusolosuhteiden vaikutuksen alainen.

Miten API toimii

Prosessi sisältää yleensä viisi vaihetta. UPS:n päivittäessä kehittäjäalustaansa nimet, kentät ja vastausrakenteet voivat muuttua, joten kehittäjien tulee käyttää nykyistä API-viitettä vanhaan koodiesimerkkiin luottamisen sijaan.

1. Sovellus hankkii valtuutuksen

Yritys luo ensin UPS-kehittäjäsovelluksen tai käyttää olemassa olevaa sovellusta ja hankkii API-yhteyteen tarvittavat tunnistetiedot. UPS API:t käyttävät todennettua kehittäjätyönkulkua, ja nykyisestä UPS-dokumentaatiosta tulee tarkistaa tilin edellytykset, tunnistetietojen hallinta, ympäristöt ja tunnusten käsittely. Tunnistetiedot tulee säilyttää suojatulla palvelimella, eikä niitä saa paljastaa selaimen koodissa tai mobiilisovellusten paketeissa.

2. Sovellus kerää osoitekentät

Kassa- tai tilausjärjestelmä kerää toimitukseen käytettävän osoitteen. Yleisiä tietoja ovat vastaanottajan nimi, katuosoite, kaupunki, osavaltio tai maakunta, postinumero sekä maa tai alue. Kaikilla kentillä ei ole samaa merkitystä kaikilla markkinoilla, ja vaadittu pyyntörakenne riippuu käytettävästä UPS API -toiminnosta.

Hyvä tietojen käsittely alkaa ennen API-kutsua. Lomakkeessa osoiterivit tulee erottaa kaupungista ja postinumerosta, yksikkö- tai huoneistotiedot tulee säilyttää, eikä käyttäjän syöttämiä tietoja pidä poistaa huomaamatta. Osoitteen normalisointi näyttöä varten on eri asia kuin toimitustarraan lopulta tulevien tietojen muuttaminen.

3. Järjestelmä lähettää tarkistuspyynnön

Palvelin lähettää osoitteen UPS:n tarkistuspäätepisteeseen käyttäen UPS:n määrittämää menetelmää, otsakkeita, valtuutustunnusta ja pyyntökaaviota. Pyyntö tulee lähettää taustapalvelimelta, jossa tunnistetietoja, lokitusta, käyttörajoja ja virheenkäsittelyä voidaan hallita.

Tuotantointegraatiossa tulee myös määritellä, mitä tapahtuu, jos pyyntö aikakatkaistaan, palauttaa todennusvirheen tai saavuttaa käyttörajan. Osoitteen tarkistuksen tulee parantaa kassaprosessia, ei tehdä koko kaupasta käyttökelvotonta kolmannen osapuolen palvelun ollessa tilapäisesti poissa käytöstä.

4. UPS palauttaa tuloksen tai ehdotuksen

Vastaus voi sisältää tarkistuksen tilan, selittävää tietoa ja yhden tai useamman osoitekandidaatin. Kandidaatti ei automaattisesti tarkoita, että asiakkaan osoite pitäisi korvata. Ehdotetusta osoitteesta voi esimerkiksi puuttua huoneiston numero tai se voi olla lähellä sijaitseva osuma. Sovelluksen tulee näyttää tulos selkeästi ja säilyttää asiakkaan mahdollisuus vahvistaa lopullinen osoite.

Hyödyllinen käyttöliittymä erottaa kolme lopputulosta:

• Hyväksytty: Osoite vaikuttaa riittävän kelvolliselta yrityksen työnkulkua varten.
• Korjausta ehdotettu: Palvelu palautti mahdollisen parannuksen, jonka asiakkaan tai työntekijän tulee tarkistaa.
• Ratkaisematon: Järjestelmä ei pystynyt muodostamaan luotettavaa osumaa, joten tilaus edellyttää lisätietoa tai manuaalista tarkistusta.

Nämä nimikkeet ovat sovelluksen suunnitteluratkaisu, eivät välttämättä UPS:n käyttämää täsmällistä sanamuotoa. Toteutuksessa dokumentoidut vastauskoodit tulee yhdistää huolellisesti, eikä jokaista virheetöntä vastausta pidä tulkita vahvistetuksi toimituskelpoiseksi osoitteeksi.

5. Tilausjärjestelmä päättää jatkotoimista

Vastauksen saatuaan myyjä voi päivittää kassalomakkeen, pyytää asiakasta vahvistamaan ehdotuksen, ohjata tilauksen operatiiviseen jonoon tai jatkaa toimituksen käsittelyä. Tarkistettu tulos voidaan myös tallentaa tilauksen yhteyteen yrityksen tietosuoja-, säilytys- ja turvallisuuskäytäntöjen mukaisesti.

Tarkistus tulee suorittaa työnkulun oikeassa vaiheessa. Kassalla tehtävä tarkistus voi estää ilmeiset virheet ennen maksua tai toimituksen käsittelyä. Sen suorittaminen uudelleen ennen tarran luomista voi havaita markkinapaikoista, tuonneista, asiakaspalvelun muokkauksista tai vanhemmista tilauksista peräisin olevat osoitteet. Toistuvia kutsuja tulee hallita, jotta järjestelmä ei aiheuta tarpeetonta liikennettä tai kitkaa.

Osoitteen tarkistus verrattuna osoitteen varmennukseen

Näitä termejä käytetään usein toistensa synonyymeina, mutta ne kuvaavat eri varmuustasoja. Tarkistus kysyy yleensä, vastaako osoite tunnettua osoitetietoa ja voidaanko se standardoida. Varmennus voi tarkoittaa vahvempaa tarkistusta, kuten toimitettavuuden tai osoitteen ja tietyn vastaanottajan välisen yhteyden vahvistamista. UPS Address Validation API:tä ei tule esittää todisteena siitä, että henkilö asuu osoitteessa tai että toimitus onnistuu.

Ero on tärkeä liiketoimintasäännöissä. Myyjä voi hyväksyä tarkistetun osoitteen vähäriskisessä tilauksessa, mutta vaatia lisätarkistusta arvokkaassa lähetyksessä, poikkeuksellisen suuressa tilauksessa tai kohteessa, jossa on ollut toimitusongelmia. Osoitteen tarkistus on yksi tilausten laatuprosessin kontrolli, ei petosten seulonnan, asiakkaan vahvistuksen tai kuljetusyrityksen palvelukelpoisuustarkistusten korvike.

Mitä API ei takaa

Tarkistusvastausta tulee tulkita dokumentoidun laajuutensa puitteissa. Se ei välttämättä vahvista kaikkia seuraavia asioita:

• Että nimetty vastaanottaja liittyy kyseiseen sijaintiin
• Että osoite on turvallinen tai saavutettavissa kaikilla palvelutasoilla
• Että tietty huoneisto, liikehuoneisto, yrityksen osasto tai postihuone vastaanottaa paketin
• Että osoite soveltuu kaikille UPS-tuotteille, lisämaksukäsittelyille tai toimitusvaihtoehdoille
• Että tarra voidaan luoda ilman erillisiä lähetys-, laskutus- tai palvelutarkistuksia

Kattavuus ja toiminta voivat myös vaihdella maan, alueen, osoitetyypin ja API-version mukaan. Ennen kuin lupaat asiakkaille tietyn kattavuustason, tarkista virallisesta UPS-dokumentaatiosta markkina-alue ja toiminto, jota yrityksesi aikoo käyttää.

Toteutuspäätökset, jotka vaikuttavat tuloksiin

Säilytä alkuperäiset ja korjatut arvot erillään

Tallenna asiakkaan alkuperäinen syöte erillään standardoidusta ehdotuksesta. Tämä tukee auditointia ja helpottaa epäonnistuneen toimituksen selvittämistä. Se estää myös korjausalgoritmia poistamasta huomaamatta tietoja, joita paikallinen kuljetusyritys tai rakennuksen ylläpitäjä tarvitsee.

Käsittele huoneisto- ja yksikkötiedot huolellisesti

Yksikkötiedot voivat olla toiminnallisesti tärkeitä, vaikka katuosoite näyttäisi kelvolliselta. Jos API palauttaa kandidaatin ilman yksikkötietoa, käyttöliittymän tulee pyytää asiakasta vahvistamaan se sen sijaan, että kandidaattia pidettäisiin täydellisenä korvauksena.

Suunnittele epäselvyyksiä varten

Kun palautetaan useita kandidaatteja, näytä riittävästi asiayhteyttä, jotta käyttäjä voi erottaa ne toisistaan. Vältä ensimmäisen tuloksen automaattista valitsemista, ellei yritys ole testannut toimintaa ja hyväksy siihen liittyvää riskiä. Yritysosoitteissa manuaalinen tarkistusvaihtoehto voi olla tarkoituksenmukaisempi kuin toistuvat automaattiset korjaukset.

Seuraa koko työnkulkua

Seuraa tarkistusvirheitä, asiakkaiden ohituksia, hylättyjä ehdotuksia, osoitteeseen liittyviä kuljetuspoikkeuksia ja onnistuneita toimituksia. Näiden mittareiden avulla voidaan arvioida, vähentääkö integraatio operatiivisia ongelmia. Pelkkä korkea hyväksymisaste ei osoita, että palvelu parantaa toimitustuloksia.

Milloin yrityksen kannattaa käyttää sitä?

API on hyödyllisin silloin, kun osoitteen laatu vaikuttaa toimituksen kustannuksiin tai asiakaskokemukseen. Yleisiä käyttötapauksia ovat verkkokaupan kassavaihe, markkinapaikkojen tilaustuonnit, fyysisesti toimitettavien tilausten tilauslaskutus, varaston tilausten vapautus ja tarranluontiprosessit. Se voi olla erityisen hyödyllinen, kun yritys vastaanottaa osoitteita useista myyntikanavista eikä voi luottaa yhteen standardoituun lomakkeeseen.

Se voi olla tarpeeton pienelle, hallitulle listalle yrityksen sisäisesti ylläpidettyjä toimipaikkoja. Se voi myös olla yksinään riittämätön säänneltyihin, arvokkaisiin tai petosherkkiin lähetyksiin. Tällöin se tulee yhdistää manuaaliseen tarkistukseen sekä yrityksen edellyttämiin palvelukelpoisuus-, lähetys- ja turvallisuuskontrolleihin.

Käytännön integraation tarkistuslista

1. Varmista tarkka UPS API -toiminto, markkina-alue ja tuettavat osoitetyypit.
2. Tutustu nykyiseen todennus-, pyyntö-, vastaus-, virhe- ja käyttörajoituksia koskevaan dokumentaatioon.
3. Rakenna taustapalvelu sen sijaan, että paljastaisit tunnistetiedot asiakaspuolen koodissa.
4. Säilytä huoneisto-, liikehuoneisto-, rakennus- ja toimitusohjeet.
5. Luo käyttöliittymään selkeät tilat hyväksytyille, ehdotetuille ja ratkaisemattomille osoitteille.
6. Testaa yrityksesi kannalta olennaiset kansainväliset, maaseutu-, kaupalliset, usean yksikön ja keskeneräiset osoitteet.
7. Määrittele varareitti käyttökatkojen, aikakatkaisujen ja epäselvien tulosten varalle.
8. Mittaa osoitteeseen liittyviä toimitustuloksia käyttöönoton jälkeen.

Yhteenveto

UPS Address Validation API toimii vastaanottamalla osoitteen, vertaamalla sitä UPS:n osoitetietoihin ja palauttamalla tuloksen tai mahdollisen korjauksen kutsuvan sovelluksen arvioitavaksi. Sen hyöty on suurimmillaan ennen toimituksen käsittelyä, jolloin myyjä voi vielä pyytää puuttuvia tietoja tai estää vältettävissä olevan toimitusvirheen. Turvallisin toteutus käsittelee vastausta päätöksenteon tukena: säilytä asiakkaan syöte, tarkista epäselvät ehdotukset, vahvista nykyinen maantieteellinen kattavuus äläkä sekoita osoiteosumaa toimitustakuuseen.

Usein kysytyt kysymykset

Vahvistaako UPS Address Validation API, että osoite on toimitettavissa?

Ei välttämättä. Se voi auttaa yhdistämään ja parantamaan osoitetietoja, mutta tarkistustulos ei ole sama asia kuin todiste vastaanottajan, rakennuksen, yksikön tai toimituspalvelun saatavuudesta. Tutustu nykyiseen UPS-dokumentaatioon ja käytä tarvittaessa erillisiä palvelukelpoisuus- ja operatiivisia tarkistuksia.

Voiko API korjata asiakkaan osoitteen automaattisesti?

Sovellus voi käyttää palautettua ehdotusta korjauksen tarjoamiseen, mutta automaattinen korvaaminen on liiketoimintapäätös. Asiakkaan tulee voida tarkistaa muutokset erityisesti silloin, kun yksikkönumerot, yritysnimet tai muut toimitustiedot voivat kadota.

Pitäisikö tarkistus suorittaa kassalla vai ennen lähetystä?

Kumpikin vaihe voi olla hyödyllinen. Kassalla tehtävä tarkistus havaitsee ongelmat varhain, kun taas tarkistus ennen tarran luomista voi havaita muokkaukset ja tuodut tilaukset. Monet yritykset käyttävät hallittua yhdistelmää, jossa hyödynnetään välimuistia ja varatoimintoja tarpeettomien pyyntöjen välttämiseksi.

Edellyttääkö API:n käyttö kehittäjätunnuksia?

Kyllä. Yritys tarvitsee yleensä pääsyn UPS:n kehittäjäalustalle sekä valitun API:n edellyttämät todennustunnistetiedot. Tiliä, sovellusta, ympäristöä ja käyttöä koskevat vaatimukset tulee vahvistaa suoraan UPS:ltä.

Onko osoitteen tarkistus sama asia kuin petosten ehkäisy?

Ei. Osoitteen tarkistus koskee osoitteen laatua ja yhdistämistä. Se ei selvitä, kuka tilauksen teki, onko maksu valtuutettu tai soveltuuko toimitusosoite tiettyyn tapahtumaan.

Lähteet

• UPS Developer Portal — virallinen aloituspiste UPS API -tuotteille, sovelluksille, todennukselle ja kehittäjäresursseille.
• UPS Address Validation API reference — virallinen viite osoitteen tarkistustoiminnolle, pyyntörakenteelle, vastauksille ja toteutustiedoille.
• UPS Application Programming Interfaces — UPS:n virallinen yleiskatsaus API-pohjaisiin teknologiaintegraatioihin.