Operações e Gerenciamento de → Integração com ferramentas externas

Integração com ferramentas externas

1) Por que é necessário

Quase qualquer plataforma de alimentos é baseada em um ecossistema externo: provedores de pagamentos, KYC/AML, antifrode, email/SMS/push, analista, provedores de estúdios de jogos, BI, CDP, ask gerentes, ferramentas de marketing. Integrações bem projetadas aumentam a conversão e a farmácia; analfabetos - Multiplicação de rejeitos em cascata, contas inesperadas e multas de SLA.

• Conectar os provedores rapidamente e com segurança.
• Manter o negócio SLO (depósito, taxa, conclusão, jogo de lançamento).
• Gerenciar quotas/limites e custos.
• Reduzir raio de falha e MTTR.

2) Taxonomia de integrações

API sincronizada (REST/gRPC/GraphQL): respostas instantâneas, dependência severa por latência e disponibilidade.
Asinhrones (webhook/event/queue): entrega de eventos, confirmação, menos conectividade de tempo.
Bibliotecas SDK/clientes: velocidade de implementação, mas risco de dependências invisíveis e «magia».
Batch/ETL/SFTP/compartilhamento de arquivos: relatórios, recepção, descarga noturna.
iFrame/Redirect/Hosted page: rápido, mas menos controle UX/Security.
Hybrid: chamada sincronizada + confirmação asincrona (muitas vezes para pagamentos/CUS).

3) Modelo de gerenciamento de integração (governance)

Catálogo de integrações: proprietário, contatos, on-call, contratos (OpenAPI/AsyncAPI), versões, ambiente, chaves/segredos, quotas e tarifa.
Acordos SLO/OLA: O que garantimos ao usuário e o que o provedor promete; ligação explícita SLO ↔ OLA/SLA.
Gates de lançamento: consumer-driven controls (CDC), testes de compatibilidade, inclusão canária, ficheflags.
Políticas de dados PII, finados, GDPR/CCPA, regiões de armazenamento, DPA com vendedores.

4) Segurança e segredos

Armazenamento de segredos: KMS/Secret Gerente, Rotation, Direitos Menores, Acesso a Contas de Rol.
Assinatura e verificação: HMAC/JWS para webhook 'ov, TLS mútual para servidor-servidor.
IP allowlist/ mTLS/WAF: proteja os canais de entrada e saída.
Tocen scope: direitos API estreitos, chaves individuais por ambiente.
Auditoria trail: Todas as chamadas de saída e alterações de configurs - para o logotipo de auditoria.

5) Quotas, rate limits e confiabilidade

Claro rate-limit per-provider para não partir para 429/ban.
Isolamento Bolkhead: pool de fluxo/conexões selecionados para cada provedor.
Temporizações <orçamento de latência, para não gerar chamadas zombies.
Retrai com backoff + jitter: somente para operações/códigos idumpotentes.
Circuito breaker: «queda» rápida e reversão para o folhetim durante a degradação.
Queue + Outbox: para operações críticas - entrega garantida e repetição.

providers:
psp_x:
timeout_ms: 200 rate_limit_rps: 1500 retries: 2 retry_on: [5xx, connect_error]
backoff: exponential jitter: true circuit_breaker:
error_rate_threshold: 0.05 window_s: 10 open_s: 30 pool: dedicated-psp-x (max_conns: 300)

6) Contratos, versões e compatibilidade

OpenAPI/AsyncAPI + SemVer: extensões - backward-compatível; remoção - através do período de deprekate.
Testes CDC: O consumidor registra as expectativas; O lançamento do provedor é bloqueado por incompatibilidade.
Schema Registry (eventos): evolução dos circuitos (Avro/JSON-Schema); política can-read-old/can-write-new.
Controle de alterações: Mudança, arquibancadas de migração, data de desativação da versão antiga.

7) Ambientes e sandbox

Sandbox/Estágio/Prod no vendedor - obrigatório.
Dados de teste: geradores PII-like, cartões/documentos falsos, carteiras de teste.
Contract & integration tests: versus stage com limites reais.
Golden-path & chaos-path: happy-case e cenários negativos (timeouts/4xx/5xx/webhook-retries).

8) Observabilidade e dashboards

Метрики per-integration: `outbound_rps`, `p95/p99`, `error_rate`, `retry_rate`, `circuit_open`, `cost_per_1k_calls`.
Webhook health: atraso na entrega, percentual de repetições, assinatura/validação.
Eventos de lançamento/fichiflags: anotações em gráficos.
Mapa de dependências: Quem acessa o provedor onde há estreitos.

9) Incidentes e escalações

Correlação de alertas: se o provedor de suporte é o software do dono da integração, não todos os consumidores.
Ajuste automático: ficheflags «modo mínimo» (conteúdo light simplificado por KYC flow, filas de processamento).
Feelover/multi-vendedor: PSP-X ⇄ PSP-Y, KYC-A ⇄ KYC-B; Um swich manual e automático.
Runbook: como confirmar um incidente com um vendedor, aumentar quotas, incluir uma rota alternativa, reverter.

