Ping e moedas¶

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

Duas rotas de leitura que você chama no boot do conector. GET /v1/ping prova que a credencial, o relógio e o ambiente estão certos. GET /v1/currencies diz quais moedas e métodos a sua operação aceita e o que o POST /v1/deposits exige dela.

O que é¶

Rota	Escopo	operationId	O que devolve
GET /v1/ping	qualquer chave válida	ping	operação e ambiente derivados da chave, mais o relógio do servidor
GET /v1/currencies	read	listarMoedas	moedas habilitadas na sua operação, com os métodos e as exigências de cada um

Nenhuma das duas cria nem altera nada. O ambiente e a operação vêm da chave, nunca de um campo do pedido.

Quando usar¶

• No boot do conector e em cada deploy: chame GET /v1/ping. Se o pedido volta 200, a chave existe, a assinatura está certa e o relógio está dentro da janela.
• Para detectar desvio de relógio: compare server_time com o seu relógio. Alerte quando a diferença passar de 5 s. A janela de aceitação da assinatura é de ±300 s, mas desvio perto disso causa 401 intermitente.
• Para confirmar o ambiente: environment é sandbox numa operação Teste e production numa operação Real. Se vier o contrário do esperado, você está com a chave ou o host errado (veja Ambientes, tipos de operação e hosts).
• Antes de oferecer um método ao jogador: leia GET /v1/currencies. Só ofereça o que a lista traz.
• Antes de montar o corpo do POST /v1/deposits: leia method_details para saber que campos do jogador a operação exige.

Como funciona¶

GET /v1/ping¶

Resposta 200:

Campo	Tipo	Conteúdo
ok	booleano	sempre true
operation_id	texto	UUID da operação a que a chave pertence
environment	texto	sandbox (operação Teste) ou production (operação Real)
server_time	texto	instante do servidor, RFC 3339 em UTC com segundos

O ping não é afetado pela queda simulada de POST /v1/sandbox/outage: ele continua 200 mesmo com a queda ligada. Qualquer chave válida pode chamá-lo, sem exigência de escopo.

GET /v1/currencies¶

Resposta 200 com {"data": [Moeda, ...]}. Cada Moeda tem:

Campo	Tipo	Significado
code	texto	código da moeda. Hoje só BRL
kind	texto	fiat ou crypto. Hoje só fiat
exponent	inteiro	casas da menor unidade. BRL tem 2: R$ 50,00 é "5000" em Money.amount
methods	lista de texto	métodos habilitados para a moeda nesta operação. Hoje só pix
method_details	lista de objetos	um item por método de methods, na mesma ordem. Veja abaixo
rails	—	nunca vem. Está no contrato 1.1.0 para trilhos bancários, que não existem hoje

A lista é a interseção de duas coisas: o que o Dracma suporta e o que a sua operação habilitou. Moeda ou método fora do que o Dracma suporta nunca aparece, mesmo que a operação o tenha configurado. Operação sem moeda habilitada recebe {"data": []}. Use exponent para converter valores: nunca fixe "2 casas" no código.

method_details e as exigências por operação¶

Cada item de method_details tem:

Campo	Tipo	Significado
method	texto	o método a que o item se refere
deposit_requirements	lista de texto	campos do Jogador que o POST /v1/deposits desta operação exige
psp_notes	lista de texto	avisos informativos sobre o PSP de depósito da operação

• deposit_requirements é um subconjunto de player.name, player.email, player.ip, player.device_id, sempre nessa ordem. Método sem exigência vem com a lista vazia, nunca null.
• psp_notes hoje pode conter payer_identity_unavailable: o PSP de depósito não informa o documento do pagador real. Espere mais depósitos em under_review com o motivo PAYER_UNKNOWN. Nota desconhecida é informativa: ignore.
• O Dracma escolhe o PSP de cada operação no onboarding. Você não escolhe e não precisa saber qual é: leia as exigências aqui. Veja a matriz de PSPs em PSPs.

method_details é um acréscimo do Dracma ao contrato 1.1.0 (campo aditivo). Está no documento OpenAPI servido (schema DetalheMetodo) e não no contrato do briefing. Veja Divergências conhecidas.

Leia as exigências no boot e a cada hora. Não as fixe no código: elas mudam com a configuração da operação.

Exemplos¶

Ping, resposta 200 de uma operação Teste:

{
  "ok": true,
  "operation_id": "0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
  "environment": "sandbox",
  "server_time": "2026-10-18T15:04:05Z"
}

Um item de data em GET /v1/currencies, para uma operação cujo PSP de depósito exige nome e e-mail do jogador:

{
  "code": "BRL",
  "kind": "fiat",
  "exponent": 2,
  "methods": ["pix"],
  "method_details": [
    {
      "method": "pix",
      "deposit_requirements": ["player.name", "player.email"],
      "psp_notes": ["payer_identity_unavailable"]
    }
  ]
}

Para uma operação que não exige nada além do básico, deposit_requirements e psp_notes vêm como [].

Pedido assinado, no formato dos demais exemplos da referência (valores de assinatura ilustrativos):

GET /v1/currencies HTTP/1.1
Host: api.example.test
Dracma-Key-Id: key_test_01J9EXEMPLO
Dracma-Timestamp: 1790000000
Dracma-Nonce: 0123456789abcdef0123456789abcdef
Dracma-Signature: v1=<assinatura>

Erros e casos de borda¶

Situação	Resposta
Assinatura, relógio, nonce ou chave inválidos	401 com invalid_signature, timestamp_out_of_window, replayed_nonce ou unknown_key
Chave sem o escopo read em GET /v1/currencies	403 insufficient_scope
Chave key_live_ num host de Teste, ou o contrário	401 unknown_key. É assim que você descobre o ambiente errado
Banco ou dependência da API fora	503 service_unavailable, com Retry-After. Repita
Muitas chamadas	429 rate_limited, com Retry-After

• GET /v1/currencies nunca devolve uma resposta sem as exigências de method_details: se a API não consegue lê-las, responde 503 e registra o problema, em vez de entregar uma lista que enganaria o conector.
• Um método ausente de methods responde 400 method_not_enabled no POST /v1/deposits; uma moeda ausente responde 400 currency_not_enabled.
• Valor desconhecido em kind, methods ou psp_notes é informativo: aplique o leitor tolerante (veja Convenções HTTP).

Veja também¶

• Depósitos: o que acontece quando uma exigência não é cumprida.
• Autenticação HMAC
• Ambientes, tipos de operação e hosts
• Objetos e campos