Versões e depreciação

Esta política vale para a API de integração do financeiro (/api/partner/v1/finance) e segue a do canal.

Versão

• A versão fica na URL: /api/partner/v1. Uma versão publicada não muda de forma incompatível.
• Não é quebra (pode acontecer a qualquer momento, com registro no changelog): rota nova, campo novo opcional na requisição, campo novo na resposta, novo valor de erro em rota nova, novo escopo.
• É quebra (só em versão nova, /v2): remover ou renomear rota ou campo, mudar tipo ou unidade de um campo, tornar obrigatório o que era opcional, mudar o significado de um código de erro, exigir escopo diferente em rota existente.
• Integrações devem ignorar campos que não conhecem.

Depreciação

1. A rota ou o campo a retirar é anunciado no changelog do portal com, no mínimo, 180 dias de antecedência.
2. Durante esse prazo, as respostas da rota trazem os cabeçalhos Deprecation (data do anúncio) e Sunset (data da retirada), conforme a RFC 8594, e um Link para a rota substituta quando houver.
3. Depois da data de Sunset, a rota responde 410 Gone.
4. Correção de segurança pode encurtar o prazo; nesse caso o aviso é direto à instituição, pelo contato técnico cadastrado.

Convivência de versões

Quando existir /v2, a /v1 continua no ar por pelo menos 12 meses depois da publicação da /v2.

Onde está a especificação

GET /api/openapi devolve a especificação OpenAPI 3.0 gerada do próprio roteador, então ela não diverge do que está no ar. GET /api/swaggerui é a interface navegável.

Estado de hoje

A /v1 do financeiro foi publicada em setembro de 2026. Nenhuma rota está em depreciação. Os cabeçalhos Deprecation e Sunset ainda não são emitidos por nenhuma rota, porque nenhuma foi depreciada.

As mudanças publicadas estão no changelog do financeiro.