Changelog¶

Para: Dev · Fin · Adm — Conferido em 2026-10-18.

O que mudou no Dracma e é visível para quem integra ou administra uma operação: contrato, comportamento da API, webhooks, painel e acesso. As entradas vão da mais nova para a mais antiga, a partir de 2026-09-27 (a data da edição anterior deste guia). Mudanças internas que não alteram o que você vê não estão aqui.

O que é¶

Um registro por data, com a área, o efeito para você e o que fazer. Todas as datas estão em UTC e são a data em que a mudança passou a valer no código. Quando uma mudança vale só em operações Teste ou só em operações Real, a entrada diz.

A política de compatibilidade está em Versionamento: dentro da v1 só entram acréscimos, e correção de comportamento não muda o número da versão.

Quando usar¶

• Ao atualizar o conector ou ao investigar um comportamento que mudou ("isso respondia 401, agora responde 429").
• Ao revisar o guia: todo o conteúdo foi reconferido em 2026-10-18 contra o código de cada serviço. A edição anterior (2026-09-27) está defasada em pontos que esta página lista: devolução real de saque, lista de IPs, autenticação sem oráculo, limites por jogador, painel completo e e-mail real no hml.
• Ao preparar o corte para a operação Real: percorra as entradas e confirme que o seu conector já trata cada uma.

Como funciona¶

Versões do contrato¶

Versão	O que trouxe
1.0	Base: depósitos e saques PIX em BRL, autenticação HMAC, idempotência, webhooks assinados, reconciliação, sandbox.
1.0.1	review_reasons no depósito (motivos de under_review) e o objeto já existente em existing no 409 duplicate_external_id.
1.1.0	Versão vigente. Declara wire, SWIFT, câmbio e recebimentos bancários, campos novos nos objetos (fee, fees, rail, fx, compliance, return, recall e outros) e a regra do leitor tolerante. A API implementa só o recorte PIX; o resto é reservado (Rotas e campos reservados).

2026-10-21¶

Área	Mudança	O que fazer
API	IP liberado e URL de webhook são opcionais e altamente recomendados. Operação sem IP liberado aceita qualquer origem com a chave válida. Com IP liberado, a chamada de outra origem recebe 403 ip_not_allowed, sem listar os IPs. A API passa a registrar por 30 dias os IPs de origem das chamadas autenticadas.	Em Real, cadastre os IPs de saída fixos do conector. Atrás de proxy ou NAT, use o IP público de saída.
Painel	O painel avisa enquanto faltar IP ou webhook (com Lembrar depois por 7 dias, por pessoa) e, após as primeiras chamadas, sugere Bloquear para estes IPs: aplica na hora, depois da sua confirmação e de uma confirmação recente de identidade (só aperta o acesso, com IPs já vistos; sem aprovação de outra pessoa e sem espera). Nada é aplicado sozinho, e remover os IPs desfaz.	Veja IPs do conector.

2026-10-19¶

Área	Mudança	O que fazer
Acesso	Convidar alguém para a equipe passa a ser por convite com aceite. O pedido de convite (com a aprovação que já existia) envia um e-mail com link de uso único e 72 h de validade. O acesso só vale depois que a pessoa aceita com dois fatores, e só na operação do convite. A tela Usuários e papéis ganhou "Aguardando aceite", com reenvio e revogação.	Avise a equipe de que o convite não dá acesso na hora. Veja Equipe e papéis.
Acesso	Adicionar um segundo e-mail à conta (Conta, e-mails). Um endereço já verificado em outra conta responde como um livre, sem enviar código.	Veja Conta, login e dispositivos.

2026-10-18¶

Área	Mudança	O que fazer
API	A lista de IPs da operação deixa de ser aplicada às chamadas. Nenhuma chamada recebe mais 403 ip_not_allowed. A tela de IPs do painel continua registrando a lista.	Não use IP como controle de acesso. A autenticação por assinatura e os escopos seguem valendo (Autenticação HMAC).
Guia	O guia foi reescrito e reconferido contra o código, e passa a ser publicado em docs.dracma.cfd, com o documento OpenAPI (OpenAPI). Autenticação, erros, idempotência, paginação e limites ganharam páginas próprias.	Atualize favoritos e links.

2026-10-15¶

Área	Mudança	O que fazer
Painel	Tenants e operações são criados pelo painel, pela equipe do Dracma, com acompanhamento do estado da operação: Configurando, Ativa ou Suspensa (Tenants e operações).	Nada. O primeiro acesso do administrador do integrador é por convite (Do zero ao go-live).

2026-10-12¶

Área	Mudança	O que fazer
Painel	Painel completo. Chaves de API e IPs, usuários e papéis, webhooks (configuração, entregas, DLQ), regras e listas, relatórios com exportação CSV e JSON, alertas, auditoria com trilha verificável, reconciliação e saldos e caixa, cobrança de teste e o pedido de informação ao operador no detalhe do saque.	Veja O painel.
Painel	Aprovação por 1 outra pessoa. Ações que pediam 2 aprovações (dar papel que aprova dinheiro, afrouxar regra, remover entrada de lista, ativar VIP, exportar com dados pessoais) passam a pedir 1, sempre de outra pessoa; quem propõe nunca vota. A mesma pessoa pode administrar o tenant e aprovar dinheiro. Saque marcado para dupla aprovação continua exigindo 2 revisores distintos.	Revise os papéis da sua equipe (Equipe e papéis).
Painel	Chave de API nova exige aprovação de outra pessoa e espera de 24 h; o segredo é revelado uma vez, em janela de 24 h, ao proponente. Chave não revelada nesse prazo é revogada.	Chaves de API.
Painel	Cobrança de teste. Cria um depósito PIX de teste pela tela. Em operação Real exige confirmação explícita, porque o dinheiro é real.	Cobrança de teste.
Operação Real no hml	No ambiente de homologação, a operação Real passa a usar o PSP de verdade e move dinheiro real. Operações Teste continuam no simulador.	Use a chave key_test_ para ensaios; só use key_live_ no hml com valor pequeno e intencional (Ambientes, tipos de operação e hosts).
Caixa e reconciliação	Depósito returned deixa de debitar o caixa da operação por um dinheiro que nunca entrou. O item de devolução na reconciliação usa o valor efetivamente recebido.	Confira a sua conciliação (Reconciliar com o seu livro).
Webhooks	Configuração pelo painel com filtro por tipo de evento e teste a seco; resolução e reentrega de itens na DLQ; alertas do painel por e-mail.	Webhooks no painel.

2026-10-11¶

Área	Mudança	O que fazer
E-mail	No hml, os e-mails chegam de verdade (convites, alertas, códigos de login). Só endereços de teste (.test, .invalid, .example) continuam suprimidos.	Use um endereço real e seu para o administrador; nunca use endereço de terceiros em ensaios.
Acesso	Login e cadastro em etapas: e-mail, primeiro método e segundo método, um por vez. O link do convite aponta para a tela de cadastro correta.	Conta, login e dispositivos.

2026-10-10¶

