Skip to content

Matriz de Políticas — API Nova (PASI) — Versão 1.2

Referência única para Gateway, segurança, governança, observabilidade/rastreabilidade, testes, e entrega automatizada (CI/CD + segredos) da API Nova.
Foco do MVP para parceiros: fluxo completo cotação → proposta → finalizar adesão.

1) Contexto operacional e regra de ouro

Contexto atual (legado)

  • Publicação manual com troca de credenciais hardcoded e cópia de DLL em servidor via RDP.
  • Isso cria risco alto: credenciais expostas, erro humano, falta de rastreabilidade e inconsistência entre HML/PRD.

Regra de ouro na API Nova

  • Nenhuma credencial fica hardcoded no código-fonte.
  • Deploy automatizado por ambiente com artefato versionado e rastreável.

2) Ambientes

  • HML e PRD
  • Banco SQL Server exclusivo por ambiente
  • Client ID por ambiente (parceiros terão credenciais diferentes em HML e PRD)

3) Borda e segmentação (Gateway obrigatório)

3.1 Decisão fechada

  • Gateway desde o início (entrada única).
  • Validação de token no Gateway (JWT).

3.2 Segmentação por rota (padrão)

  • /v1/auth/*
  • /v1/partners/*
  • /v1/cliente/*
  • /v1/corretor/*
  • /v1/superapp/*
  • /v1/whatsapp/*
  • /v1/ai/*
  • /v1/webhooks/* (Pix)

3.3 Funções obrigatórias do Gateway

  1. Roteamento por público/canal (segmentação por rota).
  2. Políticas por rota:
    • validação de JWT
    • allowlist IP (parceiros)
    • CORS (portais)
    • rate limit / quota
  3. Rastreabilidade de borda:
    • gerar/propagar X-Correlation-Id
    • log mínimo de acesso (rota/status/latência/consumer/client_id)

3.4 Limite do Gateway (importante)

O Gateway valida autenticidade do token e aplica políticas de borda.
A API/Core valida autorização por vínculo (ownership) e regras de negócio (status/transições).
Isso é obrigatório para evitar “bug global” de autorização.

3.5 Pendente

  • [A DEFINIR] tecnologia do Gateway (produto/stack).

4) Versionamento

  • /v1 como versão base.
  • Breaking changes somente em /v2.

5) Autenticação

5.1 Parceiros (B2B) — decisão fechada

  • OAuth2 Client Credentials via Auth interno.
  • Allowlist de IP no Gateway (suporta múltiplos IPs e faixas/CIDR).
  • mTLS: apenas mapeado como hardening futuro (não no MVP).

5.2 Usuários (Portal Cliente/Corretor/SuperApp)

  • Bearer token
  • Access token: 45 min
  • Refresh token: sim

5.3 Auth interno (emissor)

O Auth interno deve: - armazenar segredo do cliente de forma segura (hash forte; nunca em texto puro), - emitir JWT com claims mínimas: - iss, aud, sub=client_id, exp, iat, jti - consumer (ex.: partners) - partner_id - scopes (lista)

Gateway valida assinatura + iss/aud/exp.
API valida scopes + ownership.

5.4 Pendências do Auth interno (para fechar o contrato do token)

  • [A DEFINIR] valores de iss e aud (strings oficiais).
  • [A DEFINIR] TTL do token de parceiro (recomendação: curto, ex. 10–30 min; sem refresh).

6) Autorização no Core (ownership obrigatório)

6.1 Princípio

Autenticação ≠ autorização.
Além de estar autenticado, precisa passar em uma policy que valide: - scope exigido pelo endpoint - ownership/vínculo ao recurso

6.2 Regras mínimas de ownership

  • Parceiro só acessa/alterar recursos criados pelo próprio parceiro (cotação/proposta/adesão).
  • Usuário só acessa recursos do seu vínculo (cliente/contratos/documentos/faturas).

6.3 Observação de arquitetura (MVC)

Mesmo em MVC, evitar “authorization espalhada” em controller.
Recomendação: policy/validação de vínculo centralizada (biblioteca/serviço de autorização).

7) Rate limit e quotas (Gateway)

7.1 Aplicação

  • Por client_id + IP + rota (parceiros)
  • Por sub + IP (usuários)

7.2 Defaults iniciais (até existir métrica real)

Como vocês ainda não têm métricas, adotar defaults conservadores e ajustar com base em logs/429:

  • Geral /v1/partners/*: 2 req/s sustentado, burst 10
  • Criar cotação/proposta: 1 req/s sustentado, burst 3
  • Finalizar adesão: 0,5 req/s sustentado, burst 2
  • Quota diária: 10.000 req/dia por parceiro (ajustável)

[A DEFINIR]: refino após primeiros parceiros entrarem (1–2 semanas de uso).

8) Idempotência (decisão: NATURAL, sem Idempotency-Key)

8.1 Decisão fechada

  • Não usar Idempotency-Key.
  • Endpoints críticos serão naturalmente idempotentes.

8.2 Obrigatório para o MVP (parceiros)

Para suportar retries/timeout sem duplicar cotação/proposta/adesão, o MVP precisa de um identificador externo do parceiro.

Requisito de contrato - Requests de criação/finalização devem incluir um identificador do parceiro, por exemplo: - external_reference (nome a definir)

Implementação no SQL Server - Índice/constraint único: (partner_id, external_reference) nas entidades pertinentes. - “Finalizar adesão” deve ser safe repeat: - se já estiver finalizada, retorna estado atual e não replica efeitos.

8.3 Pendência

  • [A DEFINIR] nome do campo no contrato: external_reference ou outro.
  • [A DEFINIR] em quais endpoints do fluxo ele é obrigatório (recomendado: criar cotação/proposta e finalizar adesão).

9) Observabilidade, rastreabilidade, logs e auditoria (decisão: SQL Server)

9.1 Decisão fechada

  • Logs e auditoria no banco (SQL Server).
  • Retenção: 60 dias.

9.2 Correlation

  • X-Correlation-Id obrigatório (Gateway gera se ausente).
  • Propagar para logs e respostas de erro.

9.3 Logs estruturados (mínimo obrigatório)

Registrar por request: - correlation_id, request_id, environment, consumer, - client_id (parceiros) ou sub (usuários), - route, method, status_code, latency_ms.

9.4 Log de erros

Em app_errors, registrar: - contexto do request (campos acima), - error_type, message, stacktrace, - sem PII (masking obrigatório).

9.5 Auditoria de negócio

Em audit_events, registrar eventos relevantes: - “parceiro criou cotação”, “parceiro finalizou adesão”, etc. - partner_id/client_id, action, resource_id, result, timestamp, correlation_id.

9.6 Estrutura mínima sugerida (SQL Server)

  • audit_events (eventos de negócio)
  • app_errors (erros)
  • job diário de expurgo > 60 dias

9.7 Stack futura

  • Sem stack definida por enquanto (ok).
  • Observação: se volume crescer, migrar logs de aplicação para stack própria e manter auditoria no DB.

10) Webhooks (Pix)

10.1 Escopo

  • Pix terá webhook inbound em /v1/webhooks/pix/*.

10.2 Autenticação e proteção

  • Assinatura (HMAC/JWS) + anti-replay (timestamp/nonce/event_id).

10.3 Deduplicação

  • Deduplicar por event_id (isso é “idempotência de evento”, não Idempotency-Key).

11) WhatsApp e IA (MVP restrito)

11.1 Decisão fechada no MVP

  • WhatsApp e IA não executam ações em nome do usuário.
  • Permitido:
    • iniciar fluxo
    • consultar status não sensível
    • coletar dados para uso posterior em canal autenticado

11.2 Alerta estrutural (se futuramente precisarem agir)

Se WhatsApp/IA passarem a executar ações sensíveis em nome do usuário, será necessário: - modelo de delegação/consentimento - step-up/validação adicional - acting_user no contexto - auditoria reforçada por canal - allowlist de capacidades (especialmente IA)

12) CORS (portais)

  • CORS restrito por domínio no Gateway para:
    • Portal Cliente
    • Portal Corretor
  • Proibir CORS aberto (*) com credenciais.

13) Padrão de erros (contrato)

  • 400 validação
  • 401 não autenticado
  • 403 sem permissão/ownership
  • 404 quando aplicável (evitar “confirmar existência” indevidamente)
  • 409 conflito (ex.: transição de status inválida)
  • 429 rate/quotas

Envelope recomendado: - code, message, correlation_id, details (sem dados sensíveis)

14) CI/CD e segredos (automatizar o cenário que hoje é manual)

14.1 Objetivo

Eliminar: - credenciais hardcoded em classe/arquivo - publicação manual por Visual Studio - cópia manual de DLL via RDP

14.2 Estratégia prática (compatível com “servidores terceirizados”)

Cenário recomendado para MVP (sem depender de cloud): 1. Build + testes no GitHub Actions 2. Gerar artefato versionado (zip/package) 3. Deploy automatizado para servidor Windows/IIS via um método suportado pela infra

Opções comuns (ordem do mais “padrão” ao mais “simples”): - MSDeploy/Web Deploy (ideal para IIS) - WinRM/PowerShell Remoting (script que copia, faz backup, troca pasta, recicla app pool) - SMB + script remoto (menos ideal, mas funciona) - Self-hosted runner dentro da rede da infra (muito provável ser necessário)

Observação importante: se os servidores forem “rede fechada”, GitHub-hosted runner não alcança. Normalmente resolve com self-hosted runner dentro da rede/VM com acesso aos servidores.

14.3 Segredos (sem expor credenciais)

Como vocês ainda não definiram 100% a infra, a política fica assim: - Destino preferencial: KeyVault - Fallback MVP: GitHub Actions Encrypted Secrets

Alternativas (mapeadas): - HashiCorp Vault - Secret manager do provedor (AWS/GCP) - Secrets do Kubernetes (se houver k8s), com criptografia e RBAC

14.4 Mudança obrigatória no código (para nunca mais “CONFIGURACOESBANCO hardcoded”)

Na API Nova: - connection strings vêm de configuração por ambiente (env vars / secret store / arquivo fora do repo), - nunca de classe com senha em string no código.

[A DEFINIR]: como a infra terceirizada vai fornecer/permitir a configuração segura: - acesso do app ao KeyVault (saída para internet? service principal? certificado?) - ou manter por enquanto via secrets injetados no deploy

15) Testes (desde o início, integrado ao fluxo)

15.1 Unitários (obrigatório)

  • transições de status de cotação/proposta/adesão
  • validações de domínio
  • ownership (parceiro só enxerga o que é dele)
  • validação de scopes por endpoint

15.2 Integração (obrigatório para Partner API)

  • autenticação do parceiro (token real/validação real)
  • persistência SQL Server
  • idempotência natural via (partner_id, external_reference)
  • erros padrão + correlation id

15.3 Recomendado (quando estabilizar)

  • testes de contrato do /v1/partners (para não quebrar parceiro sem querer)