Glossário

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

Os termos que aparecem em mais de uma página do guia, em ordem alfabética dentro de cada grupo. Cada definição aponta para a página que explica o assunto por inteiro.

O que é

Quatro grupos: contas e acesso, chamadas à API, dinheiro e webhooks.

Quando usar

Quando um termo de outra página não está claro. Os seis termos de base (tenant, operação, tipo da operação, conector, jogador e PSP) também estão em Visão geral.

Como funciona

Contas e acesso

Termo Definição
Administrador do tenant A primeira pessoa da sua empresa no painel. Entra por convite, convida a equipe e pede chaves. Veja Equipe e papéis.
Aprovação de outra pessoa (4-eyes) Regra do painel: uma ação sensível vira um pedido, e só vigora depois que outra pessoa (nunca quem pediu) aprova. Um voto contra encerra o pedido. Veja O painel.
Conector O serviço do seu lado que fala com o Dracma. Só ele guarda a chave e o segredo.
Confirmação recente (step-up) Prova de identidade com um fator forte nos últimos 5 minutos, exigida para aprovar, revelar segredo ou ver dado pessoal. Veja Conta, login e dispositivos.
Fator forte Passkey ou aplicativo autenticador. O e-mail sozinho não basta para as ações sensíveis.
Operação Uma marca em um país e em um ambiente. É a unidade de credencial, regra, moeda, webhook e saldo.
Pacote (papel) Conjunto de permissões de uma pessoa na operação: Administrador, Financeiro, Revisor ou Auditor. Veja Equipe e papéis.
Staff do Dracma A equipe do Dracma que cria tenants, cadastra e ativa gateways e aprova pedidos de operação Real.
Tenant A sua empresa (pessoa jurídica) no Dracma. Agrupa pessoas, operações e a trilha de auditoria.
Time-lock (espera) Espera de 24 h depois da aprovação em certos pedidos (chave nova, IP novo, URL de webhook, afrouxar regra). Durante a espera, o pedido pode ser cancelado.
Tipo da operação Teste (simulador, sem dinheiro real, chave key_test_) ou Real (PSP de verdade, dinheiro real, chave key_live_). Veja Ambientes, tipos de operação e hosts.

Chamadas à API

Termo Definição
external_id O id que você dá a cada depósito ou saque. Único por operação e por tipo; é a âncora de idempotência e de conciliação. Veja Idempotência e repetição.
Escopo Permissão da chave: read, deposits:write, withdrawals:write, rules:propose. Veja Escopos.
Idempotency-Key Cabeçalho obrigatório em todo POST. Repetir com a mesma chave e o mesmo corpo devolve o mesmo resultado, sem novo efeito. Veja a chave.
Leitor tolerante Código que ignora campo desconhecido e trata estado, evento ou código desconhecido como "não terminal", sem mover dinheiro. Veja Convenções HTTP.
Money Valor monetário como texto de inteiro na menor unidade ("5000" = R$ 50,00). Nunca número de ponto flutuante. Veja Dinheiro.
Nonce Valor aleatório de 32 hex minúsculos, novo em toda requisição assinada. O Dracma recusa um nonce repetido com 401 replayed_nonce.
Pedido canônico O texto de 6 linhas que você assina com HMAC-SHA256. Veja Pedido canônico e assinatura.
problem+json Formato dos erros da API (RFC 9457), com code estável, retryable e trace_id. Veja Erros.
Dracma-Trace-Id Identificador da requisição, em toda resposta. É o que o suporte pede. Veja Suporte.
Vetores de assinatura Casos normativos de assinatura de chamada e de webhook que o seu código deve reproduzir byte a byte. Veja Exemplos executáveis.

Dinheiro

Termo Definição
available Dinheiro da operação que entrou por depósito pago e ainda não saiu. Inclui o valor reservado. Veja Saldos e caixa livre.
Caixa livre available - pending_out. É o que sustenta um novo saque.
pending_in Dinheiro recebido e ainda não creditado (depósitos em revisão). Informativo.
pending_out Valor reservado para saques que o Dracma está enviando ao PSP.
Decisão Resultado do motor de regras para um saque: automático, revisão ou bloqueio. Veja Decisão, limites e regras.
Digest Resumo assinado do relatório diário de reconciliação. Veja Reconciliação.
Gateway A conexão de uma operação com um PSP, para entrada (depósito) ou saída (saque). O cadastro é feito pelo staff. Veja Gateways.
needs_decision Caso que o seu conector abre quando o estado exige decisão humana (estorno, chargeback, devolução). Veja Política de exceções.
PSP O provedor de pagamento que movimenta o PIX de fato. O conector nunca fala com ele.
Reconciliação Conferência diária do seu livro contra o relatório do Dracma. Veja Reconciliar com o seu livro.
Regras Conjunto versionado por operação com limites, horários e aprovação dupla, lido em GET /v1/rules. Veja Regras (API).
Reserva Débito que você faz no saldo do jogador antes de POST /withdrawals. Devolvida só em rejected, failed ou cancelled.
Revisão Decisão humana, no painel, sobre um depósito ou saque que as regras não liberaram sozinhas. Veja Revisão.
under_review Estado de depósito ou saque à espera da revisão.
Estorno, chargeback Devolução de um depósito já pago (refunded, chargeback). Só existem no sandbox hoje. Veja Devoluções, estornos e disputas.

Webhooks

Termo Definição
DLQ Fila das entregas que esgotaram as tentativas sem 2xx em 72 h. O evento continua em GET /events e pode ser reentregue pelo painel. Veja Retentativas, skipped e DLQ.
Entrega O registro de um evento a enviar para a URL da operação. Há uma entrega por evento; cada tentativa é um POST.
Envelope O JSON do webhook: id, type, object_id, object_version, data.object. Veja Envelope.
Fetch-back A consulta que o receptor faz à API, com a própria credencial, para confirmar o estado antes de mover dinheiro. O corpo do webhook nunca é a fonte de verdade.
Dracma-Event-Id Identificador estável de um evento (evt_...). É a chave de deduplicação do receptor.
object_version Contador que só cresce, por objeto. Resolve a ordem quando os eventos chegam fora de ordem.
Operador de referência Receptor que a suíte de conformidade usa como oráculo. Veja Suíte de conformidade.
skipped Entrega registrada e não enviada: sem URL cadastrada, ambiente diferente ou tipo não assinado.
Webhook POST assinado do Dracma para o seu servidor a cada mudança de estado. Só avisa. Veja Webhooks.

Exemplos

Na frase "o receptor deduplica pelo Dracma-Event-Id, faz fetch-back e credita pelo external_id", os três termos se encaixam: o evento chega (webhook), a consulta confirma o estado (fetch-back) e o seu livro grava uma vez (idempotência).

Erros e casos de borda

  • "Aprovação dupla" tem dois sentidos neste guia. Nas ações do painel, basta uma aprovação de outra pessoa. Na revisão de um saque de valor alto, o motivo DUAL_APPROVAL_REQUIRED pede duas pessoas diferentes (Revisão).
  • "Dia" é o dia UTC na reconciliação e o dia do fuso da operação nas janelas de limite (Dia, fuso e horários).

Veja também