Visão geral do domínio

Esta seção explica como construir sobre a API da Superdinda. A referência rota a rota fica em API Reference. Aqui ficam os conceitos e os fluxos que amarram essas rotas.

As peçasCopy Anchor Link

Como se ligamCopy Anchor Link

conta (owner, guardians)
 └─ vaga (pending → active ⇄ paused, archived)
     ├─ pessoa protegida (kind: minor | adult)
     ├─ pedido de consentimento (pending → given | declined | expired | revoked)
     │    └─ checagem de vínculo (confirmed | refuted | inconclusive | failed)
     ├─ canal contratado (seat_channels: whatsapp)
     │    └─ pareamento (starting → challenge → connecting → paired ⇄ degraded …)
     └─ análise → achados → alerta (open | resolved | dismissed)
                                  └─ notificação pros responsáveis
tudo isso → events (ULID) → stream Redis → SSE

Algumas regras que atravessam tudo:

• Só refuted bloqueia. Uma checagem de vínculo inconclusive vai pra revisão manual e não impede o pareamento (AD-009).
• Consentimento antes do cartão. Toda vaga criada desde a migração do onboarding v2 tem activationRequiresConsent: true: o link sai antes da ativação, e POST /seats/{uid}/activate responde 422 CONSENT_REQUIRED até o "sim" (AD-019, D2).
• Pareamento exige vaga ativa, consentimento dado e vínculo não refutado. GET /seats/{uid}/consent diz se pode (pairingAllowed) e o que falta (blockedBy).
• O número conectado precisa ser o da pessoa. Se o provedor confirmar outro telefone, o pareamento é desfeito (pairing.identity_mismatch).
• O teste grátis começa na primeira conexão, não na ativação (AD-019, D1). O evento trial.started avisa.
• Responsável não lê conversa. Quando a análise vê risco, ele recebe um alerta com o trecho mínimo. Push, e-mail e SSE nunca carregam trecho (regra P1 do api-map.md).

Estado da proteçãoCopy Anchor Link

Toda tela que diz "como está a proteção de alguém" lê a mesma derivação (deriveProtectionState), em vez de juntar status de vaga, consentimento e pareamento na mão. Nada disso é guardado: é recalculado a cada leitura.

Junto vêm reason (vocabulário fechado, por exemplo consent_stopped_by_dependent, identity_mismatch, paused_by_guardian; nunca um motivo que a pessoa deu), since e action (o próximo passo sugerido, como send_consent, connect ou resume_pause). O texto fica no front.

• GET /accounts/{uid}/home: a tela Início numa leitura só (estado de cada pessoa, a semana com dias protegidos e quedas, o aquecimento e o bloco de alertas).
• GET /seats/{uid}/protection: uma pessoa, com o mesmo cartão e mais consentimento, conexão, pausa, quem recebe os avisos e a semana.
• Quando a derivação muda, sai seat.state_changed no SSE. O começo e o fim da primeira leitura saem como analysis.warmup.

Papéis e portas de entradaCopy Anchor Link

Uma vaga de outra família responde 404, nunca 403: a existência dela não é da conta de quem pergunta (backend/src/http/middleware/seat.ts).

Guias desta seçãoCopy Anchor Link

Usando a referência da APICopy Anchor Link

A API Reference é gerada do openapi.json que o backend exporta (bun run openapi:export). Cada rota tem um playground.

• Servidores. O padrão é http://localhost:3000 (backend com bun run dev), e https://api.superdinda.com (produção) também aparece na lista. Se a variável DOCS_API_URL estiver definida no app de docs, esse servidor entra em primeiro lugar (por exemplo, um host de homologação).
• Proxy. O playground não chama a API direto do navegador: passa por /api/proxy do próprio docs, que só encaminha para os servidores dessa lista e recusa qualquer outro destino.
• Token. As rotas protegidas declaram o esquema Bearer. Pegue um accessToken (veja Autenticação) e cole no campo de autorização do playground. O token vale JWT_ACCESS_TTL_SECONDS (padrão 900 s). Quando vencer, peça outro.

curl -s -X POST http://localhost:3000/auth/otp/request \
  -H 'content-type: application/json' \
  -d '{"email":"voce@exemplo.com","delivery":"code"}'
# Em dev o código sai no terminal do backend (MAIL_TRANSPORT=log).
curl -s -X POST http://localhost:3000/auth/otp/verify \
  -H 'content-type: application/json' \
  -d '{"email":"voce@exemplo.com","code":"123456"}'
# → { "success": true, "data": { "accessToken": "<access-jwt>", "expiresAtMs": "…" } }

FontesCopy Anchor Link

• backend/README.md
• backend/src/http/middleware/auth.ts, account.ts, seat.ts, operator.ts
• backend/src/domains/subscriptions/tables/seats.table.ts, dependents.table.ts
• backend/src/domains/consents/tables/consent-requests.table.ts, relationship-checks.table.ts
• backend/src/http/routes/channels/schemas.ts
• backend/src/http/routes/seats/activate.route.ts, seats/protection.route.ts, accounts/home.route.ts
• backend/src/domains/protection/dtos/protection.dto.ts, use-cases/state-watch.ts
• apps/docs/src/lib/openapi.ts, apps/docs/src/app/api/proxy/route.ts
• .specs/features/redesign/api-map.md (§0.2 regras de privacidade)
• AD-009, AD-010, AD-018, AD-019