Autentifikācija un API atbildes

Izmantojiet API akreditācijas datus

Sūtiet v3 pieprasījumus, izmantojot HTTPS, uz https://api.multitel.net. Katrs šīs rokasgrāmatas galapunkts pieprasa autentifikāciju. Glabājiet akreditācijas datus savā serverī un nekad neievietojiet tos pārlūkprogrammas JavaScript, publiskās lapās, ekrānuzņēmumos vai versiju kontrolē.

Izmantojiet vienu no šiem akreditācijas datu veidiem:

• HTTP Basic ar API lietotājvārdu un paroli, kas konfigurēti jūsu MultiTEL kontam.
• Bearer žetons ar Authorization: Bearer YOUR_API_TOKEN galveni, kas paredzēta iespējotam API kontam ar konfigurētu žetona autentifikāciju. Žetona pieprasījumi tiek pieņemti tikai no adresēm, kas atļautas šim API kontam.

Ja IP atļauto adrešu saraksts ir konfigurēts jūsu API kontam, sūtiet visus pieprasījumus no atļautajām adresēm.

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

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

Šajos piemēros izmantotie mainīgie ir vietturi akreditācijas datiem, kurus jūs privāti glabājat savā vidē.

Apstrādājiet autentifikācijas kļūmes

Autentifikācijas kļūmes tiek nosūtītas ar HTTP statusu 401. Ķermenis izmanto standarta aploksni kopā ar status.code iestatītu uz 401 un tukšu virkni kā response.

• Nav akreditācijas datu: status.msg ir Username and password are required, un atbilde ietver Basic autentifikācijas izaicinājumu.
• Bearer žetons noraidīts: ja Authorization galvene izmanto Bearer shēmu un žetons nav zināms, ir atspējots vai nav atļauts no jūsu adreses, status.msg ir Invalid bearer token. Ja ir norādīta Bearer galvene, citi akreditācijas dati netiek mēģināti.
• Nederīgi Basic akreditācijas dati: status.msg sākas ar A valid username and password pair are required., un atbilde ietver Basic autentifikācijas izaicinājumu. Ziņojums var saturēt papildu diagnostikas tekstu, tāpēc neparsējiet to programmkodā.

Automātiski nemēģiniet vēlreiz ar tiem pašiem akreditācijas datiem. Daudzi neveiksmīgi mēģinājumi no vienas adreses īsā laikā var izraisīt turpmāku pieprasījumu bloķēšanu no šīs adreses.

Lasiet atbildes ķermeni

Lielākā daļa v3 galapunktu, tostarp getcountries, getstates, getareas un other, atgriež JSON šajā aploksnē:

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

Šī ir ilustratīva valsts saraksta atbilde, nevis paziņojums par pašreizējo krājumu vai iespējām.

Kļūdas atbilde izskatās šādi:

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

Ja atbildi nevar iekodēt, ķermenis satur status.code 500, status.msg Response encoding error, un tukšu objektu kā response.

Mantotais galapunkts GET /v3/countries tā vietā atgriež {"code": 200, "data": [...]}. Pārbaudiet katra galapunkta dokumentēto atbildi. Ja ķermenis nav derīgs JSON, piemēram, pēc negaidītas servera kļūmes, uzskatiet pieprasījumu par neizdevušos un mēģiniet vēlāk.

API rezultātu kodi un HTTP statuss

status.code ir API rezultāta kods. Tas nav HTTP statuss. Autentifikācijas kļūmes tiek nosūtītas ar HTTP 401. Pretējā gadījumā meklēšanas galapunkti ziņo par tādiem rezultātiem kā 404 un 500 tikai laukā status.code un neiestata atbilstošu HTTP statusu. Tāpēc rezultāts par neatrastu vienumu vai trūkstošu parametru var pienākt ar veiksmīgu HTTP statusu. Vienmēr pārbaudiet status.code pirms response izmantošanas.

Rezultāta kods 500 ar ziņojumu ISO Code parameter is required nozīmē, ka trūkst obligāts parametrs. Izlabojiet pieprasījumu, nevis uzskatiet to par servera darbības pārtraukumu.

Sekojiet next_function

Meklēšanas rezultātos ir ietverts next_function. Tas ir relatīvs ceļš bez sākuma slīpsvītras, dažreiz ar vaicājuma virkni, piemēram, v3/getareas/US vai v3/getareas/US?state=NY. Pievienojiet tam priekšā https://api.multitel.net/, lai izveidotu nākamo pieprasījumu, un autentificējiet šo pieprasījumu tāpat. Neobligātie filtri, ko nosūtījāt, piemēram, pid, netiek pārnesti uz next_function. Ja tie ir nepieciešami, pievienojiet tos vēlreiz.

Neobligāts krājumu atlasītājs (pid)

getcountries, getstates un getareas pieņem neobligātu pid vaicājuma parametru, kas sašaurina rezultātus līdz vienam krājumu avotam. Izmantojiet to tikai ar MultiTEL nodrošinātu vērtību skaitliskā formā vai 32 rakstzīmju heksadecimālā formā. Parastai lietošanai to neizmantojiet. Sūtiet pid vaicājuma virknē. Ja galapunkts vērtību neatpazīst vai nepieņem, tas to ignorē bez kļūdas, un pieprasījums darbojas tā, it kā pid būtu izlaists.

Nošķiriet meklēšanu no pasūtījumiem

Valsts, pavalsts un apgabala uzziņas nemaina jūsu kontu. Īpašo numuru katalogs (other) atjaunina kataloga datus un saglabā cenu piedāvājumus jūsu kontam, bet neveic pasūtījumu. Neviens meklēšanas pieprasījums nerezervē numuru, un krājumi starp pieprasījumiem var mainīties. Pirms pasūtīšanas galapunkta izmantošanas pārskatiet numura prasības un cenu.

Pirkumiem, piešķīrumiem, ziņojumiem, faksa sūtījumiem un citām darbībām ievērojiet attiecīgā galapunkta atkārtošanas noteikumus. Ja pēc darbības pieprasījuma nosūtīšanas beidzas gaidīšanas laiks, pirms atkārtota pieprasījuma pārbaudiet darbības statusu vai sava konta ierakstus. Zaudēta atbilde nepierāda, ka darbība neizdevās.