• Diagnóstico de integração dashboard, status do vendedor, nossos logs com 'trace _ id'.
• Ações: reduzir RPS, abrir breaker, ligar o feelover, mudar o fichiflag.
• Comunicações: canal de incidente, modelo de update para negócios/safort.
• Reversão/verificação: p95/erro-rate normal, fila processada, gastos no limite.

10) Gerenciamento de custos

O modelo CPM/CRA/SRS/Chamadas é "pisotear" _ per _ 1k _ calls "e" custo de sucesso ".
Quotas e «soft-cap»: liminares de proteção, avisos.
Cachagem e dedução: redução de chamadas extras (idempotency keys).
Relatórios e recepção: Acerto diário de contas com os nossos logs.

11) Trabalhar com webhooks

Entrega: 'at-least-once', repetição com atraso exponencial, dedução por 'event _ id'.
Segurança: assinatura (HMAC/JWS), temporização, mTLS/allowlist.
Confiabilidade: resposta 2xx somente após a gravação em outbox/txn, senão o provedor retraita.
Idempotidade: Processadores - Idumpotentes, armazenando «seen events».

12) Dados, privacidade e complacência

Data minimization: solicitar apenas o necessário.
PII/finded: camuflagem em logs, toquenização, criptografia.
Data residency: onde os dados (registros) são armazenados e processados.
DPA/SCC: acordos de processamento de dados, subprocessadores.
Direito de remoção/exportação: API/processos do lado do vendedor.

13) Anti-pattern

Um pool comum de conexões em todos os vendedores → head-of-line blocking.
Retraias no tempo de um local estreito → «tempestade de retrações».
Não há assinatura/validação de webhook → frodos ou eventos falsos.
Segredos em variáveis de ambiente sem rotatividade ou direitos explícitos.
A falta de CDC e de versões de contratos → quedas em massa nas atualizações do vendedor.
Um estoque forte no SDK sem observabilidade → uma caixa preta.

14) Folha de cheque de implementação

• Cartão de integração no catálogo: proprietário, SLA/OLA, tarifa, contatos, chaves, esquemas.
• OpenAPI/AsyncAPI + CDC; testes de estágio, aço canário.
• Timouts, retrações (idempotidade!), breaker, bulkhead, rate-limit.
• Segredos: KMS/SM, rotação, chaves individuais per-eng.
• Webhook: assinatura, deadup, reaproveitamento, outbox.
• Dashboard e alertas per-integration; anotações de lançamentos.
• Plano de feelback (segundo provedor/switch manual), runbook e contatos.
• Relatórios de custo e recepção.
• DPA/complacência, política de dados, auditoria-logs.
• Game-days/chaos para os principais vendedores.

15) KPI qualidade de integração

Sucess rate sobre transações críticas (depósito/taxa/retirada).
p95/p99 chamadas de saída.
Retry storm count/mês (→ alvo 0).
MTTD/MTTR sobre incidentes de provedores.
Vale por 1k calls/ação de sucesso.
CDC pass rate e proporção de lançamentos sem incidentes de integração.
Webhook latency e repetência.

16) Desfalques rápidos

Timeout = 70 a 80% do orçamento do elo; o tempo superior da solicitação é mais curto do que o valor interno.
Retrai ≤ 2, apenas 5xx/rede, com backoff + jitter.
Circuito breaker: '> 5% de erros por' 10s ',' open = 30s ',' half-open 'por amostras.
Rate-limit per-provider, um pool de conexões separado.
Webhook: confirmar após a gravação, por 'event _ id'.
Ficheflag para transferência rápida para «modo mínimo».

17) Exemplos de alertas (ideias)

ALERT ProviderErrorRateHigh
IF outbound_error_rate{provider="psp_x"} > 0.05 FOR 5m
LABELS {severity="critical", team="payments"}

ALERT ProviderLatencySLO
IF outbound_p99_latency_ms{provider="kyc_a"} > 300 FOR 10m
LABELS {severity="warning", team="risk"}

ALERT WebhookDeliveryDelayed
IF webhook_delivery_p95_s{provider="studio_y"} > 20 FOR 15m
LABELS {severity="warning", team="games"}

ALERT ProviderCostSpike
IF rate(provider_cost_usd_total[15m]) > 2 baseline_1w
LABELS {severity="info", team="finops"}

18) FAQ

O que distinguir uma falha temporária do provedor dos nossos problemas?
A: Veja simetria: aumento de erros para todos os clientes do provedor, abertura de breaker, falta de erros internos/regressão. Traçados e logs s 'peer. service 'ajudam.

Precisamos sempre de um segundo provedor?
A: Para caminhos críticos, sim (PSP/KYC). Para os menos críticos, bastante degradação e dinheiro.

Q: SDK vendedor ou cliente próprio?
A: SDK acelera a partida, mas consuma observação, config temporizadores/retrações e a possibilidade de pinning versões. Senão, o seu cliente está acima de mim.