USPS API -dokumentaation tarkistuslista 17TRACK-toimitus- ja palautusintegraatiota varten

Luotettava USPS-integraatio 17TRACKin kanssa tulisi suunnitella kahdeksi toisiinsa liittyväksi mutta erilliseksi työvirraksi: USPS:n dokumentaatio määrittää kuljetusyhtiöön liittyvät tiedot ja palvelut, kun taas 17TRACK voi tarjota laajemman seurantakerroksen lähetysten näkyvyyteen eri kuljetusyhtiöiden välillä. Toimituksia ja palautuksia varten toteutustiimin tulisi varmistaa todennus, lähetyskohtaiset tunnisteet, tapahtumien yhdistäminen, hintojen ja lähetystarrojen vastuut, kysely- tai ilmoituskäyttäytyminen, virheenkäsittely sekä lähtevän toimituksen ja käänteisen logistiikan rajat ennen tuotantokoodin kirjoittamista.

Tämä tarkistuslista on tarkoitettu kehittäjille, verkkokauppatoimintojen tiimeille ja ratkaisuista vastaaville henkilöille, jotka yhdistävät USPS:ään liittyviä lähetystietoja tilausjärjestelmään, varastoprosessiin, asiakkaille näkyvään seurantaominaisuuteen tai palautusprosessiin. Siinä ei oleteta, että kaikki USPS:n API-ominaisuudet ovat käytettävissä 17TRACKin kautta tai että seuranta-API luo lähetystarroja, ostaa postimaksuja tai hallinnoi fyysisiä palautuksia itsenäisesti.

1. Määritä integraation rajat ensin

Aloita dokumentoimalla, mitä kunkin järjestelmän odotetaan tekevän. USPS:n dokumentaatio kuvaa USPS:n palvelut ja hyväksytyn integraattorin käytettävissä olevat rajapinnat. 17TRACKin Tracking API documentation on merkityksellinen, kun sovellus tarvitsee kuljetusyhtiöstä riippumattoman seurantaprosessin tai yhden rajapinnan lähetystapahtumia varten. 17RETURNS product page on merkityksellinen, kun projektiin sisältyy myös verkkokaupan palautusten hallinta. Käyttötapaukset liittyvät toisiinsa, mutta ne eivät ole keskenään vaihdettavissa.

• USPS: varmista, mitä kuljetusyhtiöön liittyviä toimintoja tarvitaan, kuten seurantaa, osoitepalveluja, hinnoittelua, palvelutietoja tai muita dokumentoituja API-rajapintoja.
• 17TRACK Tracking API: tarkista, miten USPS:n seurantanumerot lähetetään, niitä kysellään ja päivitetään sekä miten ne esitetään sovelluksen normalisoidussa tapahtumamallissa.
• Toimitusalusta: määritä järjestelmä, joka vastaa varaston kohdentamisesta, tilausten vapauttamisesta, lähetystarrojen luomisesta, postimaksujen ostamisesta, varaston vahvistuksesta ja lähetyksen luomisesta.
• Palautusprosessi: määritä, kuka hyväksyy palautuksen, luo palautusohjeet tai -tarrat, kirjaa palautetun paketin ja päättää hyvityksen tai vaihdon lopputuloksen.

Ensimmäinen arkkitehtuuripäätös ei siis ole ”mitä päätepistettä meidän pitäisi kutsua?”, vaan ”mikä järjestelmä omistaa kunkin liiketoimintatoiminnon?”. Kuljetusyhtiön seuranta-API voi parantaa näkyvyyttä olematta toimitusten tai palautusten järjestelmä, johon tiedot ensisijaisesti kirjataan.

2. Varmista USPS:n ajantasainen kehittäjädokumentaatio

Käytä USPS Web Tools and APIs information -sivua lähtökohtana ja seuraa sitten USPS:n linkittämää ajantasaista kehittäjädokumentaatiota ja tuotekohtaisia viitteitä. Älä kopioi vanhasta koodiesimerkistä päätepistettä, todennusmenetelmää, kentän nimeä tai käytöstäpoistoilmoitusta tarkistamatta sen nykyistä tilaa.

