Skip to Content
Documentação técnica de integração SOFIA
Governança & Compliance Técnico

Governança & Compliance Técnico

Versão: 1.0
Owner: Engenharia & Compliance SOFIA
Última revisão: 2026
Aplicável a: Dev Integradores, Backend, Infra, Segurança e Auditoria

Esta seção estabelece os controles técnicos mínimos exigidos para retenção de logs, auditoria, integridade de dados e conformidade operacional.

O não cumprimento dessas diretrizes pode comprometer auditorias, investigações e estabilidade da integração.

1. Retenção de Logs

1.1 Princípios

  • Minimização: reter apenas o necessário.
  • Finalidade: logs servem para segurança, qualidade e rastreabilidade.
  • Separação por categoria: operação, auditoria e métricas possuem retenções distintas.
  • Expurgo automático: remoção programada de dados antigos.

1.2 Retenção de Dados Operacionais

Exemplo: histórico de spins.

  • Retenção configurável por variável de ambiente.
  • Expurgo automático por janela de dias.
  • Recomendação padrão: 30 dias (ajustável conforme necessidade de auditoria).

Trecho de referência:

function getRetentionDays() {
  const v = Number.parseInt(process.env.SPIN_RETENTION_DAYS || '30', 10);
  return Number.isFinite(v) && v > 0 ? v : 30;
}

Recomendações para parceiros

  • Definir política de retenção formal (30 / 90 / 180 dias).
  • Separar armazenamento “quente” e “frio”.
  • Documentar política interna.

1.3 Logs de Sistema (Erros e Incidentes)

Logs técnicos devem registrar:

  • nível (ERROR, WARN)
  • rota
  • método
  • status HTTP
  • timestamp UTC
  • identificador do usuário (quando aplicável)

É proibido:

  • logar Authorization
  • logar tokens
  • logar assinaturas HMAC
  • logar payloads completos com PII

Mascaramento é obrigatório quando houver risco de exposição.

2. Política de Auditoria

Auditoria permite responder:

Quem fez o quê, quando, e em qual contexto?

2.1 Eventos que Devem Ser Auditados

  • Login / logout
  • Falhas de autenticação
  • Mudança de permissões
  • Alterações financeiras
  • Mudança de configuração crítica
  • Alterações de webhook e chaves públicas

2.2 Estrutura Recomendada de Audit Log

type AuditLog = {
  id: string;
  created_at: string;
  actor_id: string | null;
  action: string;
  entity: string;
  risk_level: 'critical' | 'sensitive' | 'operational';
  detail: string;
  meta?: Record<string, unknown>;
};

Boas práticas

  • Imutabilidade (não editável)
  • Correlação por request_id
  • Sem PII completo
  • Armazenamento segregado

3. Integridade de Dados

3.1 Idempotência

Obrigatório para:

  • Webhooks
  • Fluxos assíncronos
  • Operações de criação sensíveis

Regras:

  • Persistir event_id
  • Rejeitar duplicados
  • Definir janela mínima (24h+)

3.2 Consistência e Rollback

Fluxos compostos devem:

  1. Validar entradas
  2. Executar operações
  3. Reverter se falhar etapa intermediária

Estado parcial não é permitido.

3.3 Validação de Entrada

  • Validar body, params, query
  • Rejeitar campos desconhecidos quando aplicável
  • Normalizar identificadores
  • Não confiar em dados do cliente

4. Segregação de Ambientes

  • Sandbox e Produção devem ser isolados.
  • Eventos devem carregar environment.
  • Chaves e URLs nunca devem cruzar ambientes.
  • Logs não devem misturar dados de ambientes diferentes.

5. LGPD Aplicado à Integração

5.1 Minimização

  • Usar IDs pseudonimizados.
  • Evitar enviar PII em eventos técnicos.

5.2 Criptografia

  • HTTPS obrigatório.
  • Criptografia em repouso recomendada.

5.3 Controle de Acesso

  • Menor privilégio.
  • Revisão periódica de acessos.
  • Offboarding imediato.

5.4 Retenção

  • Definir janela por categoria.
  • Garantir exclusão sob demanda quando aplicável.

5.5 Incidentes

  • Registrar linha do tempo.
  • Preservar evidências.
  • Evitar exposição de dados em logs.

6. Responsabilidade do Parceiro

Checklist mínimo para produção:

  • Validar assinatura e origem.
  • Implementar idempotência.
  • Não logar segredos.
  • Aplicar rate limiting.
  • Monitorar latência e erro.
  • Documentar política de retenção.
  • Revisar acessos periodicamente.

7. Controles Técnicos Esperados

Integrações maduras devem possuir:

  • Monitoramento ativo
  • Alertas para picos de 4xx/5xx
  • Registro de correlação entre API e webhook
  • Política formal de retenção
  • Documentação interna de controle de acesso

8. Limitações

Esta seção não substitui:

  • Política jurídica formal
  • Auditoria externa
  • Obrigações regulatórias específicas
Last updated on
EventosIntrodução