Reconciliar com o seu livro

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

Todo dia, o Dracma entrega um relatório dos movimentos liquidados, com um digest assinado. A sua reconciliação compara esse relatório com o seu livro. Esta página mostra o que cada tipo de item significa para o seu livro, o que o relatório não traz e como investigar uma diferença. Parâmetros, digest e assinatura estão em Referência: reconciliação.

O que é

O relatório (GET /v1/reconciliation) lista, por dia UTC e por moeda, cada movimento que se tornou definitivo no dia. Os tipos (kind) que o Dracma emite hoje são:

kind O que representa status do item
deposit Depósito que chegou a paid paid
withdrawal Saque que chegou a paid paid
refund Estorno de depósito refunded
chargeback Chargeback ou MED de depósito chargeback
return Depósito devolvido em revisão, ou saque devolvido pelo banco returned

Reservado no contrato

Os tipos fee, recall e receipt fazem parte do contrato, mas o Dracma não emite nenhum deles hoje. fee aparece como item só se houver tarifa visível (hoje não há; veja Tarifas). recall e receipt pertencem a transferências bancárias, que o Dracma não oferece. Se algum desses tipos chegar, trate como item de revisão, sem lançamento automático no seu livro.

Quando usar

Use esta página ao montar a rotina diária de conferência e ao investigar uma diferença entre o seu livro e o relatório.

Rotina recomendada:

Quando O quê
A cada 5 minutos GET /v1/events?after=<último evento>: deduplique, faça o fetch-back e aplique o efeito. Veja Webhooks: recuperação.
Diariamente, depois das 02:00 UTC GET /v1/reconciliation do dia anterior, para cada moeda: confira o digest e a assinatura e compare com o livro.
Continuamente GET /v1/balances: alerte quando o caixa livre ficar baixo (veja Saldos e caixa livre).

Como funciona

O que cada item significa para o seu livro

kind Valor do item (amount) settled_at Sentido no seu livro
deposit Valor pago (igual ao do depósito) Instante do pagamento (paid_at) Um crédito do jogador, com o mesmo external_id
withdrawal Valor do saque Instante do pagamento (paid_at) Uma reserva finalizada
refund Valor do depósito Instante do evento de estorno Um débito, conforme a sua política
chargeback Valor do depósito Instante do evento Um débito, conforme a sua política
return (depósito) paid_amount do depósito Instante da devolução Nenhum lançamento: o depósito nunca foi creditado
return (saque) return.returned_amount, que pode ser parcial Instante da devolução Política sua: o caixa da operação recebeu o valor devolvido

Depósito devolvido: só o item return

Um depósito returned nunca passou por paid, então nunca houve crédito. O relatório mostra apenas o item return desse depósito e nenhum item deposit. Se o seu livro creditou o jogador antes da devolução, você tem um crédito sem par.

Saque devolvido: dois itens em dias diferentes

Um saque devolvido pelo banco aparece duas vezes:

  1. Como withdrawal com status: "paid", no dia do pagamento.
  2. Como return com status: "returned", no dia da devolução, pelo valor devolvido.

O Dracma não compensa o item withdrawal quando há devolução: o total withdrawals_paid continua contando o saque pago. A devolução é um segundo item, em outro dia.

O total de devoluções não existe

totals traz deposits_paid, withdrawals_paid, refunds, chargebacks, fees e count. Não há returns. Os itens return contam em count, mas não entram em nenhum total de valor.

Não disponível

O relatório não traz o total de devoluções. Por isso, a regra "os totais batem com a soma dos itens" só vale para os tipos que têm total. Some os itens return à parte, no seu lado, e confira essa soma com o que o seu livro lançou. O relatório também não tem item de ajuste ou de correção.

Conferência dos totais, tipo a tipo:

Total Como conferir
deposits_paid Soma dos itens deposit
withdrawals_paid Soma dos itens withdrawal
refunds Soma dos itens refund
chargebacks Soma dos itens chargeback
fees Sempre "0" (sem itens fee)
count Todos os itens, inclusive return
Devoluções Soma dos itens return, fora dos totais

O que comparar com o seu livro

Para cada dia e cada moeda:

  1. Todo deposit do relatório tem exatamente um crédito no seu livro, com o mesmo external_id e o mesmo valor.
  2. Todo crédito seu tem um deposit no relatório. Um crédito sem par é o caso mais grave: é dinheiro criado sem liquidação.
  3. Todo withdrawal corresponde a uma reserva sua finalizada, e vice-versa.
  4. refund e chargeback correspondem às decisões que você registrou.
  5. Todo return corresponde a um caso aberto (devolução de depósito ou de saque).
  6. Os totais de depósito, saque, estorno e chargeback batem com a soma dos itens do tipo.

