Skip to main content

Módulo 05: Integrações Plugáveis

Status: Rascunho Inicial

1. Contratos de API (RESTful)​

1.1 Gerenciamento das Chaves (Admin)​

GET  /api/integracoes
  Return: [{ tipo, provedor, status, ultima_sincronizacao }]

PUT  /api/integracoes/{tipo}
  Auth: Admin
  Body: { provedor, configuracao: { api_key, ... }, ambiente }
  Return: { status: "SALVO" }

POST /api/integracoes/{tipo}/testar
  Return: { sucesso: bool, mensagem, latencia_ms }

1.2 Webhooks de Retorno (Provedores -> CRM)​

POST /api/integracoes/assinatura/webhook
  Headers: X-Webhook-Secret: {secret}
  Body: { crm_contrato_id, status: "ASSINADO | RECUSADO | EXPIRADO", assinado_em }

POST /api/integracoes/erp/webhook
  Headers: X-Webhook-Secret: {secret}
  Body: { evento: "INADIMPLENCIA | QUITACAO | CANCELAMENTO", cpf_cnpj, contrato_id }

2. Segurança de Chaves​

  • Todas as credenciais inseridas na API (API Keys, Secrets) devem ser criptografadas no banco (AES-256).
  • Os GET endpoints nunca podem retornar as chaves completas. Devem mascarar retornando apenas os últimos 4 dígitos.