Versionamento e changelog

A versão da API é a data da especificação publicada (info.version). Versão atual: 2026-10-14.

Política de versões

• Compatível (sem aviso de versão): novos endpoints, novos campos opcionais, novos campos em respostas, novos valores de enumeração, novos tipos de evento de webhook. Seu código deve tolerar isso.
• Incompatível: remover/renomear campo ou rota, mudar tipo, tornar um campo opcional em obrigatório. Será registrado aqui como breaking com antecedência e, sempre que possível, com período de convivência (como loquidAmount → netAmount).
• Os webhooks trazem api_version; a especificação é servida em /developers/openapi.yaml.

Adquirente PayGate interno

Novo adquirente PIX (cobrança e saque), configurado em Admin → Adquirentes. Não altera a API pública nem a especificação OpenAPI. Detalhes em Adquirentes e PayGate.

2026-10-14 — versão inicial documentada

Novo

• Idempotency-Key em POST de criação (obrigatório em /api/pixout/create); cabeçalho de resposta Idempotent-Replayed.
• Webhooks de saída assinados (HMAC-SHA256, SharkPay-Signature), com fila transacional, 8 tentativas e diagnóstico: /api/webhook, /secret/rotate, /test, /deliveries.
• GET /api/checkout/{tx_ref} para confirmar pagamentos do checkout hospedado.
• Especificação OpenAPI 3.1, coleção Postman, /llms.txt e esta documentação.
• Limites de requisição com 429 e Retry-After.

Segurança e corretude

• Respostas de erro padronizadas; falhas inesperadas não expõem detalhes internos (500 internal_error).
• Isolamento por conta em todos os recursos (id de outra conta → 404).
• Saque Pix com reserva atômica de saldo e estorno automático se o banco recusar.
• Cálculo de total em aritmética decimal exata e validação de faixas (valor > 0, quantidade, percentuais 0–100).
• Chave secreta e segredo do webhook criptografados em repouso.
• Webhooks com proteção SSRF e janela anti-replay.

Obsoleto (mantido por compatibilidade)

• Withdraw.loquidAmount → use netAmount.
• Withdraw.entoend → use endToEndId.

Como se manter atualizado

1. Reimporte o OpenAPI e compare com a versão que você usou (diff de duas versões do YAML mostra tudo).
2. Rode seus testes de contrato e de webhook.
3. Só então promova a atualização.