Objetos e campos

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

Uma tabela por objeto da API, com tipo, nulabilidade e a coluna "hoje": o que a API de fato devolve (nas respostas) ou aceita (nos pedidos). O documento OpenAPI traz mais campos do que o Dracma preenche. Esta página diz quais são os campos reais, para você escrever o seu parser sem esperar um valor que nunca vem.

O que é

A referência de cada objeto, na ordem em que aparecem nas outras páginas desta seção. Os nomes de schema (Deposito, Saque, Moeda...) são os do documento OpenAPI. Legenda da coluna "hoje":

Valor Significado
sim a API devolve (ou aceita) o campo
null o campo vem, mas sempre null (ou [])
não a API nunca devolve o campo, apesar de estar no OpenAPI
ignorado a API aceita o campo no pedido e não faz nada com ele

Quando usar

  • Ao escrever o parser das respostas e os tipos do seu cliente.
  • Ao gerar um cliente a partir do OpenAPI: confira aqui quais campos são reais.
  • Ao revisar um pedido recusado com unknown_field: veja os campos aceitos de cada pedido.

Regras gerais, que valem para todas as tabelas:

  • Dinheiro é sempre Money. Datas são RFC 3339 em UTC. IDs do Dracma são opacos e têm prefixo. Veja Convenções HTTP.
  • Pedidos são estritos: campo desconhecido vira 400 validation_failed com reason: unknown_field.
  • Respostas devem ser lidas com tolerância: campo, valor de enum ou estado novo nunca devem derrubar o seu parser.

Como funciona

Uma seção por grupo de objetos: tipos comuns, pedidos, respostas de depósito e de saque, moedas e regras, reconciliação, eventos e erros.

Tipos comuns

Money

Campo Tipo Regra
amount texto inteiro sem sinal e sem zero à esquerda, na menor unidade da moeda, com até 38 dígitos. "0" existe, mas pedidos exigem valor maior que zero
currency texto código da moeda. Hoje BRL

Documento

Campo Tipo Regra
type texto CPF, CNPJ, PASSPORT, NATIONAL_ID ou TAX_ID. Em PIX, só CPF e CNPJ passam da validação de regra
number texto CPF/CNPJ: só dígitos, 11 a 14. Outros tipos: 1 a 32 caracteres
country texto ISO 3166 alfa-2 em maiúsculas

Jogador (dentro de player, nos pedidos de depósito e saque)

Campo Tipo Obrigatório Hoje Regra
external_ref texto sim sim ^[A-Za-z0-9_.:-]{1,64}$, opaco e imutável
document Documento sim sim fixado no primeiro uso do external_ref
name texto depende da operação sim até 120 caracteres
email texto depende da operação depósito: sim. Saque: ignorado até 254 caracteres. Em operação Teste, só TLD reservado
birth_date texto não ignorado informativo
kyc_level texto não ignorado informativo
ip texto depende sim IP do jogador. No saque, sem ele o saque nunca é automático
device_id texto depende sim até 128 caracteres

Pedidos

CriarDeposito (POST /v1/deposits). Detalhes em Depósitos.

Campo Obrigatório Hoje Regra
external_id sim sim ^[A-Za-z0-9_.:-]{1,64}$, único por operação
player sim sim Jogador
amount sim sim Money maior que zero
method sim sim só pix
expires_in_seconds não sim 300 a 86400. Padrão 1800
locale não sim por exemplo pt-BR
metadata não sim até 20 chaves, valores texto
method_options não não (unknown_field) só no contrato 1.1.0, reservado para cartão, cripto, wire, SWIFT e boleto
fx_quote_id não não (unknown_field) só no contrato 1.1.0, reservado para câmbio

CriarSaque (POST /v1/withdrawals). Detalhes em Saques.

Campo Obrigatório Hoje Regra
external_id sim sim idem depósito
player sim sim Jogador. player.ip é, na prática, obrigatório
amount sim sim Money maior que zero
method sim sim só pix
destination sim sim exatamente um destino. Em PIX: {"pix": {"key_type", "key"}}; key_type em cpf, cnpj, email, phone, random; key de 1 a 140 caracteres
review_requested não sim true obriga revisão manual
review_reasons não sim lista de textos; viram OP:<texto> no painel
player_context não sim informativo; nunca libera o automático
metadata não sim até 20 chaves, valores texto
purpose, fx_quote_id, payout_currency não ignorado reservados para câmbio e SWIFT

Respostas de depósito

Deposito. A API devolve 16 campos. Detalhes em Depósitos.

Campo Tipo Nulo? Hoje Conteúdo
id texto não sim dep_ mais 32 hexadecimais
external_id texto não sim o seu id
status texto não sim StatusDeposito
version inteiro não sim a partir de 1; sobe a cada transição
amount Money não sim valor cobrado
paid_amount Money sim sim valor pago
method texto não sim pix
player_ref texto não sim o seu external_ref
payer objeto sim sim {document?, name?, matches_player}
instructions objeto sim sim {pix: {copy_paste, expires_at, qr_code_png_base64?}}
failure_code texto sim sim motivo técnico em failed
review_reasons lista de texto não sim [] fora de revisão
created_at, updated_at texto não sim UTC, segundos, sem fração
paid_at, expires_at texto sim sim UTC, segundos, sem fração
rail, received_amount, receipts, fee, fees, fx, compliance, expected_settlement_date, return — — não reservados da v1.1.0 (só no contrato; fora do OpenAPI servido)

payer: document (Documento), name (texto) e matches_player (booleano). Só matches_player é sempre presente.

Respostas de saque

Saque. Detalhes em Saques.

