FAQ¶

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

Respostas curtas às perguntas mais comuns de quem integra, de quem cuida do financeiro e de quem administra a operação. Cada resposta aponta para a página que explica o assunto por inteiro.

O que é¶

Um índice de perguntas, agrupado por tema. A pergunta sobre operação suspensa (403 operation_suspended) tem resposta completa no fim da página, em "Erros e casos de borda".

Quando usar¶

Quando você tem uma dúvida pontual e quer a resposta antes de ler a página inteira. Para um erro em andamento, comece por Problemas de integração, que parte do sintoma.

Como funciona¶

Ambientes e acesso¶

Qual é a diferença entre operação Teste e operação Real? A operação Teste usa o simulador: nenhum dinheiro se move e as rotas /v1/sandbox/* existem em homologação. A operação Real cobra e paga de verdade, em qualquer ambiente, inclusive no hml. A chave diz qual é qual: key_test_… para Teste, key_live_… para Real. Veja Ambientes, tipos de operação e hosts.

Em que operação eu caí? Chame GET /v1/ping: o campo environment devolve sandbox (Teste) ou production (Real). Uma chave do tipo errado para o host volta 401 unknown_key.

Preciso cadastrar IPs fixos do meu servidor? Não é obrigatório: sem IP cadastrado a operação aceita chamadas assinadas de qualquer origem, o que deixa o teste livre. É altamente recomendado, principalmente em Real. Com IP cadastrado, outra origem recebe 403 ip_not_allowed; use o IP público de saída e só se ele for fixo. Veja IPs do conector.

mTLS é obrigatório? Não por padrão. O certificado de cliente é uma camada opcional de rede; a autenticação que vale em toda chamada é a assinatura HMAC. Detalhes em Rede, lista de IPs e mTLS.

Posso chamar a API do navegador do jogador? Não. A API é para o servidor do seu conector: o segredo da chave nunca pode ir para o navegador, e a API não responde a CORS para o seu domínio.

Como o administrador do integrador entra pela primeira vez? O Dracma cria o tenant e convida o administrador por e-mail; ele não cria a operação nem recebe a chave. O link vale 72 horas e só pode ser usado uma vez. Quem aceita o convite, com dois fatores, vira dono do tenant e cria as próprias operações e chaves no painel. Depois, o dono convida a equipe do mesmo modo. Veja Do zero ao go-live e Equipe e papéis.

Perdi o segredo da chave. Dá para ver de novo? Não. O segredo é exibido uma única vez, ao proponente, em uma janela de 24 h depois da aprovação. Crie outra chave e revogue a antiga (Chaves de API).

Quantas chaves posso ter ao mesmo tempo? Até 2 chaves ativas por operação, o que permite trocar sem parada: crie a nova, faça o deploy, confira o "último uso" e revogue a antiga. A revogação vale em até 60 s.

Minha URL de webhook em homologação é um domínio meu. Funciona? Fora de produção, o Dracma só entrega webhook em domínios de teste (.test, .example, .invalid) ou em um domínio que ele tenha liberado para você. No onboarding, informe o domínio que você vai usar e peça a liberação. Endereços temporários de túnel não são aceitos. Veja Seu endpoint.

Chamadas e erros¶

Meu POST deu timeout. O saque (ou o depósito) foi criado? Você não sabe. Repita com a mesma Idempotency-Key e o mesmo corpo: se ele já foi criado, você recebe a mesma resposta, com Idempotent-Replayed: true; se não, ele é criado agora. Não crie com chave nova. Veja Idempotência e repetição.

Posso repetir um 4xx? Não: é uma decisão. Corrija a causa. Para tentar de novo depois de uma recusa de negócio, use external_id e Idempotency-Key novos.

Recebi 202 ao criar um depósito. Deu erro? Não. O depósito existe no estado created; o PSP ainda não devolveu as instruções de pagamento. Siga pelo webhook e pelo GET /deposits/{id}. Saque nunca responde 202: é sempre 201.

Por que 403 insufficient_scope? A chave não tem o escopo da rota (por exemplo, read não cria depósito). Também aparece quando você usa um método que a API não tem (PUT, DELETE). Veja a tabela em Autenticação HMAC.

Por que recebo 404 em um depósito que existe? Porque o objeto é de outra operação (outra chave) ou o id está errado. A API responde 404 nos dois casos, de propósito, sem confirmar se o objeto existe em outra operação.

Quanto posso chamar por segundo? Chave de escrita: 50/s, rajada 100; leitura: 100/s por chave; listagens: 5/s. Por jogador: 10 depósitos e 3 saques por hora. Tudo em Limites e quotas.

Posso mandar amount com decimais ou como número? Não. amount é uma string de inteiro na menor unidade ("5000" para R$ 50,00). Veja Convenções HTTP.

O e-mail do jogador é obrigatório no depósito? Depende da operação: algumas exigem player.name e player.email (GET /v1/currencies lista as exigências em method_details). Sem o campo exigido, a resposta é 400 com reason: required_by_operation e nada é criado. Em operação Teste, o e-mail precisa ser de domínio reservado (.test, .invalid, .example).

Posso usar cartão, boleto, wire, SWIFT ou câmbio? E cripto?

O que fazer com um code ou status que não conheço? Seja um leitor tolerante: trate pela classe HTTP e pelo retryable, e trate estado desconhecido como não terminal, conferindo pelo fetch-back. Veja Versionamento.

Dinheiro¶

O Dracma cobra tarifa? A tarifa é negociada por contrato, e esta documentação não traz valores. O Dracma não desconta tarifa do crédito do jogador nem do valor pago: o campo fee do saque vem null, e o depósito não o devolve. Veja Tarifas.

Como coloco dinheiro no caixa da operação para pagar saques?

O saque ficou em processing por muito tempo. É erro? Não necessariamente. O estado só muda quando o banco confirma. Não crie um saque novo nem devolva a reserva ao jogador sem a resposta conclusiva. Veja Ciclo do saque.

O banco devolveu o PIX de um saque. O que muda? O saque paid pode virar returned, com o objeto return (reason_code, returned_amount, returned_at). A devolução pode ser parcial. O caixa da operação é creditado pelo valor devolvido. Veja Devoluções, estornos e disputas.

Como confiro o meu livro com o do Dracma? Com GET /v1/reconciliation (um dia por moeda, disponível a partir de 02:00 UTC do dia seguinte) e GET /v1/balances. Veja Reconciliar com o seu livro.

Webhooks e eventos¶

Perdi webhooks. Como recupero? Com GET /v1/events?after=<último evt_ processado>, que devolve os eventos da sua operação em ordem de criação. Veja Recuperação por GET /events.

Posso confiar no corpo do webhook para creditar o jogador? Não. O corpo é um aviso. Antes de mover dinheiro, consulte o objeto (GET /deposits/{id} ou GET /withdrawals/{id}) e confira o external_id. Veja Receptor de webhooks.

Painel e equipe¶

Por que minha ação no painel ficou "pendente"? Ações sensíveis (criar chave, mudar webhook, afrouxar regra, dar papel que aprova dinheiro) exigem a aprovação de outra pessoa e, em alguns casos, uma espera de 24 h. Quem propõe não vota. Veja Equipe e papéis.

A operação aparece como "Suspensa" no painel. Posso reativá-la? Não pelo painel. Veja a resposta completa abaixo.

Exemplos¶

Mensagem boa para o suporte (copie e preencha; todos os campos vêm da resposta do erro e do seu log):

Operação: <operation_id do GET /v1/ping>
Tipo: Teste (key_test_) ou Real (key_live_)
Quando (UTC): 2026-10-18T15:04:05Z
Chamada: POST /v1/withdrawals
Resposta: 503 service_unavailable
Dracma-Trace-Id: 4bf92f3577b34da6a3ce929d0e0e4736
external_id: wdr_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b
O que já tentei: repeti 3 vezes com a mesma Idempotency-Key, com backoff

Nunca envie o segredo da chave, o segredo de webhook nem o corpo com documento do jogador. O trace_id, o external_id e o horário bastam. O canal de suporte está em Suporte.

Erros e casos de borda¶

Operação suspensa: 403 operation_suspended¶

O que acontece. Com a operação suspensa, toda chamada /v1 autenticada volta 403 operation_suspended, inclusive GET e GET /v1/ping. A assinatura continua sendo conferida: com assinatura inválida você ainda vê 401.

Quem suspende e quem retoma. O Dracma. O painel mostra a situação Suspensa na lista de operações, mas não tem ação para suspender nem para retomar. Fale com o suporte (Suporte), informando o operation_id e o Dracma-Trace-Id da resposta.

O que fazer no conector enquanto durar:

1. Pare de enviar: um 403 é definitivo para aquela requisição. Não faça laço de repetição. Abra o circuito do conector e pause a fila de depósitos e saques.
2. Mantenha as reservas. Saque cujo POST você enviou e cuja resposta não viu continua com a reserva do jogador onde está. Não a devolva às cegas.
3. Não crie objetos novos com external_id novo para "contornar": quando a operação voltar, o pedido original ainda pode estar válido.
4. Objetos já criados seguem o próprio ciclo. Um depósito pode ser pago ou expirar, e um saque em curso pode avançar, porque isso não depende das chamadas à API.
5. Depois da retomada, recupere o que aconteceu: GET /v1/events?after=<último evento processado> e, para cada pedido incerto, GET /v1/deposits?external_id=… ou GET /v1/withdrawals?external_id=…. Só então retome a fila, começando devagar por causa do limite de taxa.

Como saber que voltou. GET /v1/ping volta 200. Faça esse ping a cada minuto, com a assinatura de sempre, em vez de repetir chamadas de negócio.

Outras situações¶

• 403 insufficient_scope logo depois de criar a chave: confira os escopos marcados na criação; se faltar um, crie uma chave com os escopos certos e revogue a anterior.
• 401 unknown_key com a chave certa: o tipo da chave não bate com o host (Teste × Real), ou a chave foi revogada.
• Divergência entre o guia e a API: a API vale; registre em Divergências conhecidas e avise o suporte.

Veja também¶

• Problemas de integração
• Suporte
• Idempotência e repetição
• Erros
• Limites e quotas
• Ciclo do saque
• Ambientes, tipos de operação e hosts