Rede aberta e integração externa

(Secção: Ecossistema e Rede)

1) Por que uma rede aberta

A rede aberta reduz os custos transacionais das integrações e acelera a inovação. Contratos normalizados, barras de areia e portais self-service transformam o ecossistema em uma «plataforma de desenvolvimento», onde os participantes rapidamente criam valor sem concordar com cada passo.

2) Princípios openness

Open by design: especificações públicas de API/Ivents, exemplos, SDK.
Segurança & private first: dados, assinaturas, localização PII minimamente necessários.
Backward/forward compatibilidade: políticas de versionização e migração.
Observabilidade by default: trace-id de passagem, logs estruturados, métricas.
Self-service: chaves, webhooks, quotas e relatórios - através do portal.
Costa-aware: limites de egress, cachê, ouros econômicos.

3) Contratos de integração

3. 1 API (RQ/RS)

Formato: REST/gRPC + especificação (OpenAPI/Protobuf).
Títulos obrigatórios: 'x-request-id', 'x-idempotency-key', 'traceparent'.
Erros: códigos determinados, dicas de retrações, referência 'status _ url' para asinhronca.

3. 2 Eventos (Pub/Sub)

Поля: `event_id`, `occurred_at`, `producer`, `subject_id`, `schema_version`, `region`, `tenant`.
As garantias são: at-least-once, particionamento por chave (user _ id/tenant _ id), retenção por replay.

3. 3 Webhooks

Os cabeçalhos são «assinatura», «timestamp», «nonce», «delivery-id».
As janelas anti-replay são TTL, as janelas descartáveis, a lista de «delivery-id» usada.
Comportamento: 2xx = recepção; Retraias exponenciais com jitter; Idepotência no receptor.

4) Segurança e confiança

Autenticação: OAuth2/OIDC para integrações de clientes mTLS para S2S.
Assinaturas: HMAC/Ed25519; catálogo centralizado de chaves, rotação e pinning.
Políticas de acesso: RBAC/ABAC, escopos «minimamente suficientes», tokens temporários.
Chave e segredos: KMS per-region, divisão de responsabilidades (M-of-N para operações críticas).
Auditoria: Registros invariáveis (WORM) + Cortes e Recibos (receipts).

5) Versionização e migração

SemVer para API e esquemas de eventos.
Estratégia: expand → migrate → contract (adicionando campos → transferindo consumidores → removendo o antigo).
Lançamentos breaking de calendário, pré-pré-GA e janelas GA, fidas de teste.
Máquinas de compatibilidade em CI; «cheque verde» para integrações certificadas.

6) Caixa de areia, SDK e DevEx

Um ambiente completo, com chaves de teste, ficturas, pagamentos mock, geradores de eventos.
SDK/CLI: integração rápida, geração de clientes por especificação, exemplos de copiar-colar.
Catálogo de contratos: pesquisa por domínios, versões, regiões; changelog e exemplos de payload.
Processamento automático: pacote de testes de assinaturas, idempotidade, esquemas; crachá de compatibilidade.

7) SLO/SLA, quotas e fair-use

SLO per-canal: p95/p99 latency, erro-rate, sucesso na entrega de eventos.
SLA para associados: janelas de destino de acessibilidade, crédito-notas/multas como código.
Quotas/limites: per-chave/tenante/região, parâmetros burst, prioridades por nível.
Rate-limits e proteção: circuito-breakers, backpressure, botão vermelho (kill-switch).
Roteamento de Costa-aware: Em tempo igual, um caminho mais econômico.

8) Observação e auditoria

Traceability: "trace _ id '/' span _ id 'em todos os canais (RPC, eventos, webhooks).
Métricas: latency p50/p95/p99, error-rate, fila, sucesso em dinheiro, egress/ingress.
Logi: estruturado, com 'tenant _ id', 'parceiro _ id', versão do contrato e região.
Recibos e revistas Merkle: entrega comprovada/inclusão; cruzamentos automáticos (diff).
Dashboards do parceiro, consumo, entregas estatais, quotas, incidentes, billing.

9) Complaens e privacidade

Data minimization: Os eventos trazem ID/prova, não um PII a mais.
Localização de dados: PII/findados - em «zonas de confiança» da região; lá fora, tokens/hachis.
Direito ao esquecimento: remoção de PII primário sem perda de provabilidade (os recibos permanecem).
Políticas como código: verificações de privacidade/segurança na CI que bloqueiam gates para lançamento.

