Как отправлять SMS через HTTP API: Подробное руководство для разработчиков

Отправка SMS-сообщений через HTTP API — один из самых доступных и надёжных способов интеграции текстовых уведомлений в веб-сервисы, мобильные приложения, CRM и ERP-системы. Это решение позволяет автоматизировать отправку одноразовых паролей (OTP), статусов заказов, напоминаний о записи и маркетинговых рассылок.

Ниже подробно рассмотрено, как отправлять SMS через HTTP API, из каких этапов состоит и с какими нюансами сталкиваются разработчики.

---

Как работает отправка SMS через HTTP API

Архитектура взаимодействия проста: ваше приложение выступает в роли клиента, а шлюз провайдера рассылок — в роли сервера.

1. Ваш сервер формирует HTTP-запрос (обычно POST или GET) с данными: номером получателя, текстом и ключом авторизации.
2. HTTP API шлюза принимает запрос, валидирует ключи и баланс счета.
3. Шлюз конвертирует веб-запрос в протокол сотовой связи (например, SMPP) и передаёт сообщение сотовому оператору.
4. Оператор доставляет SMS на устройство пользователя и возвращает статус обратно.

---

Что нужно для старта

Перед написанием кода необходимо выполнить базовую подготовку:

• Выбрать SMS-провайдера: Среди международных популярны Twilio, Vonage (Nexmo), Infobip, среди локальных — SMS.ru, SMS-Aero, SMSC, GreenSMS и др.
• Зарегистрировать аккаунт и получить API Key / Token: Ключ аутентификации необходим для безопасного доступа к API.
• Зарегистрировать имя отправителя (Sender ID): Буквенная подпись (например, MY_BRAND), которая отображается у пользователя вместо номера. В большинстве стран требует предмодерации у операторов связи.

---

Пошаговый процесс интеграции

1. Формирование параметров запроса

   Сформируйте обязательные поля. Как правило, REST API SMS-провайдеров ожидают следующие параметры:

   • to / phone — номер получателя в международном формате E.164 (например, +79991234567).
   • text / message — текст сообщения (учитывайте ограничение в 160 символов для латиницы и 70 для кириллицы).
   • from / sender — зарегистрированное имя отправителя.
2. Авторизация

   Авторизация в HTTP API реализуется одним из способов:

   • Bearer Token в заголовке Authorization: Authorization: Bearer YOUR_API_KEY
   • Basic Auth: Логин и пароль/токен в base64.
   • Query-параметры: Передача ключа прямо в URL (?api_key=SECRET_TOKEN), что менее безопасно, но встречается в простых GET-запросах.
3. Отправка запроса

   Выполните HTTP-запрос к конечной точке (endpoint) провайдера. В современной веб-разработке стандартом является POST-запрос с телом в формате JSON.

4. Обработка ответа

   Сервер вернёт HTTP-код 200 OK или 201 Created при успешном приеме сообщения, а также JSON-ответ с идентификатором сообщения (message_id / sms_id).

---

Пример кода на cURL и Python

Пример 1: cURL (запрос из командной строки)

curl -X POST "https://api.smsprovider.com/v1/sms/send"   -H "Authorization: Bearer YOUR_API_TOKEN"   -H "Content-Type: application/json"   -d '{
    "to": "+799999999",
    "from": "MyCompany",
    "text": "Ваш код подтверждения: 4821"
  }'

Пример 2: Python (библиотека requests)

import requests

url = "https://api.smsprovider.com/v1/sms/send"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "to": "+79991234567",
    "from": "MyCompany",
    "text": "Ваш код подтверждения: 4821"
}

response = requests.post(url, json=payload, headers=headers)

if response.status_code == 200:
    data = response.json()
    print(f"SMS отправлено! ID сообщения: {data.get('message_id')}")
else:
    print(f"Ошибка {response.status_code}: {response.text}")

---

Приём статусов доставки (Webhooks / DLR)

Отправка HTTP-запроса подтверждает лишь то, что шлюз принял сообщение в обработку. Чтобы узнать, дошло ли SMS до телефона, используется механизм Delivery Reports (DLR) через Webhooks:

1. В кабинете провайдера указывается URL вашего сервера (например, https://your-domain.com/api/sms-status).
2. Когда оператор связывается со шлюзом, шлюз отправляет POST-запрос на ваш Webhook.
3. В запросе передаются message_id и статус: DELIVERED (доставлено), UNDELIVERED (не доставлено), EXPIRED (истёк срок жизни).

---

Подводные камни и лучшие практики

• Длина сообщений и кодировка: Одно стандартное SMS содержит до 160 латинских символов или до 70 символов кириллицы (Unicode). При превышении этого лимита сообщение разбивается на части (по 153 и 67 символов соответственно) и тарифицируется как несколько SMS.
• Резервирование и отказоустойчивость: Если сервис отправляет критически важные данные (OTP), настройте каскадную отправку: если SMS не доставляется за 30 секунд — отправляется Push-уведомление или сообщение в мессенджер (Telegram/WhatsApp).
• Безопасность (Rate Limiting): Для эндпоинтов авторизации обязательно защищайте формы отправки капчей (reCAPTCHA) и ограничением по IP/номеру, чтобы злоумышленники не выжгли ваш баланс с помощью «SMS-бомбинга».