Kirjaa ennen toteutusta seuraavat dokumentaatiotiedot projektirekisteriin:

• Tarvittava USPS API -tuote tai -tuotteet.
• Nykyinen perus-URL ja testaus- sekä tuotantoympäristöjen tiedot.
• Rekisteröintiprosessi, sovellustunnistetiedot ja niiden sallittu käyttö.
• Todennusprosessi, tunnuksen voimassaoloaika, käyttöoikeusalueet sekä tunnistetietojen kierrätystä koskevat vaatimukset, jos ne on dokumentoitu valittua APIa varten.
• Vaaditut otsakkeet, sisältötyypit, pyyntömuodot, vastausmuodot ja versiotunnisteet.
• Tuetut toiminnot sekä tiliin, palveluun, maantieteelliseen alueeseen tai tietotyyppiin perustuvat rajoitukset.
• Pyyntörajat, aikakatkaisua koskevat ohjeet, huoltoilmoitukset ja dokumentoidut virhevastaustyypit.
• USPS:n vastaustietojen tallennusta, näyttämistä, uudelleenkäyttöä ja jakelua koskevat ehdot.

Jos vaatimusta ei ole ilmoitettu virallisessa dokumentaatiossa, merkitse se vahvistettavaksi suoraan USPS:ltä tai asiaankuuluvalta asiakasvastaavalta. Älä oleta, että vanha USPS Web Tools -esimerkki edustaa nykyistä APIa, äläkä oleta, että yhdessä USPS-tuotteessa kuvattu toiminto on käytettävissä toisessa tuotteessa.

3. Laadi todennus- ja tietoturvatarkistuslista

Todennus tulisi testata erillään liiketoimintalogiikasta. Tiimin tulee pystyä peruuttamaan ja vaihtamaan tunnistetiedot muuttamatta sovelluskoodia tai keskeyttämättä muita seurantatoimintoja.

1. Tallenna asiakassalaisuudet, API-avaimet, tunnukset ja varmenteet hallittuun salaisuuksien säilöön lähdekoodin tai asiakaspuolen sovelluksen sijaan.
2. Varmista, käyttääkö valittu USPS API nykyisessä dokumentaatiossa kuvattua todennusmenetelmää. Toteuta dokumentoitu prosessi täsmällisesti, mukaan lukien tunnuspyynnöt, käyttöoikeusalueet, vanheneminen sekä uusinta- tai uudelleentodennuskäyttäytyminen.
3. Käytä erillisiä tunnistetietoja tai ympäristöjä, jos USPS sallii sen, jotta testiliikennettä ei sekoiteta tuotantoliikenteeseen.
4. Rajoita pääsyä asiakkaiden osoitetietoihin, lähetystietoihin ja palautustietoihin niiden roolien mukaisesti, jotka niitä tarvitsevat.
5. Poista tunnistetiedot ja tarpeettomat henkilötiedot sovelluslokeista.
6. Kirjaa todennusvirheet korrelaatiotunnisteen avulla, mutta vältä salaisuuksien tai kokonaisten arkaluontoisten hyötykuormien kirjaamista.
7. Testaa toiminta tilanteissa, joissa tunnus vanhenee, tunnistetieto peruutetaan, pyyntö toistetaan tai todennuspalvelu ei ole tilapäisesti käytettävissä.

Pidä kuljetusyhtiön tunnistetiedot ja 17TRACKin tunnistetiedot käsitteellisesti erillään 17TRACK-integraatiossa, ellei vastaava dokumentaatio nimenomaisesti määritä muuta järjestelyä. 17TRACKin kautta reititetyn seurantapyynnön ei pidä olettaa myöntävän pääsyä USPS:n postimaksu-, tili- tai lähetystarrapalveluihin.

4. Vahvista tunnisteet ja tietojen omistajuus

Lähetyksen identiteetti aiheuttaa usein päällekkäisiä tilauksia ja katkenneita palautuslinkkejä. Luo kenttäkartta ennen järjestelmien yhdistämistä. Erottele vähintään seuraavat arvot:

