Публичный API блогов Гапи

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

Базовые понятия

  • API-ключ блога — ключ, который владелец блога создаёт в меню блога («API ключи»). До 10 ключей на блог. Полный ключ показывается один раз при создании; храните его в секрете.

  • Токен доступа подписчика — персональный токен, который подписчик генерирует сам в разделе «Подписки» (меню карточки подписки → «Токен доступа»). Подписчик передаёт этот токен вашему сервису (например, отправляет боту), а сервис проверяет его через API.

Базовый URL

https://gapi.ru/blogs_api

Аутентификация

Каждый запрос должен содержать заголовок с API-ключом блога:

Authorization: Bearer <API_КЛЮЧ_БЛОГА>

Коды ошибок аутентификации:

Код

Значение

401

Ключ отсутствует, недействителен, удалён или принадлежит другому блогу

404

Блог или токен не найдены

429

Превышен лимит запросов (см. «Ограничения»)

Эндпоинты

1. Список подписок блога

GET /blogs_api/blogs/{адрес_блога}/subscriptions?page={номер}

Постраничный список подписок блога (20 записей на страницу, от новых к старым).

Пример ответа:

{
  "data": [
    {
      "id": "123",
      "type": "subscription",
      "attributes": {
        "accessToken": "aBcD…32-символьный-токен…",
        "subscriptionLevel": { "name": "Гражданин", "price": "300.0" },
        "expiresAt": "2026-09-13T12:00:00.000Z",
        "createdAt": "2026-08-13T12:00:00.000Z"
      }
    }
  ],
  "meta": { "count": 137, "page": 1, "pages": 7, "per": 20 }
}

Поля подписки:

Поле

Тип

Описание

accessToken

string | null

Токен доступа подписчика (null, если подписчик его не создавал)

subscriptionLevel

object | null

Уровень подписки { name, price }; null — бесплатная подписка

expiresAt

string | null

Дата истечения (ISO 8601); null — бессрочная

createdAt

string

Дата оформления (ISO 8601)

Важно для разработчиков: поле price внутри subscriptionLevel — это строка (например, "300.0"), а не число. При сравнении уровней приводите его к числу явно. Более высокий уровень доступа всегда имеет большую цену.

2. Проверка токена доступа

GET /blogs_api/blogs/{адрес_блога}/subscriptions/{токен_доступа}

Основной метод интеграции — проверка конкретного токена, предъявленного пользователем вашему сервису.

  • Токен найден → 200 OK с объектом подписки. Действительность подписки определяется по объекту subscriptionLevel: null означает, что у пользователя нет платной подписки — это не ошибка.

  • Токен не найден → 404 Not Found.

Пример ответа:

{
  "data": {
    "id": "123",
    "type": "subscription",
    "attributes": {
      "accessToken": "aBcD…32-символьный-токен…",
      "subscriptionLevel": { "name": "Гражданин", "price": "300.0" },
      "expiresAt": "2026-09-13T12:00:00.000Z",
      "createdAt": "2026-08-13T12:00:00.000Z"
    }
  }
}

Ограничения (rate limit)

По умолчанию на каждый API-ключ действуют лимиты: 100 запросов в секунду и 1000 запросов в минуту. При превышении возвращается 429 Too Many Requests. Лимиты можно изменить через администраторов платформы.

Алгоритм интеграции

  1. Владелец блога создаёт API-ключ (меню блога → «API ключи») и сохраняет его в настройках своего сервиса.

  2. Подписчик генерирует токен доступа («Подписки» → меню подписки → «Токен доступа») и передаёт его вашему сервису (например, через команду бота или форму на сайте).

  3. Сервис вызывает GET /blogs_api/blogs/{адрес_блога}/subscriptions/{токен} с заголовком Authorization: Bearer <ключ>.

  4. Решение о доступе принимается по ответу:

    • 404 — токен недействителен: доступ не предоставлять;

    • 200 с непустым subscriptionLevel — платная подписка: доступ предоставлять (при необходимости уровень проверяется сопоставлением по name или сравнением price — более высокий уровень доступа всегда имеет большую цену);

    • 200 с subscriptionLevel: null — бесплатная подписка: доступ не предоставлять.

  5. Рекомендуется периодически перепроверять выданные доступы (подписка может истечь или быть отменена) — например, при каждом входе пользователя или по расписанию с учётом лимитов.

Конфиденциальность

Ответы API не содержат персональных данных подписчиков (имён, email, идентификаторов пользователей). Связь пользователя с подпиской возможна только через токен доступа, который пользователь передаёт сам. API-ключи и токены доступа подлежат хранению в секрете; при утечке ключ можно удалить и создать новый, а токен — пересоздать (старый перестаёт работать немедленно).