Integração dos parceiros no ecossistema

1) Papéis e modelos de participação

Operadoras/marcas: vitrines, cálculos, KYC/AML, responsabilidade da experiência do usuário.
Estúdios/RGS/Agregadores de conteúdo: jogos/striam, catálogos, promoções.
Provedores de pagamento/carteiras PSP, APM, kripto, charjbacks.
KYC/AML/Antifrod: verificação, folhas de sank, risco-recapeamento.
Afiliadas/redes de marketing: tráfego, pós-back, atribuição.
ISV/integradores: plug-ins, aplicativos de marketing.

Modelos: referral/resell, white-label/OEM, marketplace/app-store, hub & spoke (federação).

2) «Passaporte do parceiro» e pacote inicial

Porquê: uma única fonte de verdade sobre direitos, zonas, versões, SLO, chaves e processos.

yaml partner_passport. v1:
partner_id: "kyc-omega"
type: "KYC/AML"
regions: ["EU","TR","LATAM"]
contracts: { msa: "2025-01-10", dpa: "2025-01-10", sla: "99. 9/30d" }
api_versions: ["identity. v1","events. v1","webhook. v1"]
auth: { oidc_client_id: "p_omega", scopes: ["kyc:read","kyc:write"] }
webhooks: { signature: "Ed25519", retry: "exp", dedupe: true, ttl_s: 300 }
rate_limits: { rps: 100, burst: 300 }
pii_policy: { minimization: true, retention: "180d", geo_pinning: ["EU"] }
recon: { window_days: 7, epsilon: 0. 002 }
owners: { biz: "ecosystem-biz", tech: "integrations" }
status: "sandbox"

3) Onboarding: processo «da candidatura à produção»

1. Screening: questionário, sócio KYC, fontes de dados/tráfego, cheque de sank.
2. Contratos: MSA/DPA/SLA/OLA, comercial (CPA/RevShare/Hybrid/net-basis).
3. A emissão de chaves/cliente da OIDC, acesso ao banco de areia, conjunto de testes.
4. Testes de Conformance: esquemas de eventos, webhooks, limites, idempotidade.
5. Segurança review: assinatura de artefatos, SBOM/SLSA (se SDK/cliente).
6. Piloto/canário: volume limitado/geo, monitoramento reforçado.
7. Go-live: tradução de status, SLO-dashboard, plano de resposta.
8. QBR/MBR: revisões regulares do KPI, incidentes, cartões de trânsito.

4) Contratos de dados e esquema de eventos

Princípios: minimização, versões (semver), compatibilidade «vN/vN+1», assinaturas.

yaml event. common. v1:
id: uuid occurred_at_utc: timestamp source_partner_id: string trace_id: uuid type: enum        # e. g., "kyc. approved. v1"
payload: object signature: ed25519 version: "1. 0. x"

Diretórios e relatórios: JSON Schema/Avro, controle de campos obrigatórios, TTL/Retenschen, Legal Hold.
Estabilidade: alterações breaking somente através de novos tipos/versões com a janela deprecation.

5) Autenticação, autorização, segredos

OAuth2/OIDC: tokens curtos, PoP/DPoP sempre que possível.
mTLS para servidor servidor.
Webhooks assinados: Ed25519/HMAC; anti-replay ('X-Timestamp', janela 5 min).
PoLP/ABAC: caixas/atributos: «parceiro», «region», «datpra», «eng».
Rotação de chaves: bilateral, com janela de compatibilidade e registro de auditoria.

python def verify(req):
if abs(now()-req. h["X-Timestamp"])>300: return 401 if not sig_ok(req. body, req. h["X-Signature"], partner_pubkey): return 401 if seen(req. json["event_id"]): return 200 store(req. json); mark_seen(req. json["event_id"]); return 200

6) Idempotidade, limites, resistência

Idempotency-Key: `partner_id + external_id + op_type`.
Rate limiting/cotas: RPS, burst, «início quente», reduzindo os coeficientes de degradação.
Políticas Retry: expositor + jitter, deadup na recepção.
Pattern outbox/inbox: entrega garantida, dedução, auditoria.
Backpressure: filas, DLQ com retino separado.

7) Observabilidade e SLO

Метки: `partner`, `region`, `api_version`, `route`, `env`.
SLI: disponibilidade, p95/99 latency, erro-rate, delivery-within-window, recon-diff.
SLO & burn rate: por parceiro/nó; Alertas por excesso.
Traçados: «trace _ id» completa; sampleamento de caudas e erros (tail sampling).
Sintética: verificações externas de endpoint/assinaturas/TTL.

rego package partner. release deny["SLO at risk"] { input. slo_forecast. error_burn > 1. 0 }
deny["Missing schema tests"] { input. tests. schemas_passed == false }

8) Complaens e privacidade

