Autentikimi dhe përgjigjet API

Përdorni kredenciale API

Dërgoni kërkesa v3 përmes HTTPS te https://api.multitel.net. Çdo pikë fundore në këtë udhëzues kërkon autentikim. Mbani kredencialet në serverin tuaj dhe mos i vendosni kurrë në JavaScript të shfletuesit, në faqe publike, në pamje ekrani ose në sistemet e kontrollit të versioneve.

Përdorni një nga këto forma kredencialesh:

• HTTP Basic me emrin e përdoruesit dhe fjalëkalimin API të konfiguruar për llogarinë tuaj MultiTEL.
• Shenjë Bearer në kreun Authorization: Bearer YOUR_API_TOKEN, për një llogari API të aktivizuar të konfiguruar për autentikim me shenjë. Kërkesat me shenjë pranohen vetëm nga adresat e lejuara për atë llogari API.

Nëse është konfiguruar një listë lejimesh IP për llogarinë tuaj API, dërgoni të gjitha kërkesat nga adresat e lejuara.

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

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

Variablat në këta shembuj janë vendmbajtës për kredencialet që ruani privatisht në mjedisin tuaj.

Trajtoni dështimet e autentikimit

Dështimet e autentikimit dërgohen me gjendjen HTTP 401. Trupi përdor zarfin standard, me status.code vendosur në 401 dhe një varg bosh si response.

• Pa kredenciale: status.msg është Username and password are required, dhe përgjigjja përfshin një sfidë autentikimi Basic.
• Shenja Bearer u refuzua: nëse kreu Authorization përdor skemën Bearer dhe shenja është e panjohur, e çaktivizuar ose e palejuar nga adresa juaj, status.msg është Invalid bearer token. Nuk provohen kredenciale të tjera kur është i pranishëm kreu Bearer.
• Kredenciale Basic të pavlefshme: status.msg fillon me A valid username and password pair are required., dhe përgjigjja përfshin një sfidë autentikimi Basic. Mesazhi mund të përmbajë më shumë tekst diagnostikues, prandaj mos e analizoni automatikisht në kod.

Mos u përpiqni automatikisht me të njëjtat kredenciale. Shumë përpjekje të dështuara nga një adresë brenda një periudhe të shkurtër mund të shkaktojnë bllokimin e kërkesave të mëtejshme nga ajo adresë.

Lexoni trupin e përgjigjes

Shumica e pikave fundore v3, duke përfshirë getcountries, getstates, getareas dhe other, kthen JSON në këtë zarf:

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

Kjo është një përgjigje ilustruese e listës së vendeve, jo një deklaratë e inventarit ose e aftësive aktuale.

Një përgjigje gabimi duket kështu:

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

Nëse një përgjigje nuk mund të kodohet, trupi ka status.code 500, status.msg Response encoding error, dhe një objekt bosh si response.

Pika fundore e trashëguar GET /v3/countries kthen {"code": 200, "data": [...]} në vend të kësaj. Kontrolloni përgjigjen e dokumentuar të secilës pikë fundore. Nëse një trup nuk është JSON i vlefshëm, për shembull pas një dështimi të papritur të serverit, trajtojeni kërkesën si të dështuar dhe riprovoni më vonë.

Kodet e rezultatit API dhe gjendja HTTP

status.code është kodi i rezultatit API. Nuk është gjendja HTTP. Dështimet e autentikimit dërgohen me HTTP 401. Përndryshe, pikat fundore të zbulimit raportojnë rezultate si 404 dhe 500 vetëm në status.code dhe nuk vendosin një gjendje HTTP përputhëse. Prandaj, një rezultat i pagjetur ose me parametër mungues mund të arrijë me një gjendje HTTP të suksesshme. Kontrolloni gjithmonë status.code përpara se të përdorni response.

Kodi i rezultatit 500 me mesazhin ISO Code parameter is required do të thotë se mungon një parametër i kërkuar. Korrigjoni kërkesën në vend që ta trajtoni si ndërprerje serveri.

Ndiqni next_function

Rezultatet e zbulimit përfshijnë next_function. Është një shteg relativ pa vijë të pjerrët në fillim, ndonjëherë me një varg pyetësor, si v3/getareas/US ose v3/getareas/US?state=NY. Parafijojeni me https://api.multitel.net/ për të ndërtuar kërkesën tjetër dhe autentikoni atë kërkesë në të njëjtën mënyrë. Filtrat opsionalë që dërguat, si pid, nuk barten në next_function. Shtojini përsëri nëse ju nevojiten.

Përzgjedhësi opsional i inventarit (pid)

getcountries, getstates dhe getareas pranojnë parametrin opsional të pyetësorit pid që ngushton rezultatet në një burim të vetëm inventari. Përdoreni vetëm me një vlerë të dhënë nga MultiTEL, qoftë në formën e saj numerike, qoftë në formën e saj heksadecimale me 32 karaktere. Hiqeni për përdorim normal. Dërgoni pid në vargun pyetësor. Nëse pika fundore nuk e njeh ose nuk e pranon vlerën, e injoron pa gabim dhe kërkesa sillet sikur pid të ishte hequr.

Ndani zbulimin nga porositë

Kërkimet e vendeve, shteteve dhe zonave nuk ndryshojnë llogarinë tuaj. Katalogu i numrave specialë (other) rifreskon detajet e katalogut dhe ruan ofertat e çmimeve për llogarinë tuaj, por nuk bën porosi. Asnjë kërkesë zbulimi nuk rezervon numër dhe inventari mund të ndryshojë midis kërkesave. Shqyrtoni kërkesat dhe çmimin për një numër përpara se të përdorni një pikë fundore porositjeje.

Për blerje, caktime, mesazhe, dërgime faksi dhe veprime të tjera, ndiqni rregullat e veta të riprovës të asaj pike fundore. Nëse një veprim skadon pas dërgimit, kontrolloni gjendjen e tij ose regjistrimet e llogarisë suaj përpara se ta përsërisni. Një përgjigje e humbur nuk provon se veprimi dështoi.