Skip to main content
Sua conta é fixada (pinada) em uma versão de contrato da API. Isso significa que sua integração nunca muda de comportamento sem que você decida migrar — mesmo quando lançamos novas versões.

Como funciona

Cada conta possui uma versão de API associada, identificada por uma data (ex.: 2025-01-01). Toda requisição é respondida de acordo com a versão da sua conta, a menos que você explicite outra versão na própria requisição. Isso garante que:
  • Integrações existentes nunca quebram quando lançamos uma mudança de contrato (formato de resposta, novos campos obrigatórios, etc.)
  • Novas contas já nascem na versão mais recente
  • Você pode testar uma versão nova antes de migrar sua conta para ela

Sobrescrevendo a versão por requisição

Use o header X-Api-Version para testar uma versão diferente da qual sua conta está fixada, sem afetar as demais requisições:
Se o header não for enviado, a requisição usa a versão fixada na sua conta.
Enviar um valor de versão desconhecido retorna 400 Bad Request com o código de erro invalid_api_version, listando as versões válidas. Nenhuma requisição é processada com uma versão inexistente.

Formato da resposta por versão

Na versão 2025-01-01, cada endpoint responde no seu formato próprio (o corpo cru do recurso):
A partir da versão 2026-08-16, toda resposta é envelopada em um formato único, independente do endpoint:
O mesmo vale para erros — na versão 2026-08-16 eles também seguem esse envelope, com data: null e o detalhe do erro em errors:

Changelog de versões

Migrando sua conta para uma nova versão

A mudança da versão fixada na sua conta é feita hoje com o suporte da nossa equipe — ainda não há um botão de autoatendimento no painel administrativo para isso.
Recomendamos o seguinte fluxo antes de migrar:
  1. Teste a nova versão enviando o header X-Api-Version em requisições de sandbox
  2. Valide sua integração contra o novo formato de resposta
  3. Entre em contato com o suporte para migrar sua conta de forma definitiva

Suporte

Dúvidas sobre versionamento ou sobre qual versão sua conta está usando: