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

Для покупок, назначений, сообщений, отправки факсов и других действий следуйте собственным правилам повтора этой конечной точки. Если действие превысило время ожидания после отправки, проверьте его статус или записи вашей учетной записи, прежде чем повторять его. Потерянный ответ не доказывает, что действие не выполнено.