Получение сведений о маршрутизации

Запросите сведения о маршрутизации для североамериканского телефонного номера. Используйте их для интерпретации доступных данных о маршрутизации и операторе, а не как подтверждение личности абонента, принадлежности номера, возможности дозвона или доступности номера для покупки. За запрос могут списываться средства с вашего счета.

Запрос

Используйте свою активированную учетную запись API и разрешенный для нее исходящий IP-адрес. Укажите полный номер цифрами, включая код страны 1. В примере используются переменные окружения и вымышленный номер. Обработчик не нормализует знаки пунктуации; проверьте входные данные перед отправкой.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  https://api.multitel.net/v3/lrn/12025550123

Ответ

Для иллюстрации приведены лишь отдельные поля; их доступность зависит от источника и типа номера.

{
  "status": {
    "code": 200,
    "msg": "Success"
  },
  "response": {
    "lrn": "12025550123",
    "ocn": "0000",
    "local": 1,
    "ported": 0,
    "cost": "$0.00025"
  }
}

При стандартном запросе имена возвращаемых полей приводятся к нижнему регистру. В зависимости от источника могут присутствовать поля оператора, тарифного центра, местоположения и юрисдикции. Ответ не является полной записью об абоненте с фиксированным набором полей. Флаг local может иметь числовое значение 1 или строковое значение 0. Обработчик вычисляет ported, сравнивая возвращенный номер маршрутизации с переданным телефонным номером; не считайте это значение проверенной полной историей переноса номера.

Стоимость и повторные запросы

Проверенный обработчик списывает со счета $0.00025, когда выполнение достигает этапа завершения и запрос регистрируется. Возвращаемая стоимость обычно представляет собой строку со знаком доллара, а не просто числовую сумму. Ключ идемпотентности не предоставляется. Повторная отправка запроса может привести к еще одному списанию.

Для предоплатных счетов код проверяет, составляет ли остаток не менее 0.00025. В сообщении о недостаточном балансе сейчас указано $5, что не соответствует этому порогу. Расценивайте эту ошибку как отказ из-за баланса и проверьте наличие средств на счете перед повторным запросом.

Ошибки и неполные успешные ответы

Проверяйте как статус HTTP, так и status.code/status.msg в JSON. При пустом результате стандартного запроса возвращается код API 404. Код API 403 может указывать на недостаточный баланс предоплатного счета.

В текущей реализации один из сценариев ошибки для номеров с бесплатным для звонящего вызовом все же может приводить к списанию платы за запрос и возврату кода API 200 без полезных полей маршрутизации; сведения о стоимости могут быть неполными. Поэтому сам по себе код 200 не подтверждает, что результат запроса пригоден для использования. Проверяйте поля, необходимые вашему приложению, сверяйте спорные списания с платежными записями счета и обращайтесь в службу поддержки при неполных результатах.

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