Spurningar · Heimilisföng

Er til API til að staðla heimilisföng?

Hvað kallið gerir

Endapunktur sannprófunar tengiliða setur heimilisfangið á póstform lands síns, og nafnið sem því fylgir. Hann les götu, húsnúmer, póstnúmer og stað saman, ekki einn reit í einu, og tilgreinir hverja leiðréttingu. Landið fer í country_code (ISO 3166-1) eða í country, skrifað hvernig sem er.

Einn tengiliður í einu í meginmáli beiðninnar, eða listi í reitnum items, allt að fimm hundruð í hverju kalli. Hvert kall þarf tákn, sem þú býrð til á aðgangssvæðinu þínu eftir skráningu og sendir í hausnum Authorization: Bearer. Tákninu má gefa gildistíma, eða láta það gilda þar til þú afturkallar það.

Hvernig niðurstaðan kemur til baka

Svarið hefur tvö form sama heimilisfangs: læsilegt form með íslensku stöfunum, og póstformið til að prenta límmiða, með hástöfum. Þú þarft bæði af ólíkum ástæðum: það fyrra til að sýna heimilisfangið starfsmanni eða í viðmóti, það seinna fyrir sjálfa prentunina.

Með þeim kemur niðurstaða sem lykilorð — rétt, breytt með sundurliðun á því sem breyttist reit fyrir reit, eða til athugunar þegar ekki er hægt að endurbyggja heimilisfangið með vissu, með ástæðunni á skiljanlegu máli: gata fannst ekki í sveitarfélaginu, ófullnægjandi gögn, húsnúmer fannst ekki. Ekkert er nokkurn tíma leiðrétt þegjandi: ef við breytum einhverju segjum við þér það, og ef við erum ekki viss segjum við það jafn skýrt í stað þess að giska. Þar sem skráin er í notkun færðu líka hnit húsnúmersins, kóða sveitarfélagsins og póststaðinn — „101 Reykjavík“ — sem heimilisfangið tilheyrir.

Stakt heimilisfang eða hópvinnslur

Undir fimm hundruð beiðnum færðu svarið strax, í sama kalli: dæmigert tilvik er skráningareyðublað eða greiðslusíða, þar sem sannreyna þarf heimilisfangið á því augnabliki sem notandinn slær það inn. Fyrir stærri lista, allt að hundrað þúsund heimilisföng í einu, bætir þú við "async": true: beiðnin skilar strax verkkóða og vinnslan fer í biðröð, þá sömu og sér um hópvinnslur sem hlaðið er upp af vefnum. Þú lest niðurstöðuna til baka með GET á sama endapunkt með kóðanum, á JSON-formi eða, ef þú þarft skjal til að sækja, sem CSV.

Sjálfvirk útfylling í eyðublöðin þín

Ef þú ert að smíða heimilisfangseyðublað gefur /api/v1/suggest þér sjálfvirka útfyllingu meðan notandinn slær inn: gata, staður og húsnúmer eru lögð til jafnóðum, og reiturinn er þegar sannreyndur við val í stað þess að þurfa að athuga hann eftir á með sérstöku kalli. Það á að nota frá eigin vefþjóni, sem virkar sem milliþjónn að endapunktinum: táknið má aldrei birtast í vafra notandans.

Hvenær borgar sig að tengja það

Það borgar sig þegar heimilisföng koma inn í skrárnar þínar aftur og aftur, ekki einu sinni: skráningareyðublað, greiðslusíða í vefverslun, CRM-kerfi sem fyllist úr mörgum áttum. Að sannreyna þar, á því augnabliki sem heimilisfangið berst, kemur í veg fyrir að röng heimilisföng safnist upp og þurfi svo að hreinsa í heilu lagi fyrir hverja póstsendingu. Ef þú átt hins vegar þegar lista sem þarf að laga einu sinni, er einfaldara að hlaða honum upp sem Excel- eða CSV-skjali af vefnum: sama vél, án þess að skrifa eina línu af kóða.

Villur, mörk og full skjölun

Hvert svar hefur HTTP-kóða í samræmi við það sem gerðist: 401 ef táknið vantar eða er ógilt, 413 ef lotan fer yfir mörkin, 429 ef þú fórst yfir leyfðan fjölda beiðna á mínútu, 402 ef inneignin nægir ekki fyrir kallið. Heimilisfang sem ekki er hægt að staðla er ekki API-villa: svarið kemur samt, með niðurstöðu sem útskýrir hvers vegna.

Á API-síðunni finnur þú alla endapunktana — heimilisfang, tvítakahreinsun, netfang, sími, vefsíða, auðgun nafns — með breytum, curl-dæmum og villukóðum í heild. Ef þú vinnur með tól sem flytur inn lýsingar er líka til openapi.json.

Lágmarkskall

Fulla svarið ber líka póstformið, sundurliðun hvers breytts reits, hnit húsnúmersins og gögnin eins og þú sendir þau, til samanburðar.