Versionamento e mudanças
O que pode mudar dentro da v1 sem aviso, o que exige uma nova versão e o histórico da API.
Em resumo
- A versão está no caminho:
/api/v1. - Dentro da v1 podem aparecer campos novos, recursos novos e valores novos de situação — o seu sistema deve tolerá-los.
- Renomear ou remover um campo, ou mudar o seu tipo, só acontece numa nova versão, com aviso e período de convivência.
O que não quebra a v1
- Um campo novo numa resposta.
- Um recurso ou filtro novo.
- Um valor novo num campo de situação (por exemplo, uma nova
statusde contrato). - Um código de erro novo, com o status HTTP de sempre.
Por isso: ignore campos que não conhece e trate valores desconhecidos de situação como "outro" — sem falhar.
O que exige uma nova versão
- Remover ou renomear um campo.
- Mudar o tipo ou o significado de um campo.
- Mudar o comportamento de paginação ou de autenticação.
Quando houver uma v2, a v1 continua no ar por um período anunciado, e as respostas da v1 passam a trazer os cabeçalhos Deprecation e Sunset.
Histórico
| Data | Mudança |
|---|---|
| 2026-10 | Primeira versão: identidade da chave, fornecedores, dados bancários, contratos, documentos de faturamento (com arquivo), contas a pagar (com a situação de pagamento) e pagamentos. Somente leitura. |