Docs/Разработчикам/API

REST API

Внешний read-only API v1 передаёт сохранённые SEO-данные внешним конвейерам. Расширение analysis:run безопасно обновляет только разрешённые источники, не запускает AI-функции и не изменяет клиентские сайты.

Текущий статус

production beta

Внешний контракт использует префикс /api/v1/external и схему ответа версии 1.0. Выпуск токенов доступен только администратору платформы. Refresh-расширение требует отдельного scope analysis:run.

Swagger / OpenAPI

живой

Все доступные сейчас эндпоинты задокументированы автоматически через декораторы NestJS. UI смотрите по адресу:

📘

Swagger UI

seasale.ru/api/docs — список модулей: auth, billing, projects, agents и др.

📄

OpenAPI JSON

seasale.ru/api/docs-json — машиночитаемая схема, можно скормить в Postman или Insomnia.

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

JWT

Защищённые эндпоинты ждут access-токен в заголовке Authorization: Bearer <jwt>. Токен выдаётся через POST /api/auth/login (email + пароль) или через Яндекс OAuth.

Для внешнего API используются отдельные токены ssx_..., а не JWT кабинета. Полный секрет показывается один раз, в базе хранится только криптографический хэш. Выпуск и отзыв доступны только администратору платформы в разделе Админ → Внешний API.

External SEO API v1

только чтение

API возвращает сохранённые данные Метрики, Вебмастера, семантики, технических аудитов, запусков и рекомендаций. Read-endpoints ничего не запускают. Отдельный refresh запускает только фиксированные read-only сборщики Метрики, Вебмастера, Wordstat и технического аудита.

Метрики и поиск

GET /summary
GET /search-performance
GET /keywords

Находки и результаты

GET /technical-findings
GET /recommendations
GET /runs/:runId

Безопасное обновление

POST /refresh
GET /refresh/:refreshId
202, UUID idempotencyKey, polling

Токен ограничивается организацией, явным списком проектов и scopes: projects:read, metrics:read, webmaster:read, keywords:read, recommendations:read, analysis:run. Максимальный период — 366 дней, лимит страницы — 500 записей, курсор непрозрачный.

Refresh принимает только metrika, webmaster, wordstat и technical_audit. Нельзя передать agentCode, URL, команду, промт или payload очереди. По умолчанию один source запускается раз в час, не более 10 refresh в сутки на проект. При ограничении API отвечает 429 и Retry-After.

Публичные эндпоинты

без авторизации

Несколько эндпоинтов специально доступны без токена — на них опираются лендинг и публичные страницы. Они стабильны и ими можно пользоваться:

🧾

GET /api/public/requisites

Юридические реквизиты ИП, цена тарифа Pro, флаг готовности приёма платежей. Email и телефон возвращаются в обфусцированном виде — расшифровка только в браузере по клику.

🎉

GET /api/public/promo

Активная промо-кампания на тариф Pro: basePriceRub, effectivePriceRub, promo.endsAtIso и время сервера. На него же опирается реальный расчёт суммы платежа в ЮKassa — цена в баннере и цена в чеке не разойдутся.

🔗

GET /api/public/referral/resolve?code=XXXXXXXX

Проверяет реферальный код. Возвращает имя пригласившего и размер бонусов — именно так страница регистрации показывает «Вас пригласил такой-то».

Позиции сайта

готовится к выпуску

Ручной съём позиций использует JWT кабинета и доступ пользователя к проекту. Внешние токены ssx_... не дают права запуска. Маршруты пока подготовлены локально и не включены в production.

Сначала GET /api/projects/:projectId/rank-tracking/options для разрешённых регионов Google, затем POST /api/projects/:projectId/rank-tracking/quote с количеством и массивом ключей для расчёта максимума страниц и оставшихся слотов Pro. Отдельный POST /api/projects/:projectId/rank-tracking/runs требует UUID idempotencyKey, manualApproval=true и точное совпадение approvedMaximumUnits с серверным расчётом. Запуск доступен только при действующей квоте и включённом вручную worker; автоматических проверок нет.

Историю и результат возвращают GET /api/projects/:projectId/rank-tracking/runs и GET /api/projects/:projectId/rank-tracking/runs/:runId. При неясном расходе запуск требует ручной сверки; сервис не повторяет платный запрос.

Что планируем

в порядке приоритета

Production beta

Перед выпуском refresh-расширения отдельно утвердить production-деплой, сделать свежий backup, применить миграцию и провести smoke-тест tenant/project-изоляции.

SDK

Тонкие клиенты для Node.js и Python поверх уже зафиксированного JSON-контракта v1.

Webhooks

Отдельная будущая версия для подписки на завершение аудита. В v1 внешних write-операций нет.

Для локальной проверки используйте Swagger, snapshot-клиент и безопасный пример examples/external-api-refresh.mjs. Он ждёт завершения и затем только читает данные.