Provjera autentičnosti i API odgovori

Koristite API vjerodajnice

Šaljite v3 zahtjeve putem HTTPS na https://api.multitel.net. Svaka krajnja točka u ovom vodiču zahtijeva provjeru autentičnosti. Čuvajte vjerodajnice na svojem poslužitelju i nikada ih nemojte stavljati u JavaScript preglednika, na javne stranice, snimke zaslona ili u kontrolu izvornog koda.

Koristite jedan od ovih oblika vjerodajnica:

• HTTP Basic s API korisničkim imenom i lozinkom konfiguriranima za vaš MultiTEL račun.
• Bearer token u zaglavlju Authorization: Bearer YOUR_API_TOKEN za omogućen API račun konfiguriran za provjeru autentičnosti tokenom. Zahtjevi s tokenom prihvaćaju se samo s adresa dopuštenih za taj API račun.

Ako je popis dopuštenih IP adresa konfiguriran za vaš API račun, šaljite sve zahtjeve s dopuštenih adresa.

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

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

Varijable u ovim primjerima zamjenske su vrijednosti za vjerodajnice koje privatno čuvate u svojem okruženju.

Obradite neuspjele provjere autentičnosti

Neuspjele provjere autentičnosti šalju se s HTTP statusom 401. Tijelo koristi standardnu omotnicu, sa status.code postavljenim na 401 i praznim nizom kao response.

• Nema vjerodajnica: status.msg je Username and password are required, a odgovor uključuje Basic izazov za provjeru autentičnosti.
• Bearer token odbijen: ako zaglavlje Authorization koristi shemu Bearer, a token je nepoznat, onemogućen ili nije dopušten s vaše adrese, status.msg je Invalid bearer token. Ne isprobavaju se druge vjerodajnice kada je prisutno Bearer zaglavlje.
• Nevažeće Basic vjerodajnice: status.msg počinje s A valid username and password pair are required., a odgovor uključuje Basic izazov za provjeru autentičnosti. Poruka može sadržavati više dijagnostičkog teksta, pa je nemojte raščlanjivati.

Nemojte automatski ponovno pokušavati s istim vjerodajnicama. Mnogi neuspjeli pokušaji s jedne adrese u kratkom razdoblju mogu uzrokovati blokiranje daljnjih zahtjeva s te adrese.

Pročitajte tijelo odgovora

Većina v3 krajnjih točaka, uključujući getcountries, getstates, getareas i other, vraća JSON u ovoj omotnici:

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

Ovo je ilustrativni odgovor s popisom zemalja, a ne izjava o trenutačnom inventaru ili mogućnostima.

Odgovor o pogrešci izgleda ovako:

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

Ako se odgovor ne može kodirati, tijelo ima status.code 500, status.msg Response encoding error, i prazan objekt kao response.

Starija krajnja točka GET /v3/countries vraća {"code": 200, "data": [...]} umjesto toga. Provjerite dokumentirani odgovor svake krajnje točke. Ako tijelo nije valjani JSON, na primjer nakon neočekivanog kvara poslužitelja, tretirajte zahtjev kao neuspješan i pokušajte ponovno kasnije.

API kodovi rezultata i HTTP status

status.code je API kôd rezultata. To nije HTTP status. Neuspjele provjere autentičnosti šalju se s HTTP 401. U suprotnom, krajnje točke za otkrivanje prijavljuju ishode poput 404 i 500 samo u status.code i ne postavljaju odgovarajući HTTP status. Rezultat koji označava da traženo nije pronađeno ili da nedostaje parametar stoga može stići s uspješnim HTTP statusom. Uvijek provjerite status.code prije korištenja response.

Kôd rezultata 500 s porukom ISO Code parameter is required znači da nedostaje obvezni parametar. Ispravite zahtjev umjesto da to tretirate kao ispad poslužitelja.

Slijedite next_function

Rezultati otkrivanja uključuju next_function. To je relativna staza bez početne kose crte, ponekad s nizom upita, kao što je v3/getareas/US ili v3/getareas/US?state=NY. Stavite https://api.multitel.net/ ispred kako biste sastavili sljedeći zahtjev i provjerili autentičnost tog zahtjeva na isti način. Neobvezni filtri koje ste poslali, kao što je pid, ne prenose se u next_function. Dodajte ih ponovno ako su vam potrebni.

Neobvezni birač inventara (pid)

getcountries, getstates i getareas prihvaćaju neobvezni parametar upita pid koji sužava rezultate na jedan izvor inventara. Koristite ga samo s vrijednošću koju je dao MultiTEL, bilo u brojčanom obliku ili u 32-znakovnom heksadecimalnom obliku. Izostavite ga za uobičajenu upotrebu. Pošaljite pid u nizu upita. Ako krajnja točka ne prepozna ili ne prihvati vrijednost, zanemaruje je bez pogreške, a zahtjev se ponaša kao da je pid bio izostavljen.

Odvojite otkrivanje od narudžbi

Pretraživanja zemalja, saveznih država i područja ne mijenjaju vaš račun. Katalog posebnih brojeva (other) osvježava pojedinosti kataloga i sprema ponude cijena za vaš račun, ali ne izvršava narudžbu. Nijedan zahtjev za otkrivanje ne rezervira broj, a inventar se može promijeniti između zahtjeva. Pregledajte zahtjeve i cijenu za broj prije korištenja krajnje točke za naručivanje.

Za kupnje, dodjele, poruke, slanja faksa i druge radnje slijedite vlastita pravila o ponovnom pokušaju te krajnje točke. Ako nakon slanja zahtjeva za radnju istekne vrijeme čekanja, provjerite status radnje ili zapise svog računa prije ponovnog slanja zahtjeva. Izgubljeni odgovor ne dokazuje da radnja nije uspjela.