Liiketoiminta-arvo	Toteutusta koskeva kysymys	Vahvistuspiste
Tilaustunnus	Mikä verkkokaupan tai OMS-järjestelmän tietue omistaa tilauksen?	Yksi tilaus voi sisältää useita paketteja.
Toimitustunnus	Mikä varaston tai 3PL-palvelun toiminto vapautti lähetyksen?	Älä korvaa sitä seurantanumerolla.
Seurantanumero	Mikä tunniste lähetetään USPS:lle tai 17TRACKille?	Vahvista muoto, kuljetusyhtiön määritys ja päällekkäisten tietojen käsittely.
Palautustunnus	Mikä valtuutus tai palautustapaus omistaa paketin?	Palautuslähetys ei saa korvata lähtevää lähetystä.
Tapahtumatunnus ja aikaleima	Miten toistuvat tai myöhästyneet tapahtumat käsitellään?	Määritä järjestys-, aikavyöhyke- ja idempotenssisäännöt.

Säilytä alkuperäinen kuljetusyhtiön tapahtuma ja normalisoitu sisäinen tila aina kun mahdollista. Normalisoitu tila, kuten ”kuljetuksessa”, on hyödyllinen verkkokaupoille, mutta toimintatiimit saattavat silti tarvita alkuperäisen USPS-tapahtumatekstin, sijainnin ja tapahtuma-ajan selvityksiä varten.

5. Suunnittele seurannan tietojen vastaanotto ja tilojen yhdistäminen

Luettele ennen reaaliaikaisen liikenteen yhdistämistä liiketoiminnan tosiasiassa tarvitsemat elinkaaritilat. Tyypillisiä tiloja voivat olla tarra luotu, vastaanotettu, kuljetuksessa, jakelussa, toimitettu, toimituspoikkeama ja palautus lähettäjälle. USPS:n tarkka tapahtumasanasto ja 17TRACKin kautta saatavat tapahtumat on vahvistettava niiden omissa dokumentaatioissa ja testivastauksissa; älä luo yhdistelmiä pelkkien tilanimien perusteella.

Määritä jokaiselle tapahtumalle:

• Lähdejärjestelmä ja alkuperäinen tapahtumakoodi tai -kuvaus.
• Normalisoitu sisäinen tila.
• Onko tapahtuma näkyvissä asiakkaalle, vain toiminnoille vai molemmille.
• Voiko se siirtää tilausta eteenpäin, keskeyttää SLA:n, käynnistää ilmoituksen tai avata poikkeamatapauksen.
• Voiko myöhempi tapahtuma korjata tai syrjäyttää sen.
• Miten päällekkäiset ja väärässä järjestyksessä saapuvat tapahtumat käsitellään.

Päätä myös, miten uudet seurantanumerot saapuvat järjestelmään. Lähetys voidaan luoda ennen ensimmäisen kuljetusyhtiön skannauksen näkymistä. Sovelluksen tulee erottaa ”seurantanumero rekisteröity” ja ”kuljetusyhtiö on vastaanottanut paketin” toisistaan sen sijaan, että skannaamaton lähetys esitettäisiin jo verkossa liikkuvana.

6. Päätä kyselyjen ja ilmoitusten välillä

Toteutuksessa on dokumentoitava, miten uudet seurantatiedot hankitaan. Jos valittu USPS- tai 17TRACK-tuote tukee ilmoitusmekanismia, varmista sen tilausmalli, toimitusmuoto, uudelleenyrityskäyttäytyminen, allekirjoitus- tai varmennusmenetelmä ja rajoitukset virallisesta dokumentaatiosta. Jos kyselyjä tarvitaan, määritä aikaväli, lopetusehdot, backoff-strategia ja niiden lähetysten käsittely, joista ei saada uusia tapahtumia.

Älä tee kyselyjä aggressiivisesti vain siksi, että asiakas päivittää seurantasivun. Käytä tarvittaessa palvelinpuolen tapahtumavarastoa tai välimuistia, sovella eksponentiaalista backoffia tilapäisiin virheisiin ja tee tietojen vastaanotosta idempotenttia. Epäonnistunut pyyntö ei saa luoda toista lähetystä, toista palautusta tai päällekkäistä asiakasilmoitusta.

