Документация REST API
REST API для SMS и MMS
Отправляйте утверждённые сообщения приложений и обрабатывайте приём, события доставки, сегментацию и списание средств.
Выбирайте 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.
Подготовка запроса на отправку SMS
Используйте одобренный номер отправителя с поддержкой SMS, принадлежащий аккаунту, получателя, давшего согласие на сообщение, и необходимую регистрацию Brand/Campaign либо проверку номера с бесплатными вызовами для звонящего. Пример ниже отправляет реальное сообщение, если подставить рабочие учётные данные и номера; это не песочница.
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
--request POST \
--header "Content-Type: application/json" \
--data '{"from":"YOUR_APPROVED_NUMBER","to":"YOUR_CONSENTED_RECIPIENT","text":"Your requested update is ready."}' \
"https://api.multitel.net/v3/sendsms"Замените заполнители отправителя и получателя телефонными номерами в международном формате: только цифры, включая код страны. Для MMS укажите в media поддерживаемый, общедоступный для загрузки URL медиафайла и заранее проверьте возможность отправки MMS и стоимость.
Принятие запроса не означает доставку
Проверяйте и внешний статус приложения, и возвращённый результат отправки сообщения. Сохраняйте идентификатор сообщения, выданный сервисом, и отслеживайте статус доставки и события webhook. Успешная отправка запроса не доказывает, что устройство получателя получило сообщение.
SMS тарифицируются по сегментам. Кодировка и длина сообщения могут давать несколько сегментов; медиафайлы и сборы, связанные с операторами, могут отличаться от тарифов на SMS. Перед отправкой уточните актуальную цену продажи для вашего аккаунта. Никогда не повторяйте вслепую отправку, завершившуюся тайм-аутом: сначала проверьте записанный результат.
Обработка ошибок и повторных запросов
- Сбой аутентификации или прав доступа
- Проверьте, включены ли учётные данные API, разрешён ли нужный сервис и не мешает ли ограничение по исходному IP-адресу. Cookie сессии портала не является учётными данными для интеграции.
- Недостаточно средств или не выполнено требование об одобрении
- Прежде чем повторять операцию, устраните проблему с балансом аккаунта, разрешением на отправку или требованием о документах.
- Нет результата
- Пустой список номеров или отсутствие имени вызывающего абонента считайте обычным исходом. Не предполагайте, что для синтаксически корректного номера доступны все услуги.
- Тайм-аут сети или сбой сервиса
- Для операций чтения используйте ограниченное число повторов с задержкой (backoff). Перед повтором покупки, отправки или регистрации сначала проверьте состояние операции: повторение принятого запроса может привести к дублированию платного действия.
Поддержка идемпотентности зависит от семейства API. Emergency API поддерживает ключи повтора, но это не делает идемпотентными произвольные запросы v3. Сохраняйте временные метки, возвращённые идентификаторы и ответы с удалёнными конфиденциальными данными для обращения в поддержку.
Продолжите со справочником вашей учётной записи
Справочник после входа в систему отображает только те операции, которые доступны с учётом ваших разрешений и подключённых услуг. Используйте указанные в нём точный хост, тип учётных данных, поля запроса и схему ответа. Консоли могут выполнять реальные операции, включая покупки и отправку сообщений.