# 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](/br/documentacao/configuracoes-do-runtime.md).
{% 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](/br/solucao-de-problemas/sso-e-login.md).
{% 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](/br/tutoriais-praticos/2.-prompts-rapidos.md).
{% 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](/br/solucao-de-problemas/performance-e-lentidao.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.madrix.dev/br/documentacao/integracoes-e-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.