Черновой REST API

Base path: /api/v1. Это функциональная карта, не утверждённый OpenAPI contract. Все write endpoints принимают idempotency key там, где повтор может создать расчёт, списание, генерацию или уведомление.

Onboarding и auth

Метод	Endpoint	Назначение
POST	/onboarding/drafts	сохранить данные рождения/attribution и запустить бесплатные расчёты
GET	/onboarding/drafts/:token	статус расчётов без раскрытия чужих данных
POST	/auth/otp/request	создать challenge и отправить шестизначный код через Resend
POST	/auth/otp/verify	проверить код, создать пользователя при первом входе и забрать draft
POST	/auth/refresh	ротировать refresh session
POST	/auth/logout	отозвать текущую session

В MVP используется passwordless e-mail OTP через Resend: TTL кода — 10 минут, повторная отправка — не чаще раза в 60 секунд, не более пяти попыток проверки на challenge. Ответы request не раскрывают наличие пользователя. Лимиты по адресу, IP и устройству задаются конфигурацией. Паролей и Telegram-аутентификации в MVP нет.

Профиль, места и расчёты

Метод	Endpoint	Назначение
GET/PATCH	/me	профиль и настройки
GET/POST	/me/birth-profiles	история/новая версия входных данных
POST	/places/resolve	строка → варианты места, координаты, IANA timezone
POST	/calculation-sets	запустить/получить idempotent набор расчётов
GET	/calculation-sets/:id	aggregate status
GET	/calculation-sets/:id/artifacts/:system	доступный raw/free результат
GET	/me/natal-chart	projection для визуализации активной карты

Backend отдаёт координаты и связи для wheel chart; картинку не рендерит в MVP.

Paywall, AI и прогнозы

Метод	Endpoint	Назначение
GET	/products	активные тарифы/цены; контракт поддерживает список, в MVP активен один
GET	/me/entitlements	доступные возможности
POST	/interpretations	idempotent запрос платного core reading/route
GET	/interpretations/:id	queued/running/ready/failed и опубликованный JSON
GET	/me/route	текущая projection маршрута
POST	/forecasts	запрос периода по правилам entitlement
GET	/forecasts/:id	статус/результат
GET	/me/forecasts?period=...	история прогнозов

Если доступа нет, сервер возвращает стабильный ENTITLEMENT_REQUIRED и product reference, а не часть скрытого текста.

Billing

Метод	Endpoint	Назначение
POST	/orders	создать order из server-side price
POST	/orders/:id/payment-attempts	создать YooKassa confirmation
GET	/orders/:id	актуальный статус после redirect
GET	/me/subscription	период/status/renewal
POST	/me/subscription/cancel	cancel at period end
POST	/me/subscription/payment-method/change	новый provider flow
POST	/refund-requests	запрос клиента, не мгновенный безусловный refund
POST	/webhooks/yookassa	provider callback

Сумма и feature entitlement никогда не принимаются от клиента как доверенные значения.

Goals

Метод	Endpoint	Назначение
GET/POST	/goals	список/создание цели или запроса
GET/PATCH	/goals/:id	чтение/допустимый transition
POST	/goals/:id/check-ins	результат achieved/partial/not_achieved/... и заметка
GET	/goals/statistics	пользовательская агрегированная статистика

Практики и консультации

Метод	Endpoint	Назначение
GET	/practitioners	одобренный каталог и фильтры
GET	/practitioners/:id	карточка, кейсы и доступные услуги
POST	/consultations	заявка клиента
GET	/consultations/:id	статус/детали для участника
POST	/consultations/:id/transitions	accept/schedule/cancel/complete по роли и state machine
POST	/consultations/:id/order	отдельный order консультации
GET	/me/consultations	история клиента/практика

Клиент и практик согласуют время через поля заявки и допустимые переходы статуса. Календарь, чат и видеокомнаты в MVP отсутствуют.

Уведомления, аналитика и privacy

Метод	Endpoint	Назначение
GET/PATCH	/me/notification-preferences	темы e-mail-уведомлений
POST	/analytics/events	allowlisted client events; server events создаются внутри use cases
POST	/me/data-export	асинхронный экспорт доступных данных
POST	/me/deletion-request	workflow удаления/анонимизации

Административных endpoints в MVP нет. Будущий отдельный модуль описан только как post-MVP backlog в документе об админ-панели. Перед реализацией endpoints оформляются как OpenAPI с примерами, auth scopes, error codes, pagination и state transitions.