Versionamento da API

A A55 usa versionamento por URL com um contrato estável de compatibilidade retroativa. A versão atual é v1 e todos os endpoints são servidos em:

https://core-manager.a55.tech/api/v1/

---

Estratégia de versionamento

Aspecto	Política
Esquema	Prefixo no caminho da URL (/api/v1/, /api/v2/)
Versão atual	v1
Estabilidade	Estável para produção — sem breaking changes dentro de uma versão major
Aviso de depreciação	Mínimo de 6 meses antes do encerramento de uma versão major
Período de encerramento	12 meses de suporte a duas versões durante a migração

O que conta como breaking change

Essas alterações acionam uma nova versão major:

Breaking change	Exemplo
Remover um campo de uma resposta	Remover usd_currency da resposta de cobrança
Renomear um campo obrigatório de requisição	payer_name → cardholder_name
Alterar o tipo de um campo	installment_count de integer para string
Remover um endpoint	Remover POST /charge/
Alterar o esquema de autenticação	Bearer token → API key
Alterar a estrutura de resposta de erro	message: string → message: array

O que NÃO é breaking change

Essas alterações ocorrem dentro da versão atual sem aviso prévio:

Alteração não-breaking	Exemplo
Adicionar novos campos opcionais na requisição	Novo campo metadata em criar cobrança
Adicionar novos campos nas respostas	Novo provider_reference na resposta de cobrança
Adicionar novos endpoints	POST /api/v1/bank/wallet/checkout/
Adicionar novos valores de enum	Novo type_charge: "googlepay"
Adicionar novos códigos de status HTTP	Nova resposta 429 de limite de requisições
Melhorar descrições de erro	Mensagens de erro mais específicas
Melhorias de performance	Tempos de resposta mais rápidos

Sempre trate campos desconhecidos

Sua integração deve ignorar campos desconhecidos nas respostas da API. A A55 pode adicionar novos campos de resposta a qualquer momento como uma alteração não-breaking. Use parsing JSON permissivo e evite validação estrita de schema nas respostas.

---

URLs dos ambientes

Ambiente	URL base	Propósito
Produção	https://core-manager.a55.tech/api/v1	Transações reais
Sandbox	https://sandbox.api.a55.tech/api/v1	Testes e desenvolvimento

Use variáveis de ambiente para alternar entre ambientes:

export A55_API_URL="https://sandbox.api.a55.tech"   # Development
export A55_API_URL="https://core-manager.a55.tech"   # Production
export A55_ACCESS_TOKEN="your-token-here"

---

Processo de depreciação

Quando uma nova versão major é lançada:

1. Anúncio — Post no blog, notificação por e-mail e banner no dashboard 6+ meses antes do encerramento.
2. Suporte duplo — Ambas as versões rodam em paralelo por 12 meses. Endpoints v1 retornam um header Deprecation.
3. Guia de migração — Um guia detalhado de migração campo a campo é publicado.
4. Encerramento — Após a data de encerramento, a versão antiga retorna 410 Gone com um link de migração.

Headers de depreciação

Quando uma versão ou endpoint é depreciado, as respostas incluem:

Deprecation: true
Sunset: Sat, 01 Mar 2027 00:00:00 GMT
Link: <https://docs.a55.tech/migration/v1-to-v2>; rel="successor-version"

---

Versionamento do SDK

Os SDKs da A55 seguem o versionamento semântico:

SDK	Pacote	Versionamento
JavaScript	@a55/a55pay-sdk	MAJOR.MINOR.PATCH
Python	a55-sdk	MAJOR.MINOR.PATCH

As versões major do SDK são alinhadas com as versões major da API. Uma nova API v2 será distribuída com o SDK 2.x.

---

Changelog →Veja o que mudou em cada release da API.Autenticação →Configure Bearer tokens para acesso à API.Criar cobrança →Comece a integrar com a versão atual da API.