Versionamento

Para: Dev — Conferido em 2026-10-18.

A API e os eventos do Dracma evoluem só por acréscimo dentro da v1. Uma mudança incompatível só existe como /v2. Esta página define o que é compatível, o que o seu código precisa tolerar e onde acompanhar as mudanças.

O que é

A versão maior vai no caminho: toda rota pública começa com /v1. Não há cabeçalho de versão nem negociação por Accept. O contrato (OpenAPI) tem uma versão própria, hoje 1.1.0, que sobe a cada acréscimo.

Item Regra
/v1 Só recebe acréscimos. Nada que funciona hoje muda de significado.
/v2 Reservada para mudança incompatível. Não existe hoje.
Versão do contrato (1.x.y) x sobe com funcionalidade nova e aditiva; y, com esclarecimento ou campo aditivo pequeno.
Eventos de webhook Mesma regra da API. O type público do evento não leva sufixo de versão.

Não disponível

O Dracma não envia cabeçalhos Deprecation ou Sunset nem um cabeçalho de versão nas respostas. Você acompanha as mudanças pelo Changelog e pelo documento OpenAPI.

Quando usar

Consulte esta página para decidir se uma mudança que você viu no Dracma é esperada, ao escrever o leitor de respostas e de webhooks, e ao planejar a atualização do conector quando sair uma versão nova do contrato.

Como funciona

O que é compatível (acontece dentro da v1)

Qualquer um destes itens pode aparecer a qualquer momento, sem aviso prévio e sem mudar o número 1:

  • campo novo em qualquer objeto de resposta, de evento ou de webhook;
  • valor novo em enumeração aberta: status de depósito e saque, method, rail, kind de item de reconciliação, type de evento, reason de validação, code de erro, reason_code de devolução;
  • rota nova ou parâmetro opcional novo em rota existente;
  • evento novo no catálogo;
  • campo que hoje vem null ou vazio passar a vir preenchido;
  • erro de validação mais claro (mais campos em errors[]).

O que é incompatível (só em /v2)

  • remover ou renomear campo, rota, evento ou valor existente;
  • mudar o tipo de um campo (de string para número, por exemplo);
  • mudar o significado de um estado, de um evento ou de um code;
  • tornar obrigatório um campo que era opcional, ou apertar a validação de um campo que já era aceito;
  • mudar o algoritmo de assinatura ou o formato do pedido canônico.
flowchart TD A[Mudança proposta] --> B{Quebra algum conector que lê a v1 corretamente?} B -->|não: só acrescenta| C[Fica na v1 e entra no Changelog] B -->|sim| D[Só como /v2, lado a lado com a v1]

O seu lado: leitor tolerante

A promessa de "só acréscimo" vale se o seu código não quebra com acréscimo. Faça assim:

  1. Ignore campo desconhecido em qualquer JSON de resposta e de webhook. Não use desserialização estrita que falha com campo extra.
  2. Trate valor desconhecido como não terminal. Um status ou kind que você não conhece não move dinheiro no seu livro: grave o objeto e confira depois pelo fetch-back (GET /deposits/{id} ou GET /withdrawals/{id}).
  3. Evento de type desconhecido: responda 200 ao webhook, guarde e não mova dinheiro (Receptor de webhooks).
  4. code desconhecido: decida pela classe HTTP e por retryable (Erros).
  5. Não dependa da ordem das chaves de um objeto JSON nem de campos opcionais estarem presentes.
  6. Não derive nada de um ID. Os IDs são opacos (Convenções HTTP).

Eventos de webhook

O campo type do evento é público e não tem sufixo de versão (deposit.paid, não deposit.paid.v2). A política é a mesma da API:

  • mudança aditiva (campo novo no data.object, evento novo): mesma versão. O seu receptor ignora o que não conhece;
  • mudança incompatível: só junto de uma /v2, com tipos e envelope próprios, anunciada no Changelog;
  • assinatura: o formato t=…,v1=… do cabeçalho Dracma-Signature é parte da versão. O receptor deve ignorar partes do cabeçalho que não conhece e aceitar se qualquer v1 conferir, como na rotação de segredo (Requisição e assinatura).

Para o catálogo atual de eventos veja Catálogo de eventos.

Como acompanhar mudanças

Onde O que mostra
Changelog Mudanças de comportamento visíveis a quem integra, com data
OpenAPI O documento do contrato, versionado; compare com a cópia que você usa na CI
Divergências conhecidas Onde o documento OpenAPI e o comportamento da API ainda diferem
Rotas e campos reservados O que o contrato já declara mas a API ainda não preenche

O documento OpenAPI traz ETag: se você o baixa periodicamente, mande If-None-Match e receba 304 quando não mudou. Gere um diff do arquivo na CI do conector e trate qualquer mudança como motivo para ler o Changelog.

Depreciação

Dentro da v1 nada é removido. Se um dia uma rota, um campo ou um estado precisar sair, ele sai com a /v2, e a data é combinada com cada integrador antes de qualquer desligamento, pelo canal informado no onboarding.

Não disponível

O Dracma não publica um prazo mínimo fixo de aviso de depreciação. O prazo é combinado por contrato com cada integrador.

Exemplos

Exemplos hipotéticos, só para treinar a classificação:

Mudança Compatível? Por quê
Um campo que vinha null no depósito passa a vir preenchido Sim Campo existente ganha valor
O saque ganha um estado novo Sim Valor novo de enumeração aberta; trate como não terminal
Um evento novo entra no catálogo Sim O receptor responde 200 e guarda
amount.amount passa a aceitar decimais Não Muda o tipo e o significado de Money
POST /deposits passa a exigir player.email para todos Não Torna obrigatório o que era opcional
code rate_limited troca de 429 para 503 Não Muda o significado de um código

Erros e casos de borda

  • Estrito no que você envia, tolerante no que você lê. A API recusa campo desconhecido no seu corpo (unknown_field), mas o seu leitor deve ignorar campo desconhecido na resposta dela. Mandar um campo "novo" que a documentação ainda não lista dá 400: não adivinhe campos.
  • O OpenAPI pode listar mais do que a API faz. Campos e rotas do contrato 1.1.0 (câmbio, recebimentos, recall, trilhos bancários) estão declarados e ainda não são preenchidos: veja Rotas e campos reservados.
  • Correção de comportamento não é versão nova. Quando a API passa a se comportar como o contrato já descrevia (um erro que era 500 e vira 400, por exemplo), isso é correção e aparece no Changelog, sem mudar o número da versão.
  • Mudança de configuração da sua operação (um método novo habilitado, uma regra mais apertada) não é mudança de versão: consulte GET /currencies e GET /rules.

Veja também