Автентифікація та відповіді 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) оновлює деталі каталогу та зберігає цінові пропозиції для вашого облікового запису, але не розміщує замовлення. Жоден запит пошуку не резервує номер, а запаси можуть змінюватися між запитами. Перед використанням кінцевої точки замовлення перегляньте вимоги та ціну номера.

Для покупок, призначень, повідомлень, надсилання факсів та інших дій дотримуйтесь власних правил повторних спроб цієї кінцевої точки. Якщо дія перевищила час очікування після надсилання, перевірте її статус або записи свого облікового запису, перш ніж повторювати її. Втрачена відповідь не доводить, що дія не вдалася.