Как встроить отправку SMS в свой проект через REST API

Токен получается запросом POST /v1/auth/login с телом {"email": ..., "password": ...}. Обёртка ниже хранит токен в памяти, а на ответ 401 получает новый и повторяет отправку ровно один раз. Больше одного повтора не нужно: если и второй раз 401, дело не в сроке жизни токена.

Python

import threading
import requests

API = "https://api.textbee.ru"


class TextBee:
    """Отправка SMS с автоматическим обновлением токена."""

    def __init__(self, email, password, timeout=15):
        self._email = email
        self._password = password
        self._timeout = timeout
        self._token = None
        self._lock = threading.Lock()

    def _login(self):
        r = requests.post(
            f"{API}/v1/auth/login",
            json={"email": self._email, "password": self._password},
            timeout=self._timeout,
        )
        r.raise_for_status()
        data = r.json()
        # имя поля зависит от версии API, берём первое непустое
        token = (data.get("token")
                 or data.get("accessToken")
                 or data.get("access_token"))
        if not token:
            raise RuntimeError(f"в ответе логина нет токена: {list(data)}")
        return token

    def _get_token(self, force=False):
        with self._lock:
            if force or not self._token:
                self._token = self._login()
            return self._token

    def send(self, phone_number, text):
        for attempt in (1, 2):
            token = self._get_token(force=(attempt == 2))
            r = requests.post(
                f"{API}/v1/sms/send",
                headers={"Authorization": f"Bearer {token}"},
                json={"phoneNumber": phone_number, "text": text},
                timeout=self._timeout,
            )
            if r.status_code == 401 and attempt == 1:
                continue          # токен протух, обновим и попробуем ещё раз
            r.raise_for_status()
            return r.json()


client = TextBee("you@example.com", "пароль")
print(client.send("+79161234567", "Ваш код: 12345"))

Node.js

const API = "https://api.textbee.ru";

class TextBee {
  constructor(email, password, timeoutMs = 15000) {
    this.email = email;
    this.password = password;
    this.timeoutMs = timeoutMs;
    this.token = null;
    this.pending = null;          // чтобы параллельные вызовы не логинились хором
  }

  async login() {
    if (this.pending) return this.pending;
    this.pending = (async () => {
      const res = await fetch(`${API}/v1/auth/login`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ email: this.email, password: this.password }),
        signal: AbortSignal.timeout(this.timeoutMs),
      });
      if (!res.ok) throw new Error(`login: ${res.status}`);
      const data = await res.json();
      const token =
        data.token ?? data.accessToken ?? data.access_token;
      if (!token) throw new Error("в ответе логина нет токена");
      this.token = token;
      return token;
    })().finally(() => { this.pending = null; });
    return this.pending;
  }

  async send(phoneNumber, text) {
    for (const attempt of [1, 2]) {
      const token = (attempt === 2 || !this.token)
        ? await this.login()
        : this.token;
      const res = await fetch(`${API}/v1/sms/send`, {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${token}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ phoneNumber, text }),
        signal: AbortSignal.timeout(this.timeoutMs),
      });
      if (res.status === 401 && attempt === 1) continue;
      if (!res.ok) throw new Error(`sms/send: ${res.status}`);
      return res.json();
    }
  }
}

Блокировка в Python и pending в Node нужны для одного и того же: когда токен протух, запросов на отправку обычно идёт несколько сразу, и без этого все они пойдут логиниться одновременно.

Ключевая мысль в том, когда писать в базу. Отметку ставим до отправки, а не после: пропущенная SMS лечится повтором вручную, а две одинаковые с разными кодами уже не лечатся никак.

SQL

CREATE TABLE sms_outbox (
    event_key   TEXT PRIMARY KEY,          -- order:1234:paid, login:99:otp
    status      TEXT NOT NULL,             -- pending | sent | failed
    message_id  TEXT,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at  TIMESTAMPTZ
);

Python

def send_once(conn, client, event_key, phone_number, text):
    """Отправляет SMS не более одного раза на event_key."""
    with conn:
        cur = conn.execute(
            "INSERT INTO sms_outbox (event_key, status) "
            "VALUES (%s, 'pending') "
            "ON CONFLICT (event_key) DO NOTHING RETURNING event_key",
            (event_key,),
        )
        if cur.fetchone() is None:
            return None                    # уже отправляли или отправляем

    try:
        result = client.send(phone_number, text)
    except Exception:
        # ВАЖНО: на таймауте статус НЕ трогаем и запись НЕ удаляем.
        # Запрос мог дойти, и повтор отправит второе сообщение.
        # Такие записи разбираем отдельно, сверяя статус по message_id.
        raise

    with conn:
        conn.execute(
            "UPDATE sms_outbox SET status='sent', message_id=%s, "
            "updated_at=now() "
            "WHERE event_key=%s",
            (result.get("id"), event_key),
        )
    return result

ON CONFLICT DO NOTHING делает проверку и вставку одной операцией. Если разнести их на «сначала SELECT, потом INSERT», два параллельных обработчика успеют проскочить оба, и вы получите ровно тот дубль, от которого защищались.

Ответ на отправку даёт идентификатор, по нему статус спрашивается через GET /v1/messages/{id}. Опрашивать имеет смысл с паузой и с потолком по времени: если за пару минут статус не стал конечным, дело не в скорости, а в телефоне или сети.

Python

import time

TERMINAL = {"delivered", "failed", "undelivered", "expired"}


def wait_delivery(client, message_id, timeout=180, interval=5):
    """Ждёт конечного статуса. Возвращает статус или None, если не дождались."""
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        token = client._get_token()
        r = requests.get(
            f"{API}/v1/messages/{message_id}",
            headers={"Authorization": f"Bearer {token}"},
            timeout=15,
        )
        r.raise_for_status()
        status = r.json().get("status")
        if status in TERMINAL:
            return status
        time.sleep(interval)
    return None                    # не дождались, но сообщение могло уйти позже

Набор конечных статусов сверьте с тем, что реально приходит в вашем аккаунте: список выше покрывает обычные случаи, но полагаться на него вслепую не стоит. Всё, чего нет в наборе, код считает промежуточным и продолжает ждать, а это безопаснее обратного.

И не блокируйте на этом пользовательский запрос. Ожидание доставки это фоновая задача: в момент нажатия кнопки честный ответ звучит как «код отправлен», а не «код доставлен».

Здесь есть тонкость, из-за которой наивный повтор опаснее отказа. На 429 сообщение точно не принято, повторять безопасно. На 5xx и на таймауте оно могло быть принято, и повтор рискует дублем. Поэтому повторяем автоматически только первое, а остальное отдаём защите по ключу события из решения выше.

Python

import random
import time

import requests


def send_with_retry(client, phone_number, text, attempts=4):
    delay = 1.0
    last = None
    for i in range(attempts):
        try:
            return client.send(phone_number, text)
        except requests.HTTPError as e:
            code = e.response.status_code
            last = e
            if code == 429:
                # уважаем Retry-After, если сервер его прислал
                wait = float(e.response.headers.get("Retry-After", delay))
            elif 500 <= code < 600:
                raise                      # могло быть принято, повтор опасен
            else:
                raise                      # 4xx: повторять бессмысленно
            time.sleep(wait + random.uniform(0, 0.3))   # джиттер против пачки
            delay = min(delay * 2, 60)
    raise last


# в цикле по списку получателей отправку писать не надо:
# см. раздел про рассылки ниже

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