Módulo de Integrações

Documentação técnica do módulo de integrações polimórficas — gateways de pagamento, bancos e mensageria via WhatsApp.

Arquitetura

O sistema resolve o provider ativo em tempo de execução com base nas credenciais configuradas pelo tenant. Nenhuma lógica de negócio precisa saber qual provider está ativo.

IntegrationsController
        ↓
  IntegrationService
        ↓
  IntegrationProviderFactory
   ├─ IPaymentGateway  →  MercadoPagoGateway | FastGivrGateway
   ├─ IBankProvider    →  SicoobBankProvider | BBBankProvider
   └─ IWhatsAppProvider→  EvolutionApiWhatsApp

Providers Disponíveis

Provider	Tipo	Descrição
FastGivr	Payment	Gateway próprio da plataforma FastGivr (PIX, cartão, boleto)
MercadoPago	Payment	Gateway MercadoPago (PIX, cartão, boleto)
Sicoob	Bank	Cooperativa de crédito — extrato e saldo via API OAuth2
BB	Bank	Banco do Brasil — extrato e saldo via Developer Portal
EvolutionApi	Messaging	Instância WhatsApp via Evolution API (self-hosted)

---

Modelo de Dados

interface TenantIntegration {
  id: string;
  companyId: string;
  provider: 'FastGivr' | 'MercadoPago' | 'Sicoob' | 'BB' | 'EvolutionApi';
  type: 'Payment' | 'Bank' | 'Messaging';
  isActive: boolean;
  status: 'Connected' | 'Error' | 'NotConfigured';
  lastErrorMessage?: string;
  lastTestedAt?: string;
  credentialsMasked: Record<string, string>;  // sensitive fields: ****xxxx
  updatedAt: string;
}

Credenciais são armazenadas criptografadas com AES-256 no banco. A API nunca expõe valores completos de campos sensíveis — apenas os últimos 4 caracteres mascarados.

---

Endpoints

Método	Endpoint	Papel mínimo	Descrição
GET	/integrations	Admin	Listar integrações do tenant
PUT	/integrations/:provider	Admin	Criar ou atualizar credenciais
DELETE	/integrations/:provider	Admin	Remover integração
POST	/integrations/:provider/test	Admin	Testar conexão
POST	/webhooks/payment/:provider?tenant=:id	— (HMAC)	Webhook polimórfico de pagamento

---

Configuração por Provider

FastGivr

{
  "ApiKey": "fgvr_live_...",
  "WebhookSecret": "whsec_...",
  "Sandbox": "false"
}

Campo	Obrigatório	Descrição
ApiKey	✅	Chave de API do ambiente
WebhookSecret	✅	Secret HMAC-SHA256 para validar webhooks
Sandbox	❌	"true" para ambiente de testes (padrão: "false")

URL de webhook a configurar no painel FastGivr:

POST https://api.systemclinic.com.br/webhooks/payment/FastGivr?tenant={companyId}

---

MercadoPago

{
  "AccessToken": "APP_USR-...",
  "WebhookSecret": "..."
}

Campo	Obrigatório	Descrição
AccessToken	✅	Token de acesso da aplicação MP
WebhookSecret	❌	Secret para validação de assinatura (v1)

URL de webhook a configurar no Mercado Pago Developers:

POST https://api.systemclinic.com.br/webhooks/payment/MercadoPago?tenant={companyId}

---

Sicoob

{
  "ClientId": "...",
  "ClientSecret": "...",
  "CooperativeCode": "0756",
  "AccountNumber": "123456"
}

Campo	Obrigatório	Descrição
ClientId	✅	Client ID do app cadastrado no Sicoob Developers
ClientSecret	✅	Secret correspondente
CooperativeCode	✅	Número da cooperativa (4 dígitos)
AccountNumber	✅	Número da conta corrente

Scopes solicitados: cobranca_boletos-consultar conta-corrente-consultar

---

Banco do Brasil

{
  "DeveloperAppKey": "...",
  "BasicCredentials": "base64(clientId:clientSecret)",
  "AccountNumber": "123456-7",
  "AccountType": "corrente"
}

Campo	Obrigatório	Descrição
DeveloperAppKey	✅	gw-dev-app-key do Portal BB Developers
BasicCredentials	✅	base64(clientId:clientSecret) do OAuth2
AccountNumber	✅	Número da conta com dígito
AccountType	❌	"corrente" ou "poupanca" (padrão: "corrente")

Scopes solicitados: extrato.read saldo.read

---

Evolution API (WhatsApp)

{
  "BaseUrl": "https://evolution.suaempresa.com.br",
  "ApiKey": "...",
  "Instance": "clinica-principal"
}

Campo	Obrigatório	Descrição
BaseUrl	✅	URL da instância Evolution API (self-hosted)
ApiKey	✅	API Key configurada na instância
Instance	✅	Nome da instância WhatsApp

A instância precisa estar em estado open (QR Code lido) para que o teste de conexão passe.

---

Webhook de Pagamento (Polimórfico)

POST /webhooks/payment/{provider}?tenant={companyId}

Fluxo:

1. Lê o body raw para validação HMAC
2. Resolve o provider configurado para o tenant
3. Valida assinatura (X-Signature ou X-Hub-Signature-256)
4. Normaliza o evento para PaymentConfirmedEvent (provider-agnostic)
5. Encaminha ao módulo financeiro (quando implementado)

Headers esperados por provider:

Provider	Header de assinatura
FastGivr	X-Signature
MercadoPago	X-Signature (formato ts=...,v1=...)

---

Uso em Outros Serviços

// Resolver gateway ativo do tenant
var gateway = await integrationService.ResolvePaymentGatewayAsync(companyId);

// Resolver provider bancário específico
var bank = await integrationService.ResolveBankProviderAsync(companyId, "Sicoob");
var transactions = await bank.GetTransactionsAsync(from, to);

// Resolver WhatsApp
var wa = await integrationService.ResolveWhatsAppProviderAsync(companyId);
await wa.SendTextAsync("+5511999998888", "Seu agendamento foi confirmado.");

---

Segurança

• Credenciais armazenadas com AES-256 via IEncryptionService
• API nunca retorna valores completos de campos sensíveis (AccessToken, ApiKey, ClientSecret)
• Webhooks validados por HMAC-SHA256 antes de qualquer processamento
• Apenas roles Admin e Owner podem gerenciar integrações
• Cada integração é isolada por companyId (multi-tenant)

Adicionar novo provider

1. Implementar IPaymentGateway, IBankProvider ou IWhatsAppProvider em Services/Integrations/Providers/
2. Adicionar o case no IntegrationProviderFactory
3. Declarar campos obrigatórios em IntegrationService.RequiredFields
4. Classificar o tipo em PaymentProviders, BankProviders ou MessagingProviders