Autentimine ja API vastused

Kasutage API mandaate

Saatke v3 päringuid HTTPS kaudu aadressile https://api.multitel.net. Iga selle juhendi lõpp-punkt nõuab autentimist. Hoidke mandaate oma serveris ja ärge pange neid kunagi brauseri JavaScript-koodi, avalikele lehtedele, ekraanipiltidele ega lähtekoodi haldusse.

Kasutage ühte neist mandaadivormidest:

HTTP Basic koos API kasutajanime ja parooliga, mis on konfigureeritud teie MultiTEL konto jaoks.
Bearer tunnus koos Authorization: Bearer YOUR_API_TOKEN päisega, mis on ette nähtud lubatud API kontole, millel on konfigureeritud tunnuse autentimine. Tunnuse päringuid aktsepteeritakse ainult selle API konto jaoks lubatud aadressidelt.

Kui IP lubaloend on teie API konto jaoks konfigureeritud, saatke kõik päringud lubatud aadressidelt.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getcountries'

curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'

Nendes näidetes olevad muutujad on kohahoidjad mandaatidele, mida hoiate privaatselt oma keskkonnas.

Käsitlege autentimisvigu

Autentimisvead saadetakse HTTP olekuga 401. Keha kasutab standardset ümbrikut koos status.code väärtusega 401 ja tühja sõnega kui response.

Mandaadid puuduvad: status.msg on Username and password are required, ja vastus sisaldab Basic autentimisväljakutset.
Bearer tunnus tagasi lükatud: kui Authorization päis kasutab Bearer skeemi ja tunnus on tundmatu, keelatud või teie aadressilt ei ole lubatud, status.msg on Invalid bearer token. Kui Bearer päis on olemas, muid mandaate ei proovita.
Kehtetud Basic mandaadid: status.msg algab tekstiga A valid username and password pair are required., ja vastus sisaldab Basic autentimisväljakutset. Sõnum võib sisaldada rohkem diagnostikateksti, seega ärge seda parsige.

Ärge proovige automaatselt uuesti samade mandaatidega. Paljud ebaõnnestunud katsed ühelt aadressilt lühikese aja jooksul võivad põhjustada sellelt aadressilt tulevate edasiste päringute blokeerimist.

Lugege vastuse keha

Enamik v3 lõpp-punkte, sealhulgas getcountries, getstates, getareas ja other, tagastab andmed selles ümbrikus JSON-vormingus:

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "countrycode": "1",
      "name": "United States",
      "description": "United States",
      "isocode": "US",
      "is_mobile": 0,
      "sms_coverage": 1,
      "latitude": "38.0000",
      "longitude": "-97.0000",
      "next_function": "v3/getareas/US"
    }
  ]
}

See on illustratiivne riigiloendi vastus, mitte kinnitus praeguse varu või võimaluste kohta.

Väli	Tähendus
`status.code`	API tulemikood, näiteks `200`, `401`, `404` või `500`.
`status.msg`	Inimloetav sõnum. See võib olla tühi. Rajage programmiloogika välja `status.code` väärtusele, mitte sõnumi tekstile.
`status.results`	Kirjete arv. Siin dokumenteeritud otsingulõpp-punktide puhul on see olemas, kui `response` on JSON loend, sealhulgas tühi loend (`0`). See puudub, kui `response` on tühi sõne või `null`. Muude lõpp-punktide vastustes võib kirjete arv olla esitatud teisiti; järgige nende vastuse dokumentatsiooni.
`response`	Lõpp-punkti tagastatav sisu. Selle tüüp sõltub lõpp-punktist ja tulemusest. Vigade korral on see tühi sõne.

Veavastus näeb välja selline:

{
  "status": {
    "code": 404,
    "msg": "No areas found"
  },
  "response": ""
}

Kui vastust ei saa kodeerida, sisaldab keha status.code 500, status.msg Response encoding error, ja tühja objekti kui response.

Vanem lõpp-punkt GET /v3/countries tagastab selle asemel {"code": 200, "data": [...]}. Kontrollige iga lõpp-punkti dokumenteeritud vastust. Kui keha ei ole kehtiv JSON, näiteks pärast ootamatut serveritõrget, käsitlege päringut ebaõnnestununa ja proovige hiljem uuesti.

API tulemikoodid ja HTTP olek

status.code on API tulemikood. See ei ole HTTP olek. Autentimisvead saadetakse HTTP 401-ga. Vastasel juhul teatavad otsingulõpp-punktid sellistest tulemustest nagu 404 ja 500 ainult status.code väljal ega määra vastavat HTTP olekut. Seetõttu võib tulemus, mis teatab, et midagi ei leitud või et parameeter puudub, saabuda eduka HTTP olekuga. Kontrollige alati status.code enne response kasutamist.

Tulemikood 500 sõnumiga ISO Code parameter is required tähendab, et nõutav parameeter puudub. Parandage päringut, selle asemel et käsitleda seda serverikatkestusena.

Järgige next_function

Otsingutulemused sisaldavad välja next_function. See on suhteline tee ilma algkaldkriipsuta, mõnikord päringustringiga, näiteks v3/getareas/US või v3/getareas/US?state=NY. Lisage selle ette https://api.multitel.net/, et koostada järgmine päring, ja autentige see päring samamoodi. Valikulisi filtreid, mille saatsite, näiteks pid, ei kanta üle väljale next_function. Lisage need vajaduse korral uuesti.

Valikuline varude valija (pid)

getcountries, getstates ja getareas aktsepteerivad valikulist pid päringuparameetrit, mis kitsendab tulemused ühele varuallikale. Kasutage seda ainult MultiTEL-i antud väärtusega, kas numbrilisel kujul või 32-kohalises kuueteistkümnendsüsteemi kujul. Tavakasutuseks jätke see ära. Saatke pid päringustringis. Kui lõpp-punkt väärtust ei tunne või ei aktsepteeri, eirab seda veata ja päring käitub nii, nagu pid oleks ära jäetud.

Eraldage otsing tellimustest

Riigi, osariigi ja piirkonna otsingud ei muuda teie kontot. Erinumbrite kataloog (other) värskendab kataloogi üksikasju ja salvestab teie kontole hinnapakkumised, kuid ei esita tellimust. Ükski otsingupäring ei reserveeri numbrit ja varud võivad päringute vahel muutuda. Vaadake enne tellimislõpp-punkti kasutamist üle numbri nõuded ja hind.

Ostude, määrangute, sõnumite, faksisaatmiste ja muude toimingute puhul järgige selle lõpp-punkti enda kordusreegleid. Kui toiming pärast esitamist aegub, kontrollige enne kordamist selle olekut või oma konto kirjeid. Kadunud vastus ei tõesta, et toiming ebaõnnestus.