Toimintailmoitusten tulee kattaa todennusvirheet, jatkuvat pyyntörajavastaukset, virheelliset kuljetusyhtiön vastaukset, tapahtumien käsittelyvirheet sekä selvittämättömiksi jäävien lähetysten määrän kasvu. Valvonnan tulee näyttää sekä API:n että liiketoiminnan tila: onnistunut HTTP-vastaus ei välttämättä tarkoita, että lähetys yhdistettiin oikeaan tilaukseen.

7. Erota toimitukset ja palautukset

Lähtevillä toimituksilla ja palautuksilla on yhteisiä lähetystietoja, mutta erilaiset liiketoimintasäännöt. Lähtevä toimitus alkaa yleensä tilauksesta ja päättyy toimitukseen tai poikkeamaan. Palautus alkaa asiakkaan tai kauppiaan päätöksestä, saattaa vaatia hyväksynnän ja päättyy vastaanottotarkastukseen, hyvitykseen, vaihtoon tai muuhun käsittelyratkaisuun.

Dokumentoi palautusintegraation seuraavat päätökset ennen kuljetusyhtiön seurannan lisäämistä:

• Mitä palautussyitä hyväksytään ja kuka hyväksyy ne?
• Luoko palautustarran kauppiaan toimitusalusta, USPS:ään liittyvä työnkulku, kolmannen osapuolen palautusjärjestelmä vai muu palveluntarjoaja?
• Miten palautuksen seurantanumero yhdistetään alkuperäiseen tilaukseen korvaamatta lähtevää seurantanumeroa?
• Mikä tapahtuma tarkoittaa ”palautus kuljetuksessa”, ”palautus toimitettu” tai ”vastaanotettu tarkastettavaksi”?
• Voidaanko palautus toimittaa varastoon mutta pitää odottavana, kunnes tuote on tarkastettu?
• Mitä tapahtuu, jos asiakas lähettää luvattoman paketin tai käyttää eri kuljetusyhtiötä?

17RETURNS voi olla merkityksellinen, kun projekti tarvitsee erillisen palautusten hallintaprosessin, kun taas 17TRACKin API liittyy lähetysten näkyvyyteen. Vahvista ajantasainen tuotetiedokumentaatio ennen kuin kummallekaan tuotteelle määritetään toimintoja, kuten tarran luominen, hyvityksen hyväksyminen, varastoon vastaanotto tai kuljetusyhtiön tilin hallinta.

8. Testaa integraatio realistisilla tilanteilla

Yhden toimitetun paketin onnistuneen polun testi ei riitä. Laadi testimatriisi, joka sisältää:

1. Kelvollisen USPS-seurantanumeron, josta ei ole äskettäistä tapahtumaa.
2. Lähetyksen, jonka useat tapahtumat vastaanotetaan väärässä järjestyksessä.
3. Toistuvat toimitus- tai poikkeamatapahtumat.
4. Virheellisen, väärin kirjoitetun tai tukemattoman tunnisteen.
5. Lähettäjälle palautuvan paketin.
6. Lähtevän lähetyksen ja palautuslähetyksen, jotka liittyvät samaan tilaukseen.
7. API:n aikakatkaisun, pyyntörajavastauksen, todennusvirheen ja virheellisen vastauksen.
8. Lähetyksen, jonka kuljetusyhtiötä ei aluksi tunneta tai joka vaatii vahvistuksen.
9. Asiakkaille näkyvän sivun, joka vastaanottaa uuden tapahtuman samalla kun toimintojen käyttäjä muokkaa tilausta.

Kirjaa jokaisesta tilanteesta odotettu tietokantatulos, asiakasviesti, toimintojen edellyttämä toimenpide, uudelleenyrityskäyttäytyminen ja auditointijälki. Testaa synteettisillä tai valtuutetuilla tiedoilla ja varmista, etteivät henkilötiedot ja yhteystiedot paljastu lokeissa tai julkisilla seurant### pages beyond the approved business purpose.

9. Tuotantovalmiuden tarkistus

