Framework
Docs

04 — API e Integrações

Service API

AmbienteBase URL
Localhttp://localhost:3002
Produçãohttps://service.framework.forestbit.io
  • Swagger (dev): /docs
  • Health: /health

Módulos de plataforma (boilerplate)

Inventário de negócio (status, descrição, specs): product/04-features-modules.md.

MóduloPrefixo / pathSpec
Auth/auth/*002-auth-module
Companies/companies/*004-multi-tenant
Invites/companies/invites/*004-multi-tenant
Members/companies/members/*004-multi-tenant
Subscriptions/subscriptions/*003-billing-subscriptions
Webhooks/webhooks/stripe003-billing-subscriptions
Storage/storage/*006-storage
User/user/*002-auth-module

Detalhes de endpoints: Swagger em dev ou implementation-status.md de cada spec.

Hasura GraphQL

AmbienteURL
Localhttp://localhost:8080
Produçãohttps://api.framework.forestbit.io
  • Permissões por role (user, anonymous, admin secret)
  • Migrations: apps/hasura/migrations/
  • Metadata: apps/hasura/metadata/
  • JWT: claims https://hasura.io/jwt/claims emitidas pelo auth module (ver spec 001)

Contratos app ↔ service

Autenticação (JWT)

AspectoContrato
Login / registerPOST /auth/login, /auth/register → { token, refresh_token, user }
RefreshPOST /auth/refresh-token com refresh token
Requests autenticadosHeader Authorization: Bearer <access_token>
HasuraMesmo JWT; Apollo client envia Bearer
LogoutPOST /auth/logout + clear local storage no client

Fluxo completo: specs/002-auth-module.

Formato de erro

Respostas de erro seguem padrão NestJS + interceptors (ErrorLoggingInterceptor). Códigos auth: AUTH_001–AUTH_006.

Versionamento

Sem version prefix na URL v1 — breaking changes exigem coordenação app + service.

Integrações externas — plataforma

IntegraçãoUsoMóduloSecrets
StripeBillingsubscriptionsSTRIPE_*
DigitalOcean SpacesFile storagestorageDO_SPACES_* / S3-compatible
SMTP / emailAuth emailsauthmail env vars

Integrações — produto (preencher no fork)

Documente aqui integrações específicas do seu produto — não entram no checklist do PLAYBOOK. Remova linhas que não usar.

IntegraçãoUso típicoMódulo serviceSecrets
Google PageSpeed InsightsMétricas de performanceTBDPAGESPEED_API_KEY, PAGESPEED_API_ENDPOINT
ApifyWeb scrapingTBDAPIFY_API_TOKEN
Google AI (runtime no service)IA em backendTBDGOOGLE_AI_API_KEY
TBD

Webhooks

EventoEndpointIdempotência
Stripe (checkout.session.completed, customer.subscription.*, …)POST /webhooks/stripeTabela webhook events (spec 002)

Rate limits e quotas

Links relacionados