Divergência é incidente. Não ajuste o seu livro para fazê-lo bater. Abra o incidente, congele o que for preciso, investigue e registre. Dispare alerta quando o digest ou a assinatura não baterem, ou quando faltar um par.

Rotina diária (pseudocódigo)

O horário do job é seu. Escolha um horário depois das 02:00 UTC (por exemplo, 02:30 UTC) e rode uma vez por moeda habilitada:

para cada moeda em GET /v1/currencies:
  itens = baixar todas as páginas de GET /v1/reconciliation?date=D-1&currency=moeda
  se 409 day_open: reagendar para depois das 02:00 UTC, sem laço
  conferir digest e assinatura                 # veja a referência
  para cada item em itens:
    casar com o seu livro por (external_id, kind)
  para cada lançamento do seu livro no dia, sem item correspondente:
    abrir incidente "crédito sem par"
  somar os itens "return" à parte e conferir
  publicar métricas: itens, sem par, total por tipo, duração da rotina

Métricas úteis para o seu painel: quantidade de itens sem par, diferença de valor por tipo, idade do último dia reconciliado e duração da rotina.

O que a reconciliação não prova

Não disponível

O relatório prova o livro do Dracma, não o banco. O Dracma não importa nem guarda o extrato do PSP, e o painel não faz a conferência automática com ele. Se você quer provar que o dinheiro chegou à conta bancária, use o extrato do próprio PSP ou do seu banco.

O painel de reconciliação (veja Painel: reconciliação) exporta o mesmo relatório e permite importar o seu livro para comparar.

Exemplos

Relatório de 2026-10-19 com duas devoluções: um depósito devolvido em revisão (sem item deposit) e um saque pago no dia anterior que o banco devolveu parcialmente (R$ 30,00 de R$ 50,00). Note que count é 2 e todos os totais de valor são zero, porque return não tem total.

{
  "date": "2026-10-19",
  "currency": "BRL",
  "items": [
    {
      "object_id": "dep_0192a3b40c6d7e8f9a0b1c2d3e4f5a71",
      "external_id": "dep_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a71",
      "kind": "return",
      "status": "returned",
      "amount": { "amount": "5000", "currency": "BRL" },
      "fee": null,
      "settled_at": "2026-10-19T11:20:00Z"
    },
    {
      "object_id": "wdr_0192a3b40c6d7e8f9a0b1c2d3e4f5a6c",
      "external_id": "wdr_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6c",
      "kind": "return",
      "status": "returned",
      "amount": { "amount": "3000", "currency": "BRL" },
      "fee": null,
      "settled_at": "2026-10-19T10:00:00Z"
    }
  ],
  "next_cursor": null,
  "totals": {
    "deposits_paid": { "amount": "0", "currency": "BRL" },
    "withdrawals_paid": { "amount": "0", "currency": "BRL" },
    "refunds": { "amount": "0", "currency": "BRL" },
    "chargebacks": { "amount": "0", "currency": "BRL" },
    "fees": { "amount": "0", "currency": "BRL" },
    "count": 2
  },
  "digest": "8385cc0772eb313749c1114c88e5ba6889b60f8d10ad5c69f99f364a891c52c6"
}

Os itens estão em ordem de object_id, como o digest exige. O mesmo saque wdr_0192a3b40c6d7e8f9a0b1c2d3e4f5a6c aparece também como withdrawal no relatório do dia 18.

Erros e casos de borda

Investigar uma diferença

  1. Anote o object_id, o external_id e o kind do item.
  2. Leia o objeto: GET /v1/deposits/{id} ou GET /v1/withdrawals/{id}. Confira status, version, paid_amount e, no saque devolvido, return.
  3. Liste a história do objeto com GET /v1/events?object_id=<id>. Veja em que ordem os estados chegaram e quando.
  4. Compare com o seu registro: o seu livro reagiu a todos os eventos? Houve evento duplicado ou perdido?
  5. Para a investigação com o Dracma, guarde o trace_id da resposta e o Dracma-Event-Id do webhook (veja Suporte).

Casos comuns

Sintoma Causa provável O que fazer
Crédito seu sem deposit no relatório O depósito foi returned, ou você creditou antes de paid Estorne o seu crédito conforme a política e abra caso
deposit sem crédito seu Webhook perdido ou fetch-back não executado Recupere por GET /v1/events; credite uma vez, pelo external_id
Item return que você não esperava Depósito devolvido em revisão ou saque devolvido pelo banco Veja o objeto e abra caso
Total de valor não bate com os itens Item return fora dos totais Some os itens return à parte
Item de dia vizinho Fuso: você comparou pela data local Compare pelo settled_at em UTC
409 day_open O dia ainda não abriu (antes de 02:00 UTC de D+1) Aguarde, sem laço
503 na última página O Dracma não conseguiu assinar ou recalcular o digest Repita depois do Retry-After; se persistir, chame o suporte

Veja também