Ennen julkaisua toiminnosta vastaavan henkilön tulee pystyä vastaamaan viiteen käytännön kysymykseen: Mikä järjestelmä luo lähetyksen? Mikä järjestelmä omistaa seurantanumeron? Mikä järjestelmä lähettää asiakasilmoitukset? Mikä järjestelmä hallinnoi palautustapausta? Mikä tiimi tutkii puuttuvan tai ristiriitaisen tapahtuman?

Suorita tarkistus vasta, kun olet tarkistanut ajantasaisen USPS-dokumentaation, valitun 17TRACK API -dokumentaation sekä mahdolliset tuotekohtaiset ehdot tai toimintaohjeet. Säilytä versioitu rekisteri päätepisteviitteistä, kenttäkartoituksista, testituloksista, tunnistetietojen omistajista, eskalointiyhteyshenkilöistä ja oletuksista, jotka edellyttävät suoraa vahvistusta. Päivitä rekisteri, kun API-versio, kuljetusyhtiön työnkulku, varastoprosessi tai palautuskäytäntö muuttuu.

Usein kysytyt kysymykset

Voiko 17TRACK korvata USPS API:n kaikissa toimitustoiminnoissa?

Mitään tällaista oletusta ei pidä tehdä. 17TRACKia voidaan arvioida seurantakerroksena, mutta USPS:ään liittyvät toiminnot, kuten hinnoittelu, osoitepalvelut, postimaksut tai muut kuljetusyhtiön toiminnot, on vahvistettava asiaankuuluvasta tuotetiedokumentaatiosta ja tilivaatimuksista. Seurannan näkyvyys ei ole sama asia kuin tarran ostaminen tai toimituksen toteuttaminen.

Tarvitsenko sekä USPS- että 17TRACK-integraatiot?

Ei aina. Jos sovellus tarvitsee vain tarkasti määritellyn USPS-toiminnon, suora USPS-integraatio voi olla sopiva. Jos se tarvitsee normalisoitua seurantaa useiden kuljetusyhtiöiden välillä tai kuljetusyhtiöstä riippumattoman seurantaprosessin, 17TRACK voi olla merkityksellinen. Päätöksen tulee perustua tarvittaviin ominaisuuksiin, omistajuusmalliin ja tietovirtaan, ei pelkkään seurantanumeroon.

Pitäisikö palautuksen seurantanumeron korvata lähtevä seurantanumero?

Ei. Tallenna palautus erillisenä lähetyksenä tai palautussiirtona, joka on yhdistetty alkuperäiseen tilaukseen ja toimitustietueeseen. Näin lähtevän toimituksen historia säilyy ja palautuksella voi olla omat tapahtumansa, poikkeamansa ja toiminnallinen lopputuloksensa.

Miten puuttuvia seurantatapahtumia tulisi käsitellä?

Määritä dokumentoitu uudelleenyritys- ja eskalointikäytäntö. Puuttuva tapahtuma voi johtua normaalista kuljetusyhtiön ajoituksesta, virheellisestä tunnisteesta, tietojen vastaanottovirheestä tai kuljetusyhtiön puolelta tulevasta viiveestä. Älä merkitse lähetystä kadonneeksi vain siksi, että yksi kysely-yritys ei tuottanut uutta tapahtumaa.

Missä USPS:n tunnistetiedot tulisi säilyttää?

Käytä hallittua palvelinpuolen salaisuuksien säilöä ja rajoita käyttöoikeuksia roolien mukaan. Älä koskaan sijoita tunnistetietoja verkkokaupan JavaScriptiin, mobiiliasiakaskoodiin, julkisiin repositorioihin tai lokeihin. Vahvista nykyiset USPS:n todennus- ja tunnistetietojen hallintaa koskevat vaatimukset ennen tuotantoon siirtymistä.

Lähteet

• USPS Web Tools and APIs — USPS:n virallinen lähtöpiste yritysten API-tietoja varten.
• 17TRACK Tracking API Documentation — 17TRACK API -integraation virallinen dokumentaatio.
• 17RETURNS — viralliset tuotetiedot palautusten hallinnan käyttötapauksia varten.
• 17TRACK API — virallinen tuote-esittely seuranta-API-skenaarioita varten.