Stawing en API-antwoorde

Gebruik API-aanmeldbesonderhede

Stuur v3-versoeke oor HTTPS na https://api.multitel.net. Elke eindpunt in hierdie gids vereis stawing. Hou aanmeldbesonderhede op jou bediener, en plaas dit nooit in blaaier-JavaScript, openbare bladsye, skermkiekies of bronbeheer nie.

Gebruik een van hierdie vorme van aanmeldbesonderhede:

• HTTP Basic met die API-gebruikersnaam en wagwoord wat vir jou MultiTEL-rekening opgestel is.
• Bearer-token in 'n Authorization: Bearer YOUR_API_TOKEN -kop, vir 'n geaktiveerde API-rekening wat vir tokenstawing opgestel is. Tokenversoeke word slegs aanvaar vanaf adresse wat vir daardie API-rekening toegelaat word.

As 'n IP-toelaatlys vir jou API-rekening opgestel is, stuur alle versoeke vanaf toegelate adresse.

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

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

Die veranderlikes in hierdie voorbeelde is plekhouers vir aanmeldbesonderhede wat jy privaat in jou omgewing stoor.

Hanteer stawingsmislukkings

Stawingsmislukkings word met HTTP-status 401 gestuur. Die liggaam gebruik die standaardkoevert, met status.code gestel op 401 en 'n leë string as response.

• Geen aanmeldbesonderhede nie: status.msg is Username and password are required, en die antwoord sluit 'n Basic-stawinguitdaging in.
• Bearer-token verwerp: as die Authorization-kop die Bearer-skema gebruik en die token onbekend of gedeaktiveer is of nie vanaf jou adres toegelaat word nie, is status.msg se waarde Invalid bearer token. Geen ander aanmeldbesonderhede word probeer wanneer 'n Bearer-kop teenwoordig is nie.
• Ongeldige Basic-aanmeldbesonderhede: status.msg begin met A valid username and password pair are required., en die antwoord sluit 'n Basic-stawinguitdaging in. Die boodskap kan meer diagnostiese teks bevat, so moenie dit ontleed nie.

Moenie outomaties met dieselfde aanmeldbesonderhede weer probeer nie. Baie mislukte pogings vanaf een adres binne 'n kort tydperk kan veroorsaak dat verdere versoeke vanaf daardie adres geblokkeer word.

Lees die antwoordliggaam

Die meeste v3-eindpunte, insluitend getcountries, getstates, getareas en other, retourneer JSON in hierdie koevert:

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

Dit is 'n illustratiewe landlys-antwoord, nie 'n verklaring oor huidige voorraad of vermoëns nie.

'n Foutantwoord lyk so:

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

As 'n antwoord nie geënkodeer kan word nie, het die liggaam status.code 500, status.msg Response encoding error, en 'n leë objek as response.

Die verouderde eindpunt GET /v3/countries gee {"code": 200, "data": [...]} in plaas daarvan. Gaan elke eindpunt se gedokumenteerde antwoord na. As 'n liggaam nie geldige JSON is nie, byvoorbeeld na 'n onverwagte bedienerfout, behandel die versoek as misluk en probeer later weer.

API-resultaatkodes en HTTP-status

status.code is die API-resultaatkode. Dit is nie die HTTP-status nie. Stawingsmislukkings word met HTTP 401 gestuur. Andersins rapporteer die opsporing-eindpunte uitkomste soos 404 en 500 slegs in status.code en stel nie 'n ooreenstemmende HTTP-status nie. 'n Nie-gevind- of ontbrekende-parameter-resultaat kan dus met 'n suksesvolle HTTP-status aankom. Kontroleer altyd status.code voor die gebruik van response.

Resultaatkode 500 met die boodskap ISO Code parameter is required beteken 'n vereiste parameter ontbreek. Korrigier die versoek in plaas daarvan om dit as 'n bedieneronderbreking te beskou.

Volg next_function

Opsporingresultate sluit in next_function. Dit is 'n relatiewe pad sonder 'n leidende skuinsstreep, soms met 'n navraagstring, soos v3/getareas/US of v3/getareas/US?state=NY. Begin dit met https://api.multitel.net/ om die volgende versoek te bou, en staw daardie versoek op dieselfde manier. Opsionele filters wat jy gestuur het, soos pid, word nie oorgedra in next_function. Voeg hulle weer by as jy hulle nodig het.

Opsionele voorraadkieser (pid)

getcountries, getstates en getareas aanvaar 'n opsionele pid navraagparameter wat resultate tot een voorraadbron vernou. Gebruik dit slegs met 'n waarde wat deur MultiTEL verskaf word, in óf sy numeriese vorm óf sy 32-karakter heksadesimale vorm. Laat dit weg vir normale gebruik. Stuur pid in die navraagstring. As die eindpunt nie die waarde herken of aanvaar nie, ignoreer dit dit sonder 'n fout, en die versoek gedra hom asof pid weggelaat is.

Skei opsporing van bestellings

Land-, staat- en gebiedsoektogte verander nie jou rekening nie. Die spesiale-nommer-katalogus (other) verfris katalogusbesonderhede en stoor pryskwotasies vir jou rekening, maar plaas nie 'n bestelling nie. Geen opsporingversoek reserveer 'n nommer nie, en voorraad kan tussen versoeke verander. Hersien die vereistes en prys vir 'n nommer voor die gebruik van 'n bestelling-eindpunt.

Vir aankope, toewysings, boodskappe, faksversendings en ander aksies, volg daardie eindpunt se eie herprobeerreëls. As 'n aksie na indiening uittyd, gaan sy status of jou rekeningrekords na voor jy dit herhaal. 'n Verlore antwoord bewys nie dat die aksie misluk het nie.