Аутентификација и API одговори

Користите API акредитиве

Шаљите v3 захтеве преко HTTPS на https://api.multitel.net. Свака крајња тачка у овом водичу захтева аутентификацију. Чувајте акредитиве на свом серверу и никада их не стављајте у JavaScript прегледача, јавне странице, снимке екрана или контролу изворног кода.

Користите један од ових облика акредитива:

HTTP Basic са API корисничким именом и лозинком конфигурисаним за ваш MultiTEL налог.
Bearer токен у заглављу Authorization: Bearer YOUR_API_TOKEN, за омогућени API налог конфигурисан за аутентификацију токеном. Захтеви са токеном се прихватају само са адреса дозвољених за тај API налог.

Ако је IP листа дозвољених конфигурисана за ваш API налог, шаљите све захтеве са дозвољених адреса.

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

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

Променљиве у овим примерима су чувари места за акредитиве које приватно чувате у свом окружењу.

Обрадите неуспеле аутентификације

Неуспеле аутентификације се шаљу са HTTP статусом 401. Тело користи стандардну коверту, са status.code постављеним на 401 и празном ниском као response.

Нема акредитива: status.msg је Username and password are required, а одговор укључује Basic изазов аутентификације.
Bearer токен одбијен: ако Authorization заглавље користи Bearer шему и токен је непознат, онемогућен или није дозвољен са ваше адресе, status.msg је Invalid bearer token. Никакви други акредитиви се не испробавају када је Bearer заглавље присутно.
Неважећи Basic акредитиви: status.msg почиње са A valid username and password pair are required., а одговор укључује Basic изазов аутентификације. Порука може да садржи више дијагностичког текста, па је немојте парсирати.

Немојте аутоматски поново покушавати са истим акредитивима. Многи неуспели покушаји са једне адресе у кратком периоду могу довести до блокирања даљих захтева са те адресе.

Прочитајте тело одговора

Већина v3 крајњих тачака, укључујући getcountries, getstates, getareas и other, враћа JSON у овој коверти:

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

Ово је илустративни одговор са листом земаља, а не изјава о тренутном инвентару или могућностима.

Поље	Значење
`status.code`	API код резултата, на пример `200`, `401`, `404` или `500`.
`status.msg`	Људски читљива порука. Може бити празна. Засните логику програма на `status.code`, а не на тексту поруке.
`status.results`	Број уноса. За крајње тачке за откривање документоване овде, присутан је када је `response` JSON листа, укључујући празну листу (`0`). Одсутан је када је `response` празна ниска или `null`. Други садржаји крајњих тачака могу другачије пријавити број; пратите њихову сопствену документацију одговора.
`response`	Садржај крајње тачке. Његов тип зависи од крајње тачке и исхода. У случају грешака, то је празна ниска.

Одговор о грешци изгледа овако:

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

Ако одговор не може да се кодира, тело садржи status.code 500, status.msg Response encoding error, и празан објекат као response.

Старија крајња тачка GET /v3/countries враћа {"code": 200, "data": [...]} уместо тога. Проверите документовани одговор сваке крајње тачке. Ако тело није важећи JSON, на пример након неочекиваног отказа сервера, третирајте захтев као неуспео и покушајте поново касније.

API кодови резултата и HTTP статус

status.code је API код резултата. То није HTTP статус. Неуспеле аутентификације се шаљу са HTTP 401. У супротном, крајње тачке за откривање пријављују исходе као што су 404 и 500 само у status.code и не постављају одговарајући HTTP статус. Резултат који указује да тражено није пронађено или да недостаје параметар стога може стићи са успешним HTTP статусом. Увек проверите status.code пре коришћења response.

Код резултата 500 са поруком ISO Code parameter is required значи да недостаје обавезни параметар. Исправите захтев уместо да га третирате као прекид рада сервера.

Пратите next_function

Резултати откривања укључују next_function. То је релативна путања без почетне косе црте, понекад са ниском упита, као што је v3/getareas/US или v3/getareas/US?state=NY. Испред те путање додајте https://api.multitel.net/ да бисте изградили следећи захтев, и аутентификујте тај захтев на исти начин. Опциони филтери које сте послали, као што је pid, се не преносе у next_function. Додајте их поново ако су вам потребни.

Опциони селектор инвентара (pid)

getcountries, getstates и getareas прихватају опциони параметар упита pid који сужава резултате на један извор инвентара. Користите га само са вредношћу коју је обезбедио MultiTEL, у нумеричком облику или у 32-карактерном хексадекадном облику. Изоставите га за нормалну употребу. Пошаљите pid у ниски упита. Ако крајња тачка не препознаје или не прихвата вредност, игнорише је без грешке, а захтев се понаша као да је pid био изостављен.

Одвојите откривање од поруџбина

Претраге држава, савезних држава и области не мењају ваш налог. Каталог специјалних бројева (other) освежава детаље каталога и чува понуде цена за ваш налог, али не прави поруџбину. Ниједан захтев за откривање не резервише број, а инвентар се може променити између захтева. Прегледајте захтеве и цену за број пре коришћења крајње тачке за наручивање.

За куповине, доделе, поруке, слање факсова и друге радње, пратите сопствена правила понављања те крајње тачке. Ако након слања захтева за радњу истекне време чекања, проверите статус те радње или евиденцију вашег налога пре него што поновите захтев. Изгубљени одговор не доказује да радња није успела.