Autentificare și răspunsuri API

Utilizați acreditări API

Trimiteți solicitări v3 prin HTTPS către https://api.multitel.net. Fiecare punct final din acest ghid necesită autentificare. Păstrați acreditările pe serverul propriu și nu le puneți niciodată în JavaScript din navigator, în pagini publice, în capturi de ecran sau în sisteme de control al versiunilor.

Utilizați una dintre aceste forme de acreditări:

• HTTP Basic cu acreditările de tip nume de utilizator și parolă API configurate pentru contul dumneavoastră MultiTEL.
• Jeton Bearer într-un antet Authorization: Bearer YOUR_API_TOKEN, pentru un cont API activat configurat pentru autentificarea cu jeton. Solicitările cu jeton sunt acceptate numai de la adresele permise pentru acel cont API.

Dacă este configurată o listă de adrese IP permise pentru contul dumneavoastră API, trimiteți toate solicitările de la adrese permise.

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

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

Variabilele din aceste exemple sunt substituenți pentru acreditările pe care le stocați privat în mediul dumneavoastră.

Gestionați eșecurile de autentificare

Eșecurile de autentificare sunt trimise cu starea HTTP 401. Corpul utilizează plicul standard, cu status.code setat la 401 și un șir gol ca response.

• Fără acreditări: status.msg este Username and password are required, iar răspunsul include o provocare de autentificare Basic.
• Jeton Bearer respins: dacă antetul Authorization utilizează schema Bearer, iar jetonul este necunoscut, dezactivat sau nepermis de la adresa dumneavoastră, status.msg este Invalid bearer token. Nu se încearcă alte acreditări atunci când este prezent un antet Bearer.
• Acreditări Basic nevalide: status.msg începe cu A valid username and password pair are required., iar răspunsul include o provocare de autentificare Basic. Mesajul poate conține mai mult text de diagnostic, deci nu îl parsați în program.

Nu reîncercați automat cu aceleași acreditări. Multe încercări eșuate de la o adresă într-o perioadă scurtă pot cauza blocarea solicitărilor ulterioare de la acea adresă.

Citiți corpul răspunsului

Majoritatea punctelor finale v3, inclusiv getcountries, getstates, getareas și other, returnează JSON în acest plic:

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

Acesta este un răspuns ilustrativ de tip listă de țări, nu o declarație privind inventarul sau capacitățile actuale.

Un răspuns de eroare arată astfel:

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

Dacă un răspuns nu poate fi codificat, corpul are status.code 500, status.msg Response encoding error, și un obiect gol ca response.

Punctul final vechi GET /v3/countries returnează {"code": 200, "data": [...]} în schimb. Verificați răspunsul documentat al fiecărui punct final. Dacă un corp nu este JSON valid, de exemplu după o defecțiune neașteptată a serverului, tratați solicitarea ca eșuată și reîncercați mai târziu.

Coduri de rezultat API și stare HTTP

status.code este codul de rezultat API. Nu este starea HTTP. Eșecurile de autentificare sunt trimise cu HTTP 401. În caz contrar, punctele finale de descoperire raportează rezultate precum 404 și 500 numai în status.code și nu setează o stare HTTP corespunzătoare. Prin urmare, un rezultat de tip negăsit sau cu parametru lipsă poate sosi cu o stare HTTP de succes. Verificați întotdeauna status.code înainte de a utiliza response.

Codul de rezultat 500 cu mesajul ISO Code parameter is required înseamnă că lipsește un parametru obligatoriu. Corectați solicitarea în loc să o tratați ca pe o întrerupere a serverului.

Urmați next_function

Rezultatele descoperirii includ next_function. Este o cale relativă fără bară oblică inițială, uneori cu un șir de interogare, cum ar fi v3/getareas/US sau v3/getareas/US?state=NY. Prefixați-o cu https://api.multitel.net/ pentru a construi următoarea solicitare și autentificați acea solicitare în același mod. Filtrele opționale pe care le-ați trimis, cum ar fi pid, nu sunt preluate în next_function. Adăugați-le din nou dacă aveți nevoie de ele.

Selector opțional de inventar (pid)

getcountries, getstates și getareas acceptă parametrul opțional de interogare pid care restrânge rezultatele la o singură sursă de inventar. Utilizați-l numai cu o valoare furnizată de MultiTEL, fie în forma sa numerică, fie în forma sa hexazecimală de 32 de caractere. Omiteți-l pentru utilizarea normală. Trimiteți pid în șirul de interogare. Dacă punctul final nu recunoaște sau nu acceptă valoarea, o ignoră fără eroare, iar solicitarea se comportă ca și cum pid ar fi fost omis.

Separați descoperirea de comenzi

Căutările de țări, state și zone nu modifică contul dumneavoastră. Catalogul de numere speciale (other) reîmprospătează detaliile catalogului și salvează ofertele de preț pentru contul dumneavoastră, dar nu plasează o comandă. Nicio solicitare de descoperire nu rezervă un număr, iar inventarul se poate schimba între solicitări. Examinați cerințele și prețul pentru un număr înainte de a utiliza un punct final de comandă.

Pentru achiziții, atribuiri, mesaje, trimiteri de fax și alte acțiuni, urmați propriile reguli de reîncercare ale acelui punct final. Dacă o acțiune expiră după trimitere, verificați starea acesteia sau înregistrările contului înainte de a o repeta. Un răspuns pierdut nu dovedește că acțiunea a eșuat.