Integrações e API

Conecte seu app a sistemas externos com segurança e previsibilidade.

Use esta página como guia de decisão + checklist. Depois, detalhe por caso.

Integrações quase sempre mexem com autenticação e governança. Combine com Configurações do Runtime.

Decisões rápidas (antes de implementar)

1. Direção: Inbound (entrada) ou Outbound (saída)?

2. Modo: síncrono (API) ou assíncrono (eventos/webhook/fila)?

3. Frequência: real-time, near real-time, ou batch?

4. Contrato: você controla ambos os lados (melhor) ou é “API de terceiros”?

5. Confiabilidade: precisa de retries, reprocessamento, idempotência?

Checklist mínimo (produção)

• Ambientes: endpoints e credenciais por Dev/Staging/Prod.

• Autorização: menor privilégio (scopes/roles mínimos).

• Rotação de segredos: com data e dono.

• Observabilidade: logs + correlação (ex: requestId, eventId).

• Tratamento de falha: retry com backoff + dead-letter/reprocessar.

• LGPD: evite vazar PII em logs e payloads.

Autenticação de API (OAuth2/OIDC, tokens)

Escolha um padrão e documente. Evite “token fixo” sem rotação.

Opções comuns

• OAuth2 Client Credentials: bom para integração sistema-sistema.

• OAuth2 Authorization Code (com PKCE): bom quando há usuário.

• OIDC (ID token): para identidade; não substitui autorização na API.

• API keys / tokens pessoais: só se existir rotação e escopo.

Regras práticas

• Valide audience, issuer e expiração do token.

• Separe “quem autenticou” de “o que pode fazer” (claims vs roles).

• Padronize resposta de erro:

  • 401: não autenticou / token inválido/expirado.

  • 403: autenticou, mas sem permissão.

Se você usa SSO corporativo, valide claims e mapeamento de grupos. Veja SSO e login.

Rate limits e quotas

Rate limit é parte do contrato. Documente limite e comportamento de retry.

Boas práticas do cliente

• Trate 429 Too Many Requests como esperado.

• Respeite Retry-After quando existir.

• Use exponential backoff com jitter.

• Paralelismo controlado. Evite “fan-out” sem limite.

Como desenhar limites (lado servidor)

• Limite por tenant + por credencial (service account).

• Diferencie burst vs sustentado.

• Proteja endpoints caros (busca, relatórios, exportações).

Webhooks

Webhooks são o jeito mais simples de “event-driven” quando você não controla filas.

Checklist de webhooks (quem envia)

• Payload versionado (schemaVersion).

• eventId único + occurredAt.

• Retry automático com backoff.

• Assinatura do payload (ex: HMAC) + rotação do segredo.

Checklist de webhooks (quem recebe)

• Responda 2xx rápido. Processe assíncrono.

• Implemente idempotência por eventId.

• Registre: status, tentativas, último erro, tempo de processamento.

• Tenha botão/rota de reprocessar para eventos com erro.

Template de especificação (copiar e colar)

Webhook: {{nome}}

Eventos:
- {{evento1}}
- {{evento2}}

Contrato:
- eventId: string (único)
- occurredAt: ISO-8601
- type: string (nome do evento)
- payload: object (schema versionado)

Confiabilidade:
- Retry: sim, com backoff
- Idempotência: por eventId
- Timeout do receiver: {{N}}s

Segurança:
- Assinatura: HMAC-SHA256
- Header de assinatura: {{nomeHeader}}
- Rotação de segredo: a cada {{N}} dias

Connectors (ERP/CRM/…)

Conector é um pacote de integração com:

• Autenticação + renovação de credencial.

• Mapeamento de objetos (ex: Cliente ↔ Account).

• Sincronização (push, pull, ou ambos).

• Tratamento de erros e reprocessamento.

Estratégias de sync (escolha 1)

• Pull (polling): simples, mas aumenta custo e latência.

• Push (webhook/event): melhor para real-time.

• Híbrido: webhook + reconciliar diário (reduz “drift”).

Se você precisa “integrar rápido”, comece com híbrido. Webhook falha. Reconciliar salva.

Integração com banco / data access

Integração direta via banco é poderosa, mas arriscada.

Guardrails

• Prefira leitura (views/read replica) ao invés de escrita direta.

• Defina owner do schema. Evite “app escrevendo no schema do ERP”.

• Não acople em tabelas internas voláteis. Prefira views estáveis.

• Logue queries lentas. Crie índices com cuidado.

Como pedir isso no Madrix (prompts)

Se você vai gerar/ajustar integração via Chat AI, passe requisitos testáveis.

Para um prompt pronto de integração com log + reprocessar, veja o bloco Integrações em Prompts rápidos.

Prompt base — integração via webhook (copiar e colar)

Implemente um webhook para o evento {{evento}}.

Requisitos:
- Endpoint configurável por ambiente (Dev/Staging/Prod).
- Registrar payload, status, tentativas e erros em um log.
- Idempotência por eventId.
- Permitir reprocessar eventos com erro (somente Admin).
- Não expor dados sensíveis em logs.

Troubleshooting rápido

• 401/403 em integração: token expira? scopes/roles corretos?

• 429: paralelismo alto? faltou backoff? tem batch?

• Webhook duplicando: faltou idempotência por eventId.

• Integração “lenta”: chamada externa travando request principal? Veja Performance e lentidão.