Área	Mudança	O que fazer
Saques	Devolução PIX de saque pago. O saque paid pode virar returned quando o banco devolve o PIX, com o objeto return (reason_code ou unspecified, returned_amount, que pode ser parcial, e returned_at). O caixa da operação é creditado pelo valor devolvido.	Trate returned no seu livro: credite ao jogador (ou à fila de exceções) só o returned_amount (Ciclo do saque).
Acesso	Autenticação forte. Passkey, aplicativo de código (TOTP), código por e-mail, confirmação extra (step-up) em ações sensíveis, códigos de recuperação e vários dispositivos. Sessão de 7 dias deslizantes; sair encerra a sessão no servidor.	Conta, login e dispositivos.
Painel	Primeiras telas: operações e saldos, filas de saques e de depósitos em revisão com voto, transações e auditoria.	O painel.
E-mail	E-mails do Dracma ao operador: alerta de entregas de webhook que esgotaram as tentativas, saque em revisão e resumo diário.	Cadastre os endereços de alerta no webhook (Alertas e e-mails).
Sandbox	Na API de operação Teste do hml, as rotas /v1/sandbox/* passam a estar disponíveis. Em produção e em operação Real continuam sendo 404.	Sandbox.
Segurança	Correção: um Dracma-Timestamp absurdamente distante no futuro podia ser aceito por estouro de inteiro; agora é recusado como qualquer valor fora da janela.	Nada.

2026-10-02¶

Área	Mudança	O que fazer
API	Rotas do contrato 1.1.0 no recorte PIX. GET /fx/quotes/{id} e GET /receipts/{id} respondem 404; GET /receipts devolve página vazia; POST /withdrawals/{id}/recall responde 409 invalid_state_transition; POST /sandbox/bank-transfers/incoming responde 400 rail_not_enabled. Nada move dinheiro.	Nada. Veja Rotas e campos reservados.
Autenticação	Sem oráculo de existência de chave. Chave inexistente e assinatura errada voltam a mesma resposta, 401 invalid_signature. 401 unknown_key por chave revogada e 403 só aparecem depois de a assinatura de uma chave real conferir.	Em diagnóstico, parta de invalid_signature (Autenticação HMAC).
Autenticação	Dracma-Timestamp só na forma canônica: só dígitos, sem sinal, sem espaço, sem zero à esquerda. Valores como +1790000000 ou 01790000000 voltam 401 timestamp_out_of_window. O t= do webhook também é canônico.	Gere o timestamp com floor(agora / 1000) e formate como inteiro simples.
API	Validação de JSON mais estrita. Chave duplicada variando maiúsculas e minúsculas é 400 duplicate_key; JSON com delimitador trocado deixa de dar 500 e vira 400 validation_failed.	Não envie chaves repetidas.
API	Toda resposta /v1 traz traceparent; o Dracma-Trace-Id é o ID do trace, e o seu traceparent de entrada é continuado.	Convenções HTTP.

2026-09-28¶

Área	Mudança	O que fazer
Limites	Saques por jogador: 3 por hora, além dos 10 depósitos por hora. Estouro: 429 rate_limited (Limites e quotas).	Mostre "tente mais tarde" ao jogador; não faça laço.
Erros	500 internal_error passa a vir com retryable: true.	Repita com a mesma Idempotency-Key.
Chaves	A API guarda a chave resolvida por até 30 s: a revogação de uma chave passa a valer em até 60 s em todos os nós.	Revogue e confirme o "último uso" no painel.
Sandbox	Estorno e chargeback de depósito por ação de sandbox (refund, chargeback). Simulador de saque: valor terminado em 77 centavos (por exemplo 2077) fica aceito e pendente até uma ação de sandbox.	Receitas.
Contrato	GET /openapi.yaml servido pela API, com ETag.	OpenAPI.
Webhooks	Jitter nas retentativas. O atraso de cada retentativa é o intervalo do cronograma mais 0% a 10%; nenhuma tentativa sai antes do intervalo base.	Não dependa do horário exato da retentativa (Retentativas e DLQ).

Linha de base (2026-09-27)¶

Tudo o que estava descrito na edição anterior deste guia continua valendo, em especial: PIX em BRL para depósito e saque; autenticação HMAC com janela de ±300 s; idempotência de 30 dias; limites de 5 req/s em listagens, 10 depósitos por hora por jogador e 20 falhas de assinatura por minuto por IP; POST /rules/change-requests; exigências de depósito por operação em GET /currencies; POST /fx/quotes respondendo 422 fx_not_enabled; validação de UTF-8 do corpo.

Exemplos¶

Como ler uma entrada. A de 2026-10-02 sobre timestamp:

1. Sintoma possível: depois de uma atualização de biblioteca, o conector passou a receber 401 timestamp_out_of_window com o relógio certo.
2. Causa: o timestamp saía com +, com espaço ou com zero à esquerda (por exemplo 01790000000).
3. Correção: str(int(agora_em_segundos)), sem formatação.

E a de 2026-10-10 sobre returned: se o seu livro só conhecia paid, o jogador que teve o PIX devolvido ficaria com o saque "pago" para sempre. Passe a tratar returned e o return.returned_amount.

Erros e casos de borda¶

• hml e produção. Esta página descreve o comportamento do código. Um ambiente só passa a se comportar assim depois de receber a versão; no hml as mudanças chegam antes. Confira o GET /v1/ping e uma chamada de teste antes de contar com uma mudança.
• Datas. Valem em UTC. Uma mudança de 2026-10-18 pode ter chegado ao seu ambiente depois.
• O que não aparece aqui. Ajustes de operação do Dracma, regras da sua operação (configuração) e correções que não mudam o que você observa.
• Documento OpenAPI. Alguns trechos do documento ainda não refletem as mudanças acima; a lista está em Divergências conhecidas.

Veja também¶

• Versionamento
• Autenticação HMAC
• Limites e quotas
• Ciclo do saque
• O painel
• Divergências conhecidas