Integrações - APIs Externas e Webhooks

Resumo

Hub de integrações com serviços externos: providers, webhooks de entrada/saída, chaves de API, catálogo de APIs suportadas, logs de integração, testes em lote, histórico de preços, import/export, gateways, plugins e contas vinculadas via OAuth2.

Para quem é (papel/role)

• super-admin - catálogo global e credenciais de plataforma.
• tenant-admin - integrações do próprio tenant.

O que você pode fazer

Overview

• Painel consolidado: status das integrações, alertas, volume.

API catalog

• Catálogo de APIs suportadas: 223+ providers mapeados.
• Documentação e SDK por provider.

External APIs

• CRUD de integrações: provider, credenciais, scopes.
• Testar conexão.

API keys

• Chaves de API da plataforma: geração, rotação, revogação.
• Scopes e limites por chave.
• Expiração automática.

API usage dashboard

• Consumo por provider / chave / tenant.
• Rate limit e custo estimado.

Webhooks

• Webhooks de entrada: endpoint gerado pela plataforma.
• Webhooks de saída: registrar destinos para eventos internos.
• Retry, reenvio e inspeção de entrega.

Providers

• Providers conectados e seus estados.

Alertas

• Alertas de integrações: falha, rate limit, expiração de token.

Logs

• Log de requests/responses (redação de dados sensíveis).

Accounts

• Contas conectadas via OAuth2: Google, Microsoft, Apple, etc.
• Top 10 providers suportados com PKCE.

Gateways

• Gateways configurados (ver também billing-gateways.md).

Batch tests

• Execução em lote: testar N integrações de uma vez.

Import/export

• Export JSON da configuração de integrações.
• Import com validação.

Pricing history

• Histórico de preços de providers pagos.

Plugins

• Integrações com plugins (marketplace).

SMM Config

• Integração com provedores SMM.

Como acessar

1. /admin.
2. Settings → Integrações ou /admin/settings/integrations.

Tutoriais

Conectar Google via OAuth2

1. /admin/settings/integrations/accounts.
2. Clique em Conectar Google.
3. Autorize no fluxo OAuth2 com PKCE.
4. A conta aparece como conectada.

Registrar webhook de saída

1. /admin/settings/integrations/webhooks.
2. Registrar endpoint com URL destino.
3. Selecione eventos (ex: user.created, invoice.paid).
4. Salve. Secret gerado para HMAC.

Reenviar entrega de webhook falha

1. Abra o webhook.
2. Em Log, localize a entrega falha.
3. Clique em Retry.

Gerar API key com scopes limitados

1. /admin/settings/integrations/api-keys.
2. Gerar chave com scopes read:users, read:invoices.
3. Defina expiração (30/60/90 dias).
4. Copie a chave (exibida uma única vez).

Integrações

• Billing - gateways também aparecem aqui (billing-gateways.md).
• External APIs - chaves globais da plataforma (external-apis-chaves-globais.md).
• Infraestrutura - pipeline de webhooks (infrastructure-servidor.md).
• Observabilidade - logs e alertas de integrações (observability-logs-metricas.md).
• Eventos - webhooks ouvem eventos do Event Bus.

Perguntas frequentes

Quantos providers são suportados? 223+ providers catalogados em 12 controllers especializados.

Webhooks assinados? Sim, HMAC SHA-256 com secret por endpoint.

Rate limit por API key? Configurável via platform-feature-flags.md e API gateway.

Posso revogar chave perdida? Sim, imediatamente. Deixa de funcionar em cache próximo (poucos segundos).

OAuth2 suporta Apple Sign In? Sim, via ProviderAdapterService.

Webhook suporta retry com backoff? Sim, com backoff exponencial configurável.

Import de config pode sobrescrever credenciais? Sim, com confirmação explícita.

Logs redigem dados sensíveis? Sim. Tokens/chaves são mascarados.

Limitações, políticas e avisos

• Credenciais armazenadas criptografadas em repouso.
• Chaves expiradas param de funcionar automaticamente.
• Webhook com muitas falhas é temporariamente suspenso (circuit breaker).
• Scopes de API key seguem princípio do menor privilégio.

Relacionados

• external-apis-global-keys.md
• billing-gateways.md
• infrastructure-server.md
• observability-logs-metrics.md