Удостоверяване и 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": 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) опреснява детайлите на каталога и запазва ценови оферти за вашия акаунт, но не прави поръчка. Никоя заявка за откриване не резервира номер, а инвентарът може да се промени между заявките. Прегледайте изискванията и цената за номер, преди да използвате крайна точка за поръчка.

За покупки, възлагания, съобщения, изпращания на факсове и други действия следвайте собствените правила за повторен опит на тази крайна точка. Ако дадено действие изтече след изпращането, проверявайте състоянието му или записите на акаунта си, преди да го повторите. Изгубеният отговор не доказва, че действието се е провалило.