Dracma para desenvolvedores

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

Este é o portal de quem integra o Dracma: o conector do seu lado chama a API v1 para cobrar depósitos PIX e pagar saques PIX, e recebe webhooks assinados a cada mudança de estado. Aqui estão a autenticação, os endpoints, os webhooks, o sandbox, os exemplos executáveis e o checklist de go-live.

Quem só usa o painel (financeiro, revisor, dono da conta) encontra o que precisa na documentação do painel.

O que é

O Dracma é um gateway de pagamento multi-tenant. O seu conector assina cada chamada com HMAC-SHA256, manda Idempotency-Key = external_id em todo POST de dinheiro e trata o webhook como um aviso: o dinheiro só se move depois do fetch-back (GET /v1/deposits/{id} ou GET /v1/withdrawals/{id}). O Dracma fala com o PSP, aplica o motor de regras (saque automático ou revisão humana) e avisa cada mudança.

Os termos curtos (tenant, operação, conector, jogador, PSP) estão na Visão geral e os demais no Glossário.

Regra de precedência

Este portal segue o Contrato de integração v1, versão 1.1.0, e o OpenAPI publicado que a API serve. O OpenAPI dá a forma (campos e tipos); o contrato dá a semântica (assinatura, idempotência, máquinas de estado). Se o portal e o contrato divergirem, vale o contrato, e a divergência é um erro do portal. As diferenças conhecidas entre o contrato e a API de hoje estão em Divergências conhecidas.

Mudança incompatível só acontece como /v2. A v1 só recebe acréscimos (campos, estados, eventos e códigos novos), por isso o seu código deve ser um leitor tolerante. Veja Versionamento.

Quando usar

Como funciona

A ordem recomendada para integrar:

  1. Ambientes, tipos de operação e hosts e Convenções HTTP: qual host e qual chave usar; Money sem float, datas, IDs, timeouts e limites de corpo.
  2. Autenticação HMAC: pedido canônico, nonce, janela de 300 s e a ordem de verificação. Reproduza os vetores antes de qualquer outra coisa.
  3. Idempotência e repetição e Erros: o que repetir e o que não repetir.
  4. Índice de endpoints, Depósitos e Saques: corpos, estados e respostas.
  5. Webhooks, Receptor passo a passo e Recuperação com GET /events: verificar, deduplicar, fazer fetch-back e fechar lacunas.
  6. Estados no seu produto, Arquitetura do conector e Reconciliar com o seu livro.
  7. Sandbox, Receitas por caminho e Suíte de conformidade: provar cada caminho antes de produção.
  8. Rede, allowlist e mTLS, Segredos e vazamento, Checklist de go-live e Dia do corte e rollback.

A parte de dinheiro (saldos, ciclos de depósito e saque, tarifas, estornos) e a de painel (chaves de API, webhooks no painel, revisão) ficam na documentação do painel: Modelo de dinheiro, Chaves de API e Webhooks no painel.

O que está disponível hoje

Conferido contra o código em 2026-10-18 (API 17908a2, webhooks 332d6cb, ledger 6679cce, regras 3a0f8a3).

Item Estado hoje
Método pix em BRL, depósito e saque Disponível
Assinatura HMAC, escopos, idempotência, limites de taxa, erros problem+json, GET /v1/ping Disponível
POST/GET /v1/deposits, GET /v1/deposits/{id}, POST /v1/deposits/{id}/cancel Disponível (Depósitos)
POST/GET /v1/withdrawals, GET /v1/withdrawals/{id}, POST /v1/withdrawals/{id}/cancel Disponível (Saques)
GET /v1/events, /reconciliation, /balances, /currencies, /rules, /players/{ref}/limits e POST /v1/rules/change-requests Disponível (Índice de endpoints)
Webhooks assinados: 17 tipos de evento, 9 de depósito e 8 de saque Disponível (Catálogo de eventos)
Rotas /v1/sandbox/* Só em operação Teste; em operação Real respondem 404
deposit.refunded e deposit.chargeback Só no sandbox hoje: nenhum caminho de produção leva um depósito a esses estados
deposit.returned e withdrawal.returned Existem em produção (devolução na revisão e devolução informada pelo banco)
Câmbio, recebimentos e recall de saque Reservado no contrato: as rotas respondem de forma previsível, sem efeito (Rotas e campos reservados)

Não disponível

Cartão, boleto, transferência bancária, wire e SWIFT. Pedir um desses métodos devolve 400 method_not_enabled. Cripto é aceita e habilitada por operação (Cripto). Use GET /v1/currencies para saber o que a sua operação aceita.

Não disponível

O Dracma não oferece: tarifas descontadas do crédito (o crédito é o valor cheio; a tarifa é por contrato e sem extrato), aporte de caixa (o caixa só cresce por depósito pago ou devolução), página de status pública, lista de IPs de saída dos webhooks e aplicação da lista de IPs às chamadas (a lista é registrada, mas hoje não é aplicada).

Exemplos

O caminho mais curto até a primeira chamada que funciona:

  1. Peça ao Dracma o tenant e a operação Teste (Do zero ao go-live).
  2. Crie a chave key_test_ no painel (Chaves de API).
  3. Reproduza os vetores de assinatura com um dos exemplos e chame GET /v1/ping.
  4. Siga o Primeiro depósito e primeiro saque.

Erros e casos de borda

  • Operação Real move dinheiro real em qualquer instância, inclusive no hml. Só a operação Teste é isolada do PSP. Veja Ambientes, tipos de operação e hosts.
  • O webhook só avisa. O dinheiro se move depois do fetch-back, nunca pelo corpo do webhook.
  • Estado, evento ou código desconhecido nunca move dinheiro. Trate como não terminal e confirme depois.
  • Fonte de verdade. Em dúvida sobre o que a API faz hoje, rode no sandbox. Em dúvida sobre o contrato, vale o contrato.

Veja também