Список SMS

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

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

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

Параметр	Тип	По умолчанию	Описание
page	integer	1	Номер страницы
per_page	integer	20	Записей на странице
order	string	desc	Сортировка: desc (новые первые) или asc
status	string	—	Фильтр по статусу (pending, sent, delivered, undelivered, failed_send, failed_delivery)
search	string	—	Поиск по номеру телефона или тексту SMS
from	string	—	Дата начала периода в формате YYYY-MM-DD
to	string	—	Дата конца периода в формате YYYY-MM-DD

Ответ — 200 OK

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "device_id": "550e8400-e29b-41d4-a716-446655440000",
      "phone": "+79001234567",
      "message": "Ваш код: 1234",
      "status": "delivered",
      "sent_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:31:05Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "device_id": null,
      "phone": "+79007654321",
      "message": "Доброго дня!",
      "status": "pending",
      "sent_at": "2024-01-15T10:29:00Z",
      "updated_at": "2024-01-15T10:29:00Z"
    }
  ],
  "total": 145,
  "page": 1,
  "per_page": 20
}

Поле	Описание
items	Массив SMS на текущей странице
total	Общее количество SMS (с учётом фильтров)
page	Текущая страница
per_page	Количество записей на странице

Примеры

Получить первую страницу

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

Фильтр по статусу — только доставленные

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

Фильтр по периоду

curl "https://api.gosms.ru/api/ext/v1/sms?from=2024-01-01&to=2024-01-31&order=asc" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ"

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

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

Python — получить все SMS за месяц

import requests

def get_all_sms(from_date: str, to_date: str) -> list:
    """Получает все SMS за указанный период, обходя пагинацию."""
    all_items = []
    page = 1

    while True:
        response = requests.get(
            "https://api.gosms.ru/api/ext/v1/sms",
            headers={"Authorization": "Bearer ВАШ_КЛЮЧ"},
            params={
                "from": from_date,
                "to": to_date,
                "page": page,
                "per_page": 100,
                "order": "asc",
            },
        )
        response.raise_for_status()
        data = response.json()

        all_items.extend(data["items"])

        # Проверяем, есть ли ещё страницы
        if len(all_items) >= data["total"]:
            break
        page += 1

    return all_items

sms_list = get_all_sms("2024-01-01", "2024-01-31")
print(f"Всего SMS за январь: {len(sms_list)}")

# Статистика по статусам
from collections import Counter
stats = Counter(sms["status"] for sms in sms_list)
for status, count in stats.most_common():
    print(f"  {status}: {count}")

JavaScript — пагинация

async function getSMSPage(page = 1, perPage = 20, filters = {}) {
  const params = new URLSearchParams({
    page,
    per_page: perPage,
    ...filters,
  });

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

  if (!response.ok) throw new Error('Ошибка загрузки');
  return response.json();
}

// Получить недоставленные за последнюю неделю
const result = await getSMSPage(1, 50, {
  status: 'undelivered',
  from: '2024-01-08',
  to: '2024-01-15',
});

console.log(`Недоставлено: ${result.total}`);
result.items.forEach(sms => {
  console.log(`  ${sms.phone}: ${sms.message.slice(0, 30)}...`);
});

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

Чтобы определить, есть ли следующая страница:

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