Campo Tipo Nulo? Hoje Conteúdo
id texto não sim wdr_ mais 32 hexadecimais
external_id texto não sim o seu id
status texto não sim StatusSaque
version inteiro não sim a partir de 1
amount Money não sim valor pedido
fee Money sim null sempre null
method texto não sim pix
player_ref texto não sim o seu external_ref
decision Decisao não sim decisão do motor
psp_reference texto sim sim identificador do pagamento PIX, quando pago
failure_code texto sim sim motivo técnico em failed
created_at, updated_at texto não sim UTC, pode ter fração de segundo
paid_at texto sim sim UTC, pode ter fração
return DevolucaoBancaria sim sim em returned; null nos demais devolução do banco
rail, charge_bearer, fx, purpose, compliance, expected_settlement_date, sent_at, tracking, recall — sim null reservados da v1.1.0
fees lista não [] reservado da v1.1.0

Decisao

Campo Tipo Nulo? Hoje Conteúdo
mode texto não sim automatic ou manual. Em requested, manual
reasons lista de texto não sim códigos de revisão ou bloqueio; [] no automático
ruleset_version inteiro não sim versão do conjunto de regras usado
decided_by lista de texto não sim ids opacos dos revisores; [] no automático
decided_at texto sim sim null enquanto não decidido

DevolucaoBancaria (o objeto return)

Campo Tipo Nulo? Hoje Conteúdo
reason_code texto não sim código curto do PSP ou unspecified
returned_amount Money não sim valor devolvido; pode ser parcial
returned_at texto não sim instante da devolução
reason, return_fee — — não do schema do contrato; não vêm em PIX

Moedas, limites, saldos e regras

Moeda e DetalheMetodo. Detalhes em Ping e moedas.

Campo Tipo Nulo? Hoje Conteúdo
code texto não sim BRL
kind texto não sim fiat
exponent inteiro não sim 2 em BRL
methods lista de texto não sim ["pix"]
method_details lista não sim um item por método
method_details[].method texto não sim o método
method_details[].deposit_requirements lista de texto não sim campos do Jogador exigidos
method_details[].psp_notes lista de texto não sim avisos informativos
rails — — não reservado da v1.1.0

LimitesJogador. Detalhes em Limites do jogador e saldos.

Campo Tipo Hoje
player_ref, currency texto sim
total_deposited, total_withdrawn, auto_withdrawal_remaining Money sim
auto_multiplier texto (decimal) sim
blocked booleano sim

Saldo (item de data em GET /v1/balances)

Campo Tipo Hoje
available, pending_in, pending_out Money sim
as_of texto sim

ConjuntoDeRegras: campos principais em Regras (API). A resposta de POST /v1/rules/change-requests tem dois campos: id (chg_ mais 32 hexadecimais) e status (pending_approval).

Reconciliação

Reconciliacao. Detalhes em Reconciliação.

Campo Tipo Nulo? Hoje Conteúdo
date texto não sim AAAA-MM-DD, UTC
currency texto não sim a moeda pedida
items lista não sim itens da página
items[].object_id, external_id, kind, status texto não sim veja a página
items[].amount Money não sim valor do movimento
items[].fee Money sim null sempre null
items[].settled_at texto não sim UTC, segundos
next_cursor texto sim sim null na última página
totals objeto sim sim só na última página
totals.deposits_paid, withdrawals_paid, refunds, chargebacks, fees Money não sim fees é "0". Não há total de return
totals.count inteiro não sim inclui os itens return
digest texto sim sim só na última página

Eventos e erros

Evento (envelope do webhook e item de GET /v1/events): id, type, created_at, operation_id, object_id, object_version e data.object. Os campos, formatos e o catálogo de tipos estão em Envelope e Catálogo de eventos.

Problema (o corpo de todo erro, application/problem+json). Detalhes em Erros.

Campo Tipo Presente Conteúdo
type texto sempre identificador do erro, no formato de uma URL. É um identificador opaco: não abra o endereço
title texto sempre igual ao code
status inteiro sempre o status HTTP
code texto sempre o código estável do erro
detail texto só quando não vazio por exemplo em day_open e internal_error
trace_id texto quase sempre informe-o ao suporte
retryable booleano sempre true quando repetir pode funcionar
existing objeto só em 409 duplicate_external_id o Deposito ou Saque já existente
errors lista só em validação {field, message, reason?}; reason é omitido quando vazio

Exemplos

Um erro de validação com dois itens:

{
  "type": "https://docs.dracma.test/errors/validation_failed",
  "title": "validation_failed",
  "status": 400,
  "code": "validation_failed",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "retryable": false,
  "errors": [
    { "field": "method", "message": "Metodo desconhecido", "reason": "enum" },
    { "field": "player.document.country", "message": "ISO-3166 alfa-2", "reason": "format" }
  ]
}

Um 409 duplicate_external_id traz o objeto existente:

{
  "type": "https://docs.dracma.test/errors/duplicate_external_id",
  "title": "duplicate_external_id",
  "status": 409,
  "code": "duplicate_external_id",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "retryable": false,
  "existing": {
    "id": "dep_0192a3b40c6d7e8f9a0b1c2d3e4f5a6b",
    "external_id": "dep_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
    "status": "pending",
    "version": 2
  }
}

Erros e casos de borda

  • Campo reservado que não vem. Não faça payload.fee.amount sem checar: fee é null ou nem existe.
  • Campo que vem null. Em Deposito e Saque, os campos de data e valor opcionais vêm null, não ausentes.
  • detail ausente não é erro: a API o omite quando está vazio.
  • Enum novo. status, kind, reason e review_reasons são listas abertas. Valor desconhecido: não derrube o parser.
  • Pedido com campo a mais volta unknown_field. Isso vale para method_options e fx_quote_id em depósito.
  • Números grandes. Money.amount pode ter 38 dígitos: use inteiro de precisão arbitrária, nunca float.

Veja também