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

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

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

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

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

Базовый URL

text

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

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

text

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

Код

Значение

401

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

404

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

429

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

Эндпоинты

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

text

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

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

json

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

Поле

Тип

Описание

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. Проверка токена доступа

text

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

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

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

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

json

Ограничения (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-ключи и токены доступа подлежат хранению в секрете; при утечке ключ можно удалить и создать новый, а токен — пересоздать (старый перестаёт работать немедленно).