Pular para o conteúdo principal

Changelog da API

Histórico do contrato da API v1 da Régua de Cobrança: o que existe hoje e como mudanças futuras serão versionadas e comunicadas. Alterações de endpoints, campos e comportamento aparecem aqui em ordem cronológica inversa (mais recente primeiro).

A fonte canônica do contrato é sempre a especificação OpenAPI 3.1 (/openapi/openapi-v1-pt.yaml e variantes -en/-es). Este changelog resume o que muda entre versões; o YAML tem o detalhe campo a campo.

v1.0 — Julho de 2026​

Lançamento público da API v1. Baseline do contrato, com cobertura programática de toda a operação de cobrança que existe no dashboard:

  • Carteira — clientes/devedores (people), classificações e interações de contato.
  • Cobranças — criação, atualização, consulta e disparo manual de notificação (charges).
  • Régua de cobrança — réguas multicanal (collection_rules), modelos de mensagem (templates) e layouts de e-mail.
  • Acordos e disputas — acordos de pagamento (agreements) e disputas (disputes).
  • Negativação e protesto — registro em bureau (negativations) e cartório (protests).
  • Operação — tarefas (tasks), notificações (notifications), importações em lote e exportações.
  • Portal do devedor — geração e revogação de links.
  • Webhooks — endpoints assinados (HMAC-SHA256), entrega em fila com retry exponencial e trilha de entregas.

Convenções firmadas no baseline e cobertas pela garantia de compatibilidade abaixo:

  • Envelope de erro estável { message, code, details? } — trate sempre pelo code.
  • Respostas em camelCase, datas em ISO 8601 (UTC), valores monetários como string decimal.
  • Autenticação por chave de API com escopos dunning.dashboard.<recurso>.<ação> (ver Autenticação).
  • Idempotência via X-Idempotency-Key, paginação page/per_page e rate limiting por chave.

Política de versionamento​

A API é versionada no caminho (/api/v1). Enquanto a versão maior não mudar, o contrato só evolui de forma retrocompatível.

Mudanças retrocompatíveis (podem acontecer a qualquer momento, sem nova versão)​

Sua integração deve tolerá-las sem quebrar:

  • Novos endpoints e novos recursos.
  • Novos campos opcionais em respostas — ignore os que você não conhece (não faça strict parsing que rejeite campos extras).
  • Novos valores em enums e novos code de erro — trate valores desconhecidos com um fallback.
  • Novos parâmetros de query opcionais e novos headers de resposta.
  • Novos tipos de evento de webhook — assine apenas os que você trata e ignore o resto.

Mudanças que quebram (exigem nova versão maior, ex.: /api/v2)​

Nunca aplicadas silenciosamente à v1:

  • Remover ou renomear endpoints, campos ou code de erro.
  • Mudar o tipo ou o significado de um campo existente.
  • Tornar obrigatório um parâmetro antes opcional.
  • Endurecer regras de validação de forma que um request antes válido passe a falhar.

Como as mudanças são comunicadas​

  • Aditivas entram na especificação OpenAPI e são registradas neste changelog, com data.
  • Depreciações são anunciadas aqui e no changelog com antecedência, mantendo o comportamento antigo funcionando durante o período de transição antes de qualquer remoção (que só ocorre em uma nova versão maior).
  • Recomendamos acompanhar esta página e assinar os webhooks para reagir a novos eventos.