Autentifikavimas ir API atsakymai

Naudokite API kredencialus

Siųskite v3 užklausas per HTTPS adresu https://api.multitel.net. Kiekvienam šiame vadove aprašytam galutiniam taškui būtinas autentifikavimas. Laikykite kredencialus savo serveryje ir niekada nedėkite jų į naršyklės JavaScript, viešuosius puslapius, ekrano kopijas ar versijų valdymo sistemą.

Naudokite vieną iš šių kredencialų formų:

• HTTP Basic su API naudotojo vardu ir slaptažodžiu, sukonfigūruotais jūsų MultiTEL paskyrai.
• Bearer žetonas pateikiamas Authorization: Bearer YOUR_API_TOKEN antraštėje, skirtoje įjungtai API paskyrai, sukonfigūruotai žetonų autentifikavimui. Žetonų užklausos priimamos tik iš adresų, leidžiamų tai API paskyrai.

Jei IP leidžiamųjų sąrašas sukonfigūruotas jūsų API paskyrai, visas užklausas siųskite iš leidžiamų adresų.

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

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

Šiuose pavyzdžiuose naudojami kintamieji yra vietos žymės kredencialams, kuriuos privačiai saugote savo aplinkoje.

Tvarkykite autentifikavimo klaidas

Autentifikavimo klaidos siunčiamos su HTTP būsena 401. Kūnas naudoja standartinį voką, kuriame status.code yra 401, o tuščia eilutė pateikiama kaip response.

• Nėra kredencialų: status.msg yra Username and password are required, o atsakyme pateikiamas Basic autentifikavimo iššūkis.
• Bearer žetonas atmestas: jei Authorization antraštėje naudojama Bearer schema, o žetonas nežinomas, išjungtas arba neleidžiamas iš jūsų adreso, status.msg yra Invalid bearer token. Jokie kiti kredencialai nebandomi, kai pateikiama Bearer antraštė.
• Neteisingi Basic kredencialai: status.msg prasideda A valid username and password pair are required., o atsakyme pateikiamas Basic autentifikavimo iššūkis. Pranešime gali būti daugiau diagnostinio teksto, todėl neanalizuokite jo programiškai.

Automatiškai nepakartokite užklausos su tais pačiais kredencialais. Daug nepavykusių bandymų iš vieno adreso per trumpą laiką gali lemti tolesnių užklausų iš to adreso blokavimą.

Skaitykite atsakymo kūną

Dauguma v3 galutinių taškų, įskaitant getcountries, getstates, getareas ir other, grąžina JSON šiame voke:

{
  "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"
    }
  ]
}

Tai iliustracinis šalių sąrašo atsakymas, o ne teiginys apie dabartines atsargas ar galimybes.

Klaidos atsakymas atrodo taip:

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

Jei atsakymo nepavyksta užkoduoti, kūne yra status.code 500, status.msg Response encoding error, o tuščias objektas pateikiamas kaip response.

Senasis galutinis taškas GET /v3/countries grąžina {"code": 200, "data": [...]} vietoj to. Patikrinkite kiekvieno galutinio taško dokumentuotą atsakymą. Jei kūnas nėra tinkamas JSON, pavyzdžiui, po netikėto serverio gedimo, laikykite užklausą nepavykusia ir bandykite dar kartą vėliau.

API rezultatų kodai ir HTTP būsena

status.code yra API rezultato kodas. Tai nėra HTTP būsena. Autentifikavimo klaidos siunčiamos su HTTP 401. Kitu atveju paieškos galutiniai taškai pateikia rezultatus, tokius kaip 404 ir 500 tik lauke status.code ir nenustato atitinkamos HTTP būsenos. Todėl neradimo arba trūkstamo parametro rezultatas gali atvykti su sėkminga HTTP būsena. Visada patikrinkite status.code prieš naudodami response.

Rezultato kodas 500 su pranešimu ISO Code parameter is required reiškia, kad trūksta privalomo parametro. Pataisykite užklausą, o ne laikykite tai serverio gedimu.

Sekite next_function

Paieškos rezultatuose yra next_function. Tai santykinis kelias be pradinio pasvirojo brūkšnio, kartais su užklausos eilute, pavyzdžiui, v3/getareas/US arba v3/getareas/US?state=NY. Pridėkite prieš jį https://api.multitel.net/ kad sukurtumėte kitą užklausą, ir autentifikuokite tą užklausą tuo pačiu būdu. Pasirenkami filtrai, kuriuos siuntėte, pavyzdžiui, pid, nėra perkeliami į next_function. Jei jų reikia, pridėkite juos dar kartą.

Pasirenkamas atsargų parinkiklis (pid)

getcountries, getstates ir getareas priima pasirenkamą pid užklausos parametrą, kuris susiaurina rezultatus iki vieno atsargų šaltinio. Naudokite jį tik su MultiTEL pateikta reikšme, skaitine forma arba 32 simbolių šešioliktainine forma. Įprastam naudojimui jo nenurodykite. Siųskite pid užklausos eilutėje. Jei galutinis taškas neatpažįsta reikšmės arba jos nepriima, jis ignoruoja ją be klaidos, ir užklausa veikia taip, lyg pid būtų buvęs praleistas.

Atskyrkite paiešką nuo užsakymų

Šalių, valstijų ir vietovių paieškos nekeičia jūsų paskyros. Specialiųjų numerių katalogas (other) atnaujina katalogo duomenis ir išsaugo kainų pasiūlymus jūsų paskyrai, bet nepateikia užsakymo. Jokia paieškos užklausa nerezervuoja numerio, o atsargos gali keistis tarp užklausų. Prieš naudodami užsakymo galutinį tašką, peržiūrėkite numerio reikalavimus ir kainą.

Pirkimams, priskyrimams, pranešimams, faksų siuntimams ir kitiems veiksmams vadovaukitės to galutinio taško pakartojimo taisyklėmis. Jei veiksmas po pateikimo baigiasi skirtojo laiko pabaiga, prieš kartodami jį patikrinkite jo būseną arba savo paskyros įrašus. Prarastas atsakymas neįrodo, kad veiksmas nepavyko.