Документация REST API

REST API учётной записи и биллинга

Получайте баланс и данные о начислениях, доступные вашей одобренной интеграции.

Открыть справочник для вашего аккаунта Разработчики и автоматизация

Выбирайте 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"
  }
}

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

Правильно используйте данные о биллинге

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

Соглашения Communications API Схемы биллинга для вашего аккаунта

Обработка ошибок и повторных запросов

Сбой аутентификации или прав доступа: Проверьте, включены ли учётные данные API, разрешён ли нужный сервис и не мешает ли ограничение по исходному IP-адресу. Cookie сессии портала не является учётными данными для интеграции.
Недостаточно средств или не выполнено требование об одобрении: Прежде чем повторять операцию, устраните проблему с балансом аккаунта, разрешением на отправку или требованием о документах.
Нет результата: Пустой список номеров или отсутствие имени вызывающего абонента считайте обычным исходом. Не предполагайте, что для синтаксически корректного номера доступны все услуги.
Тайм-аут сети или сбой сервиса: Для операций чтения используйте ограниченное число повторов с задержкой (backoff). Перед повтором покупки, отправки или регистрации сначала проверьте состояние операции: повторение принятого запроса может привести к дублированию платного действия.

Поддержка идемпотентности зависит от семейства API. Emergency API поддерживает ключи повтора, но это не делает идемпотентными произвольные запросы v3. Сохраняйте временные метки, возвращённые идентификаторы и ответы с удалёнными конфиденциальными данными для обращения в поддержку.

Продолжите со справочником вашей учётной записи

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

Каталог конечных точек для вашей учётной записи Консоль Communications REST Общедоступный документ OpenAPI для коммуникационных сервисов Руководство по интеграции OAuth