Документация REST API
REST API поиска маршрутизации LRN
Узнавайте номер маршрутизации и доступную информацию об операторе для североамериканского телефонного номера по фиксированной цене.
Выбирайте API и учётные данные вместе
Одобренные аккаунты с профилями «Разработчики и автоматизация», «Бизнес» и «Операторы связи» могут интегрироваться с включёнными сервисами. Частному разработчику не нужно выдавать себя за компанию. Для SMS/MMS из приложений требуются соответствующее разрешение на отправку и регистрация. У сервиса «Для частных лиц и семей» нет доступного клиентам API для отправки сообщений.
| Семейство API | Базовый URL | Аутентификация и результат |
|---|---|---|
| Communications v3 | https://api.multitel.net/v3 | Одобренные учётные данные Basic; выданные токены, если они допустимы, — только для операций, которые их поддерживают. В JSON — status и response. |
| Регистрация экстренных вызовов | https://api.multi.tel/emergency | Одобренные учётные данные Basic или специально выданный bearer-доступ. В JSON — code, message и data. |
| REST-интеграции портала | Хост и операция указаны в справочнике разработчика вашего аккаунта | Используйте учётные данные, области доступа (scopes) и схему, описанные для этой операции. Запросы из браузерной сессии относятся к отдельному контуру. |
Перед использованием примеров задайте MULTITEL_API_USERNAME и MULTITEL_API_PASSWORD через конфигурацию секретов вашего сервера. Никогда не встраивайте их в публичный браузерный JavaScript, URL или систему контроля версий. Отдельные учётные данные управляются в разделе настроек интеграции API.
Поиск номера
GET /v3/lrn/{number} принимает номер назначения в пути запроса. Необязательный номер вызывающего абонента можно передать как /v3/lrn/{number}/{ani} для получения информации, зависящей от источника вызова. Указывайте североамериканские телефонные номера только цифрами, с кодом страны там, где это применимо; в примерах используются зарезервированные вымышленные номера.
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
"https://api.multitel.net/v3/lrn/12025550123"curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
"https://api.multitel.net/v3/lrn/12025550123/12025550124"Выполнение поиска с действительными учётными данными тарифицируется. Стоимость — 0,00025 $ за один поиск: 0,25 $ за 1 000 или 250 $ за миллион. Скидок за объём нет. Это поиск маршрутной информации; телефонный вызов он не совершает.
Чтение результата
{
"status": {
"code": 200,
"msg": "Success"
},
"response": {
"lrn": "12025550123",
"ported": 0,
"ocn": "",
"lata": "",
"rc": "",
"cost": "$0.00025"
}
}Этот придуманный пример демонстрирует только структуру ответа; это не результат реальной маршрутизации. Прежде чем использовать response, проверьте status.code. Поле cost — строка с префиксом валюты, а не число JSON.
| Поле | Значение |
|---|---|
lrn | Location Routing Number — номер, определяющий пункт назначения маршрутизации. |
ported | Индикатор переноса номера, возвращаемый этим поиском: как правило, 0 или 1. Не используйте его как доказательство владения номером или права на услугу. |
ocn | Operating Company Number, если предоставлен. |
lata | Local Access and Transport Area, если предоставлена. |
rc | Rate center (тарифный центр), если предоставлен. |
city, state, lec, lectype, jurisdiction, local | Дополнительные сведения о местоположении, операторе или источнике, если они доступны. Они могут отсутствовать или быть пустыми. |
Не требуйте наличия всех полей маршрутизации. В частности, в результатах для номеров с бесплатными вызовами для звонящего могут отсутствовать данные о местном тарифном центре и коде оператора. Возвращённый LRN не гарантирует доступность абонента в реальном времени и не является проверкой качества вызова.
Использование поиска в вашем процессе маршрутизации
- Перед отправкой проверьте и нормализуйте запрашиваемый номер.
- Проверяйте HTTP-статус и статус приложения. Для диагностики храните запись о номере, времени и результате с удалёнными конфиденциальными данными.
- Используйте только те поля, которые нужны вашему правилу маршрутизации, и явно обрабатывайте отсутствующие значения.
- Ограничивайте число повторов после неопределённого ответа. Повторный поиск может привести к ещё одному списанию; для этой конечной точки не задокументирован ключ идемпотентности.
Подробнее о продукте LRN и едином тарифе. Публичный путь OpenAPI включает сегмент ANI; развёрнутая реализация LRN также принимает более короткий запрос без ANI. lrninfo — отдельная операция, и её не следует подставлять вместо этой конечной точки.
Обработка ошибок и повторных запросов
- Сбой аутентификации или прав доступа
- Проверьте, включены ли учётные данные API, разрешён ли нужный сервис и не мешает ли ограничение по исходному IP-адресу. Cookie сессии портала не является учётными данными для интеграции.
- Недостаточно средств или не выполнено требование об одобрении
- Прежде чем повторять операцию, устраните проблему с балансом аккаунта, разрешением на отправку или требованием о документах.
- Нет результата
- Пустой список номеров или отсутствие имени вызывающего абонента считайте обычным исходом. Не предполагайте, что для синтаксически корректного номера доступны все услуги.
- Тайм-аут сети или сбой сервиса
- Для операций чтения используйте ограниченное число повторов с задержкой (backoff). Перед повтором покупки, отправки или регистрации сначала проверьте состояние операции: повторение принятого запроса может привести к дублированию платного действия.
Поддержка идемпотентности зависит от семейства API. Emergency API поддерживает ключи повтора, но это не делает идемпотентными произвольные запросы v3. Сохраняйте временные метки, возвращённые идентификаторы и ответы с удалёнными конфиденциальными данными для обращения в поддержку.
Продолжите со справочником вашей учётной записи
Справочник после входа в систему отображает только те операции, которые доступны с учётом ваших разрешений и подключённых услуг. Используйте указанные в нём точный хост, тип учётных данных, поля запроса и схему ответа. Консоли могут выполнять реальные операции, включая покупки и отправку сообщений.