Geo-pinning: Os domínios sensíveis não saem das regiões permitidas.
Minimização e pseudonimização PII: 'user _ pseudo _ id' em vez de PD direto.
Prazo de armazenamento: TTL/ILM; crypto-erasure por chave (para-parceiro/para-região).
Direitos do sujeito: roteiro DSAR para a origem, registro de execução.
Registros de acesso e auditoria: quem viu, quando, porquê; logs imutáveis.

9) Cálculos, atribuição e reconciação

Base de cálculo: net vs gross, taxas de câmbio, impostos, bônus.
Atribuição: janelas (click/view), prioridade de canal, dedução por 'event _ id/click _ id'.
Reconciação: relatórios bilaterais, permissividade, SLA encerramento de divergências (≤5 r.d.).

sql
SELECT a. event_id
FROM partner_report a
LEFT JOIN internal_events b ON a. event_id=b. event_id
WHERE a. date BETWEEN:from AND:to AND b. event_id IS NULL;

10) Versionização da API e gerenciamento de alterações

Semver: 'v1' - um ramo estável; breaking → 'v2' com suporte duplo de ≥90 dias.
Processo Deprecation: anúncio → bandeira no passaporte → sintético/alerta → desligamento.
SDK/conectores: assinatura de lançamentos, SBOM, compatibilidade, guias migratórios.

11) Rotação e federação (se vários parceiros do mesmo tipo)

SOR (Smart Order Routing): preço/qualidade/latência/complacência/reputação.
Fairness: limitação de participação, tie-break SLA/reputação.
Degradation: falback honesto, piora transparente (notificações/banners).

12) Playbooks incidentes

12. 1 «Direcionamento do webhook»

yaml detect: "schema_validation_error_rate>0. 5%"
steps:
- "auto-pause partner webhooks"
- "fallback to cached/default behavior"
- "notify partner; open war-room"
- "provide diff & test vectors; hotfix window 24h"
kpi: ["RTA<=1h","residual_errors<0. 1%"]

12. 2 «Fracasso do SLO em PSP/KYC»

1. Redistribuir por SOR →

2. Ativar graceful-degradation no fluxo de →

3. Aplicar limites/quotas →

4. Arranjar crédito SLA e pós-incidente.

12. 3 «Divergência de cálculo»

1. Freeze pagamentos por faixa de →

2. Eventos re-drive de outbox →

3. Ajuste/correção de →

4. Acção conjunta e descongelamento.

13) Marketing/portal de parceiros

Certificação de integração: folha de cheque, crachás de qualidade (Gold/Silver/Bronze).
Catálogo de conectores: pesquisa/filtros de mercado/tipo/versão da API.
Auto-SDK/speki: OpenAPI/AsyncAPI, exemplos, colecções Postman.
Self-service: chaves, webhooks, limites, revistas, quadros de teste.

14) Métricas de maturidade das integrações

Time-to-Integrate (TTI): mediana de dias até o prod.
Coverage: participação dos mercados/funções apoiados pelo parceiro.
SLO pass-rate: um mês por parceiro/região.
Recon-health: Taxa de fechamento de discrepância, residual £.
Segurança posture: taxa de rotação de chaves, SBOM coverage.
Costa/egress: $/req e $/GB por parceiro, eficiência SOR.

15) Anti-pattern

«Primeiro ligamos os padrões depois» → zoológico de integração.
Um padrão único para cada parceiro → uma explosão de dificuldade.
Apenas cookies sem S2S → perdas e disputas.
Não há idimpotência/limites → duplicação/tempestade de retrações.
PII em logs/webhooks → riscos regulatórios.
Uma «super integração» sem alternativas → risco de concentração.
Alterações na API sem a janela deprecation ou sintética → acidentes de venda.

16) Folha de cheque do arquiteto das integrações

1. O passaporte do parceiro está completo (contratos, regiões, versões, chaves, SLO)?
2. Os esquemas de eventos e relatórios são testados, há uma caixa de areia?
3. OAUTH/OIDC, assinatura de mandato de webhooks e anti-replay incluídos?
4. Idempotidade, limites, outbox/inbox e DLQ implementados?
5. Dashboards SLO/SLA, traçados, alertas burn-rate configurados?
6. A recordação e as janelas de cálculo/atribuição são formalizadas?
7. Geo-pinning/TTL/crypto-erasure e routagem DSAR no local?
8. Semver, processo de deprecação e duplo suporte de versões estão documentados?
9. Playbooks incidentes verificados (à deriva de circuitos, SLO-fracasso, recon-diff)?
10. Plano exit: desativação de chaves, exportação de dados, migração para segundo-fonte?

Conclusão

A integração dos parceiros é uma linha de montagem de produção: padrões → verificação → observabilidade → melhoria. Quando o passaporte do parceiro está cheio, os eventos e contratos são tipificados, a autenticação e as assinaturas são obrigatórias, o SLO é medido, os cálculos são controlados e as mudanças são controladas através de versões e gates - o ecossistema cresce de forma rápida e segura, e cada novo parceiro aumenta o valor da rede.