API, ключи и вебхуки: как приложение узнаёт о подписке
Интеграция строится на двух вещах: ваше приложение спрашивает, что доступно клиенту, а система сообщает, когда это меняется. Больше обычно ничего не нужно.
Ключи
Раздел Интеграции → API-ключи. API-ключ — это пароль для программы, а не для человека. При создании задаются название, права (scopes) и лимит запросов в минуту.
Секрет показывается один раз — скопируйте и нажмите «Я сохранил ключ». В системе хранится только хэш, восстановить ключ нельзя. Кнопка «Отозвать» отключает ключ немедленно и не задевает остальные.
| Право | Что открывает |
|---|---|
entitlements:read | Права доступа подписчика |
subscriptions:read | Статус подписки |
subscribers:read | Список клиентов без персональных данных |
events:write | Отправка продуктовых событий (питает PQL и здоровье) |
Новый ключ по умолчанию без прав — выберите нужные явно. Выдать ключу право, которого нет у вашей роли, нельзя.
Проверка доступа
Главный запрос: «что доступно этому клиенту». В ответ приходит список прав и признак isActive по каждому ключу права. Проверяйте доступ именно по праву, а не по источнику оплаты — тогда покупка на сайте и покупка в App Store работают одинаково.
Authorization: Bearer sk_…
GET /api/saas/public/v1/subscribers/{id}/entitlementsОтвет содержит поля в контракте, привычном по сложившейся практике: willRenew, periodType, store, expirationDate, льготный период и признак обнаруженной проблемы с оплатой.
Полное руководство разработчика — в кабинете: Интеграции → Документация. Там перечислены все методы, права ключей, коды ошибок и примеры запросов. Открыто сотрудникам вашей организации, отдельная регистрация не нужна.
Правила хорошей интеграции
- Версия. Мажорная версия в пути (
/v1/), точная дата контракта — заголовкомSaas-Version. Незнакомые поля в ответе нужно игнорировать: их добавление не считается ломающим изменением. - Лимиты. На каждом ответе приходят заголовки с остатком лимита; при превышении — код 429 и заголовок
Retry-After. - Ошибки. В едином формате с полем
request_id— указывайте его при обращении в поддержку. Любая проблема с ключом даёт одинаковый ответ 401, без подсказок. - Повторы. У каждого продуктового события обязателен
dedupeKey— тогда сетевой повтор не задвоит балл.
Исходящие вебхуки
Вебхук — это автоматическое уведомление в обратную сторону: как только у вас что-то произошло (подписка создана, продлена, отменена, счёт оплачен), система стучится на ваш адрес.
В разделе Интеграции → Вебхуки добавляется эндпоинт: URL приёмника, список событий (приходят только выбранные) и секрет подписи. Есть тест-отправка, обновление секрета, журнал доставок с кодами ответа и кнопка «Добрать ретраи» для ручного повтора неудачных.
Проверяйте подпись до обработки тела и отвечайте быстро — тяжёлую работу выносите в очередь.
Приём
Вкладка «Приём» — журнал входящих уведомлений от платёжных систем и магазинов: провайдер, тип события, результат нормализации и статус (принят, обработан, ошибка, дубликат). Подпись проверяется, дубли отсеиваются.