# 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.

{% hint style="info" %}
Integrações quase sempre mexem com autenticação e governança. Combine com [Configurações do Runtime](https://docs.madrix.dev/br/documentacao/configuracoes-do-runtime).
{% endhint %}

### 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.

{% hint style="warning" %}
Se você usa SSO corporativo, valide claims e mapeamento de grupos. Veja [SSO e login](https://docs.madrix.dev/br/solucao-de-problemas/sso-e-login).
{% endhint %}

### 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.

<details>

<summary>Template de especificação (copiar e colar)</summary>

```
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
```

</details>

### 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”).

{% hint style="info" %}
Se você precisa “integrar rápido”, comece com híbrido. Webhook falha. Reconciliar salva.
{% endhint %}

### 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.

{% hint style="success" %}
Para um prompt pronto de integração com log + reprocessar, veja o bloco **Integrações** em [Prompts rápidos](https://docs.madrix.dev/br/tutoriais-praticos/2.-prompts-rapidos).
{% endhint %}

<details>

<summary>Prompt base — integração via webhook (copiar e colar)</summary>

```
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.
```

</details>

### 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](https://docs.madrix.dev/br/solucao-de-problemas/performance-e-lentidao).