APIs & Eventos
Contratos técnicos, semântica de eventos e padrões de robustez.
explanation • updated 2026-03-15
O que esta secção resolve
Define como desenhar integrações previsíveis num modelo webhook-first, reduzindo inconsistências entre estados temporários e estado final.
Princípios de contrato
- Pedidos mutáveis devem usar idempotência.
- Eventos são a fonte final de confirmação operacional.
- Versionamento e naming devem ser explícitos por domínio.
Percurso recomendado
11) Ler contratos base
Começa em API Essentials.22) Definir semântica de eventos
Aplica Convenções de eventos.33) Fechar segurança de execução
Valida Autenticação e idempotência.44) Consolidar racional arquitetural
Documenta trade-offs em Arquitetura webhook-first.
Critérios de qualidade de integração
| Critério | Meta operacional |
|---|---|
| Duplicados processados | 0 efeitos laterais duplicados |
| Retries com sucesso | 100% com limite e backoff definido |
| Eventos sem schema | 0 em produção |
| Erros 5xx persistentes | Sem backlog fora da janela de SLO |
Começa por aqui
Fundamentos da API
Headers, autenticação e padrões de resposta.
Convenções de eventos
Nomes, idempotência e versionamento.
Arquitetura webhook-first
Porque o modelo é event-driven.
Autenticação e idempotência
Scopes, retries e garantias de execução única.
API Reference
Mapa dos grupos de endpoints Beacon.
Billing API
Checkout, subscrições e portal.
Stripe & Beacon Connect API
OAuth read_only, Beacon Connect e reconciliação multi-fonte.
Webhooks API
Ingestão, idempotência e replay.
Fiscal API
Documentos, reconciliação e setup-state.
OpenAPI Spec
Spec parcial para evolução para Scalar/Redoc.