Compatibility

Política de versionamento

/v1 é uma versão estável — uma vez publicada, ela nunca muda de forma incompatível. Uma mudança breaking sempre resulta numa versão nova (/v2), nunca numa alteração silenciosa de /v1.

O que conta como breaking

• Remover um campo de uma resposta.
• Renomear um campo (de request ou resposta).
• Mudar o tipo de um campo existente (ex.: string → number).
• Tornar obrigatório um campo que antes era opcional.
• Remover ou renomear um endpoint.
• Mudar o significado de um status/error.code existente.

O que não conta como breaking

• Adicionar um campo novo (opcional) numa resposta.
• Adicionar um endpoint novo.
• Adicionar um status/error.code novo (seu código deve tratar valores desconhecidos com um default razoável, nunca assumir uma lista fechada).
• Adicionar um método de pagamento novo.
• Corrigir um bug em que o comportamento documentado e o comportamento real divergiam (o documentado sempre foi o contrato — se o código estava errado, corrigir não é breaking).

Como acompanhar mudanças

Ver CHANGELOG.md na API — formato Keep a Changelog, uma entrada por versão publicada.

Deprecação

Quando um campo/endpoint for descontinuado (sem quebrar /v1 — ele continua funcionando), o aviso aparece primeiro aqui na documentação e no changelog, com uma janela de aviso antes de qualquer remoção efetiva (que só aconteceria numa hipotética /v2).