Документация REST API
Выполните первый запрос к API MultiTEL
Начните с запроса только для чтения, разберите ответ, а затем выберите справочник для услуги, которую вы хотите создать.
Выбирайте 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.
Первый запрос: получение баланса
Этот запрос только читает данные: он не покупает услугу и не инициирует вызов или сообщение.
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
"https://api.multitel.net/v3/getbalance"API communications v3 возвращает результат работы приложения внутри тела JSON. Прежде чем читать response, проверьте HTTP-статус и status.code: у отклонённого запроса объекта response может не быть. Значения кодов могут быть строками или числами.
{
"status": {
"code": 200,
"msg": ""
},
"response": {
"balance": "25.0000",
"currency": "USD",
"terms": "Prepaid"
}
}Это вымышленный пример, а не баланс реального аккаунта. Денежные значения обрабатывайте как десятичные суммы. При диагностике отклонённого запроса сохраняйте сообщение, полученное от сервера, предварительно удалив из него учётные данные.
Правильно используйте данные о биллинге
Ответ с балансом содержит текущий баланс, валюту и условия оплаты. Он не показывает стоимость будущего вызова и не заменяет полный счёт. Для таких вопросов используйте соответствующие операции тарифов и использования. У уже подключённых номеров тарифные планы могут отличаться от нынешнего каталога.
Выберите следующую интеграцию
REST API поиска маршрутизации LRN
Узнавайте номер маршрутизации и доступную информацию об операторе для североамериканского телефонного номера по фиксированной цене.
Читать руководство по интеграции →REST API телефонных номеров
Находите доступные страны и номера, изучайте предложение целиком и управляйте принадлежащими вам номерами.
Читать руководство по интеграции →REST API для SMS и MMS
Отправляйте утверждённые сообщения приложений и обрабатывайте приём, события доставки, сегментацию и списание средств.
Читать руководство по интеграции →REST API экстренных вызовов
Зарегистрируйте номер и адрес обслуживания, отслеживайте статус активации и поддерживайте актуальность записи при изменении местоположения.
Читать руководство по интеграции →REST API учётной записи и биллинга
Получайте баланс и данные о начислениях, доступные вашей одобренной интеграции.
Читать руководство по интеграции →Поиск CNAM и информации о маршрутизации
Узнавайте имена вызывающих абонентов, разберитесь в уровнях поиска и используйте информацию о маршрутизации номеров.
Справочник CNAM REST →Облачная PBX
Начните с доступных тарифных планов услуги и арендатора (tenant), которого вы собираетесь настроить.
API тарифных планов облачной PBX →Обработка ошибок и повторных запросов
- Сбой аутентификации или прав доступа
- Проверьте, включены ли учётные данные API, разрешён ли нужный сервис и не мешает ли ограничение по исходному IP-адресу. Cookie сессии портала не является учётными данными для интеграции.
- Недостаточно средств или не выполнено требование об одобрении
- Прежде чем повторять операцию, устраните проблему с балансом аккаунта, разрешением на отправку или требованием о документах.
- Нет результата
- Пустой список номеров или отсутствие имени вызывающего абонента считайте обычным исходом. Не предполагайте, что для синтаксически корректного номера доступны все услуги.
- Тайм-аут сети или сбой сервиса
- Для операций чтения используйте ограниченное число повторов с задержкой (backoff). Перед повтором покупки, отправки или регистрации сначала проверьте состояние операции: повторение принятого запроса может привести к дублированию платного действия.
Поддержка идемпотентности зависит от семейства API. Emergency API поддерживает ключи повтора, но это не делает идемпотентными произвольные запросы v3. Сохраняйте временные метки, возвращённые идентификаторы и ответы с удалёнными конфиденциальными данными для обращения в поддержку.
Продолжите со справочником вашей учётной записи
Справочник после входа в систему отображает только те операции, которые доступны с учётом ваших разрешений и подключённых услуг. Используйте указанные в нём точный хост, тип учётных данных, поля запроса и схему ответа. Консоли могут выполнять реальные операции, включая покупки и отправку сообщений.