10) Associados onboarding (fluxo de arbitragem)

1. Dê Diligence: segurança/complacência, alinhamento SLA/economia.
2. Fornecimento de chaves: caixas, quotas, disponibilidade temporária.
3. Integração na caixa de areia: exemplos de payload, processamento automático.
4. Piloto debaixo do ficheflag, tráfego limitado, guindastes e dashboards.
5. Lançamento GA: publicação no catálogo, termos SLA/billing.
6. Operação: monitoramento, relatórios, reviravoltas regulares; gerenciamento de versões/migrações.
7. EOL/cancelamento: Revogação de chaves, migração de tráfego, arquivamento de artefatos.

11) Marketplace Extensões

Formato: plugins/adaptadores/bots com vitrine, classificação e condições.
Modelo de renda: royalties/comissões de uso, descontos tier para grandes integradores.
Qualidade: certificação, crachá SLO, auto de compatibilidade em updates.
Segurança: assinatura de artefatos (SBOM), política de atualização e reversão.

12) Economia de interação

RevShare/CPA/CPL/Marketplace Comissões - transparentes e formalizadas em sistemas de relatórios.
Shared-savings: dividimos a economia (por exemplo, redução do egress/chargeback).
Orçamento-kap, limites para promoções/intentes, auto-downscale multiplicadores.
Dispute & escrow: Arbitragem automática de recibos assinados, esboço temporário.

13) Riscos e anti-pattern

Caos de versões, a falta de políticas migratórias está a destruir os consumidores.
Segurança fraca dos webhooks: sem assinatura/TTL/nce → frod/repetições.
Falta de Idempotação: tomação de pagamento/pagamento.
PII da reeleição, violação da privacidade e aumento dos custos da complacência.
Sem kill-switch ou quotas, um parceiro «sobrevive» a capacidade e os custos crescem.
Bling opaco, disputas e perda de confiança.

14) Métricas de sucesso da rede aberta

DevEx: TTFI (key-to-first-sucess), hora de certificação, NPS integradores.
Qualidade: p95/p99 por canais, entrega de webhooks bem-sucedida, replicação de liga.
Economia: custo de 1k eventos, egress/ingress por parceiro, programas de estímulo ROY.
Confiabilidade: MTTR, proporção de duplos processados idumpotentemente, proporção coberta de recibos de operações.
Efeitos de rede: número de integrações ativas, proporção de tráfego através de pneus normalizados.

15) Folha de cheque de implementação

• Publicar especificações de API/Ivents e diretório de versões.
• Incluir a caixa de areia, SDK/CLI e a impressão automática.
• Personalizar OAuth2/OIDC e mTLS, assinaturas de webhooks (HMAC/Ed25519), TTL/nonce.
• Digitar 'x-idempotency-key', 'traceparent', 'x-request-id' em todos os lugares.
• Iniciar revistas e recibos Merkle; dashboards de sócio e billing.
• Definir o SLO/SLA, quotas, rate-limits, roteamento de vale-aware e kill-switch.
• Aceitar a política de versionização (expand → migrate → contract) e o calendário de alterações breaking.
• Formalizar a economia (RevShare/CPA/Marketplace/Shared-savings) e as regras de disputa/escrow.
• Localizar PII/findados; em CI - cheques de privacidade/segurança.
• Realizar GameDays regulares de integração (tempestade de retais, perda de assinatura, diagramas de drible).

16) FAQ

Como é que se acelera?
Caixa de areia + SDK pronto, automação de contratos e status de endpoint.

Como evitar lançamentos ruins?
SemVer rigorosa, modo de compatibilidade e «expand → migrate → contract» com janelas pré-GA.

Precisamos de telemetria assinada?
Para negócios críticos, sim (recibos/assinaturas). Há correlação suficiente para as métricas.

O que fazer com «duplos»?
Chaves idumpotentes, dedução no receptor e processadores repeat-safe.

Resumo: A rede aberta é uma combinação de padrões e disciplina: especificações e grampos de areia, assinaturas e idempotação, quotas e políticas de custo-aware, observabilidade e auditoria comprovada, migração clara e economia justa. Seguindo esta folha de cheques, o ecossistema recebe integração rápida, qualidade previsível e crescimento sustentável.