Входящие SMS

Возвращает список входящих SMS, полученных вашими устройствами, с поддержкой поиска по отправителю и постраничной навигацией.

Требование

Для работы эндпоинта необходимо, чтобы на устройстве была включена опция «Входящие SMS в панель» в его настройках.

Метод: GET
Эндпоинт: /api/ext/v1/sms/incoming
Требуемое разрешение: sms:incoming_read

Параметры запроса

Параметр	Тип	По умолчанию	Описание
page	integer	1	Номер страницы
per_page	integer	20	Записей на странице (максимум 100)
search	string	—	Поиск по отправителю: номер телефона или буквенный Sender ID (например Sberbank). Только точное совпадение.

Поиск работает по точному совпадению

Данные хранятся в зашифрованном виде. Поиск выполняется по HMAC-хешу отправителя — частичное совпадение не поддерживается. Указывайте номер точно, как он приходит от оператора (например +79001234567 или Sberbank).

Ответ — 200 OK

{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "device_id": "550e8400-e29b-41d4-a716-446655440000",
      "phone": "+79001234567",
      "message": "Ваш код подтверждения: 4521",
      "received_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "device_id": "550e8400-e29b-41d4-a716-446655440000",
      "phone": "Sberbank",
      "message": "Перевод 500 руб. Баланс: 12 500 руб.",
      "received_at": "2024-01-15T09:15:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}

Поля элемента

Поле	Тип	Описание
id	string (UUID)	Уникальный идентификатор входящего SMS
device_id	string (UUID) | null	Устройство, которое получило SMS. null — устройство удалено
phone	string	Номер или Sender ID отправителя
message	string	Текст сообщения
received_at	string (ISO 8601)	Время получения SMS (UTC)

Примеры

Получить последние входящие

curl "https://api.gosms.ru/api/ext/v1/sms/incoming" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"

Поиск по номеру отправителя

curl "https://api.gosms.ru/api/ext/v1/sms/incoming?search=%2B79001234567" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"

Поиск по буквенному Sender ID

curl "https://api.gosms.ru/api/ext/v1/sms/incoming?search=Sberbank" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"

Вторая страница, 50 записей

curl "https://api.gosms.ru/api/ext/v1/sms/incoming?page=2&per_page=50" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"

Python — мониторинг кодов подтверждения

import requests

API_KEY = "ВАШ_КЛЮЧ"
BASE_URL = "https://api.gosms.ru/api/ext/v1"

def get_incoming(search: str = "", page: int = 1, per_page: int = 20) -> dict:
    params = {"page": page, "per_page": per_page}
    if search:
        params["search"] = search

    response = requests.get(
        f"{BASE_URL}/sms/incoming",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params=params,
    )
    response.raise_for_status()
    return response.json()

# Получить все входящие от конкретного отправителя
data = get_incoming(search="+79001234567")
print(f"Найдено: {data['total']} сообщений")
for sms in data["items"]:
    print(f"[{sms['received_at']}] {sms['phone']}: {sms['message']}")

JavaScript — получить входящие с пагинацией

async function getIncomingSMS({ search = '', page = 1, perPage = 20 } = {}) {
  const params = new URLSearchParams({ page, per_page: perPage });
  if (search) params.set('search', search);

  const response = await fetch(
    `https://api.gosms.ru/api/ext/v1/sms/incoming?${params}`,
    { headers: { Authorization: 'Bearer ВАШ_КЛЮЧ' } }
  );

  if (!response.ok) throw new Error(`Ошибка: ${response.status}`);
  return response.json();
}

// Пример: входящие от Сбербанка
const result = await getIncomingSMS({ search: 'Sberbank' });
console.log(`Входящих от Sberbank: ${result.total}`);
result.items.forEach(sms => {
  console.log(`${sms.received_at}: ${sms.message}`);
});

Постраничная навигация

const hasNextPage = (page * per_page) < total;
const totalPages  = Math.ceil(total / per_page);

Возможные ошибки

Код	Описание
401	API-ключ не передан или недействителен
403	Ключ не имеет разрешения sms:incoming_read
400	Недопустимое значение параметра search (слишком длинный или содержит запрещённые символы)