Ir para o conteúdo

Backend - API (Contrato Técnico)

Objetivo

Definir o contrato operacional entre backend e clientes (web/mobile), com foco em compatibilidade, segurança e previsibilidade.

Responsabilidades

  • Documentar convenções de request/response.
  • Registrar requisitos de autenticação e autorização.
  • Organizar grupos de endpoints por contexto funcional.

Fora do Escopo

  • Implementação interna de handlers/services.
  • Regras visuais de consumo no frontend/mobile.
  • Política detalhada de deploy (ver DevOps).

Fluxo Interno

  1. Cliente envia request para /api/*.
  2. Middleware valida autenticação (JWT) e autorização (role/módulo).
  3. Handler delega para service de domínio.
  4. Service orquestra persistência/integrações.
  5. API responde com payload padronizado e códigos HTTP apropriados.

Base URL

  • Produção: https://api.billings-ease.com/api
  • Desenvolvimento: http://localhost:8080/api

Autenticação

Header obrigatório para rotas protegidas:

Authorization: Bearer <token>

Detalhes em Autenticação.

Convenções de Resposta

Sucesso

{ "data": { } }

ou

{ "message": "...", "id": 123 }

Erro

{ "message": "descrição do erro" }

Status principais: 400, 401, 403, 404, 409, 422, 500.

Grupos de Endpoints

Público

  • POST /auth/login
  • POST /auth/register
  • POST /auth/refresh
  • POST /auth/forgot-password
  • POST /auth/reset-password
  • POST /auth/verify-email
  • POST /auth/resend-verification
  • GET /auth/oauth/:provider
  • GET /auth/oauth/callback/:provider
  • POST /auth/oauth/mobile/:provider

LGPD (Direitos do Titular)

  • POST /lgpd/me/data-export-requests
  • GET /lgpd/me/data-export-requests/:request_id
  • GET /lgpd/me/data-export-requests/:request_id/download
  • POST /lgpd/me/account-deletion-requests
  • POST /lgpd/me/account-deletion-requests/:request_id/confirm
  • PATCH /lgpd/me/personal-data
  • POST /lgpd/me/consents/revoke
  • GET /lgpd/me/requests
  • GET /lgpd/me/consents/history

Regras relevantes: - isolamento estrito por user_id para leitura e mutação; - requests sensíveis com rate-limit; - exportação assíncrona (queued, processing, completed, failed); - download com URL assinada e expiração curta; - exclusão com dupla etapa (pending_confirmation -> scheduled) e execução por job; - ao entrar em scheduled, usuário é desativado imediatamente e sessões refresh são revogadas.

Ciclos e Observações

  • gestão de ciclo ativo
  • registro diário
  • análise e detalhes de ciclo

Administração Billings

  • catálogos (symbols, sensations, appearances)
  • regras day-based

Marketplace e Financeiro

  • cursos, pedidos, comissões
  • ledger e informações de pagamento
  • catálogo agregado (GET /marketplace/catalog)
  • catálogo administrativo (GET /marketplace/admin/catalog)
  • exclusão lógica de curso para profissional (POST /marketplace/professional/courses/:id/delete)
  • GET /legal/me/pending
  • POST /legal/me/accept
  • GET /users/me/product-onboarding
  • PATCH /users/me/product-onboarding

Onboarding obrigatório do método (cliente)

  • PUT /client/profile/method-onboarding
  • PUT /client/profile/pbi
  • GET /client/profile (retorna novos campos de onboarding e origem de PBI)

Campos novos em client_profiles expostos via API: - knows_billings_method (boolean | null) - knows_own_pbi (boolean | null) - wants_professional_guidance (boolean | null) - method_onboarding_version (number) - pbi_defined_by ("client" | "professional" | null)

Regras principais: - Onboarding obrigatório para clientes novas (method_onboarding_version = 0). - Clientes legadas (method_onboarding_version = 1) mantêm fluxo antigo sem bloqueio imediato. - Conclusão do novo fluxo salva method_onboarding_version = 2. - Conclusão do onboarding não cria ciclo automaticamente. - Auto-PBI da cliente só é permitido quando conhece método e já identificou o próprio PBI. - Atualização de PBI pela orientadora define pbi_defined_by = "professional".

Regra de criação do primeiro ciclo (POST /cycles)

  • O primeiro ciclo deve ser criado manualmente pela cliente.
  • Para o primeiro ciclo:
  • start_date não pode ser futura.
  • start_date não pode ser anterior a 12 meses.
  • Para ciclos subsequentes, mantém-se o comportamento padrão de criação.

Módulos e Acesso

  • snapshot de módulos efetivos por usuário
  • enforcement de acesso por role/módulo

Pontos de Atenção / Riscos

  • Quebra de contrato sem compatibilidade controlada impacta web e mobile.
  • Erro de autorização apenas no cliente cria bypass de segurança.
  • Campos opcionais sem semântica clara geram bugs de integração.

Dependências Relevantes

  • Middleware de auth/role/profile.
  • Banco PostgreSQL (consistência transacional).
  • Integrações externas (R2, email, provedores OAuth).

Versionamento e Mudanças de Contrato

  • Mudança breaking exige ADR + plano de migração.
  • Preferir evolução aditiva de payload.
  • Documentar depreciação com janela de remoção.

Referências