Versionamento

A API pública da Allya Payments vive sob o prefixo /v1. Esta página descreve o que esse versionamento significa, o que muda sem aviso prévio (e por quê é seguro) e o que considerar quando uma versão nova for lançada.

Versão atual

/v1

Todas as rotas estáveis usam esse prefixo: POST /v1/payments, POST /v1/subscriptions, GET /v1/health, etc. Quando você ler ou ouvir "API da Allya", subentenda /v1.

A versão é parte do path (não header Accept nem query), por simplicidade e cacheabilidade. Roteamento interno (next.config.mjs) reescreve /v1/* para /api/v1/*: esse detalhe é irrelevante para o cliente.

Política de breaking changes

A Allya não introduz breaking changes em /v1 sem antes ter uma /v2 disponível em paralelo. Quando /v2 existir, ambas conviverão por pelo menos 6 meses antes de /v1 ser desativada.

Durante esse período:

• O changelog público (ai-changelog.md no repositório, futuramente uma página dedicada) anunciará a depreciação.
• /v1 continuará respondendo, mas pode receber um header Deprecation: true e Sunset: <data>.
• Cada endpoint deprecated traz orientação de migração.

O que NÃO é breaking change

Para evitar versão a cada melhoria, considere compatível (não-breaking) qualquer um destes:

• Novo campo opcional no request: você ignora, comportamento default igual ao de antes.
• Novo campo no response: clientes bem comportados ignoram campos desconhecidos.
• Novo valor em enum que já tinha "default ignored": ex.: novo status normalizado de pagamento. A regra é: novos status só aparecem em casos novos; status já estabelecidos não mudam significado.
• Novo endpoint: POST /v1/subscriptions foi adicionado depois de POST /v1/payments sem virar /v2.
• Novo evento de webhook: subscription.past_due foi adicionado em compatível. Endpoints filtram por allowlist (enabledEvents) ou ignoram desconhecidos.
• Novo código de erro mais específico dentro de uma família já documentada (ex.: detalhamento de invalid_input).
• Mensagem de erro mais clara: message é texto livre, não use em comparação programática.

O que É breaking change

Estes mudam o contrato e exigem /v2:

• Remover campo do response que era preenchido por garantia.
• Mudar tipo de um campo (number → string, etc.).
• Mudar default (ex.: se cancelAtPeriodEnd deixar de ser false por default).
• Remover endpoint ou rota.
• Mudar formato de assinatura de webhook (HMAC-SHA256 → outro).
• Mudar esquema do payload de webhook outbound (mover paymentId para outra estrutura).
• Mudar significado de um status existente.

Se acontecer algo dessa lista sem /v2, é bug: abra issue.

Como saber que algo mudou

Mudanças relevantes são anunciadas no changelog público antes de virar default. Acompanhe:

• O changelog da Allya, publicado periodicamente.
• Avisos no painel quando uma mudança de contrato exigir ajuste no seu cliente.
• Email para o contato cadastrado em mudanças com prazo de migração.

Compatibilidade com webhooks já enviados

Webhooks já entregues mantêm o payload da época da entrega. Se o esquema mudar entre versões, retentativas de entrega (quando houver retry avançado) continuarão com o payload original. Não há "rewrite" retroativo.

Endpoints do cliente devem ser tolerantes: ignorar campos extras desconhecidos, não falhar em valores de enum novos, e sempre validar X-Allya-Signature antes de qualquer parsing.

Roadmap

• Página de changelog público navegável (hoje vive em docs/ai-changelog.md apenas).
• Header Allya-Version na resposta para confirmar versão da instância.
• Endpoint /v1/version retornando versão do build, hash do commit, e versão do schema do banco.

Veja também

• Webhooks: como construir handler tolerante.
• Erros: política de códigos de erro.