Índice de endpoints¶

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

Esta página lista as 31 rotas que um operador chama: 30 em /v1 mais o documento OpenAPI. Para cada uma você vê o método, o escopo da chave, o operationId do documento OpenAPI e a página que explica a rota em detalhe. Use-a para achar rápido onde uma rota está descrita, ou para ir do operationId de um cliente gerado até o texto.

O que é¶

A API pública do Dracma tem 30 rotas sob /v1: 21 de negócio e leitura (o ping entra aqui) e 9 de simulação (sandbox). O documento OpenAPI é a 31ª rota e fica fora de /v1.

Grupo	Rotas	Para que serve
Saúde e cadastro	2	ping e currencies: testar a credencial e descobrir moedas e métodos da sua operação
Depósitos	4	criar a cobrança PIX, consultar, listar e cancelar
Saques	5	pedir o pagamento, consultar, listar, cancelar e recall (reservado)
Jogadores e saldos	2	limites do jogador e saldos da operação
Regras	2	ler o conjunto vigente e propor mudança
Reconciliação e eventos	2	relatório diário assinado e recuperação de eventos
Câmbio e recebimentos	4	rotas reservadas: nenhuma operação tem câmbio nem trilho bancário habilitado
Sandbox	9	simulam pagamento, expiração, estorno, saída de saque, queda e reentrega; só existem em operação Teste
OpenAPI	1	GET /openapi.yaml

Toda rota sob /v1 exige as quatro credenciais de assinatura (veja Autenticação), e todo POST exige Idempotency-Key (veja Idempotência). O prefixo /v1 faz parte do caminho assinado.

Quando usar¶

• Quer saber qual escopo a chave precisa para uma rota: veja a coluna "Escopo".
• Gerou um cliente a partir do OpenAPI e precisa achar o texto de uma operação: procure o operationId.
• Quer o contrato campo a campo de um objeto: vá a Objetos e campos.

Como funciona¶

O escopo vem da chave. As regras são estas:

1. GET (e HEAD) exige o escopo read, exceto GET /v1/ping, que aceita qualquer chave válida.
2. POST de depósito (inclusive as ações de sandbox de depósito) exige deposits:write.
3. POST de saque (inclusive recall e as ações de sandbox de saque) exige withdrawals:write.
4. POST /v1/rules/change-requests exige rules:propose.
5. POST /v1/fx/quotes, POST /v1/sandbox/outage e POST /v1/sandbox/webhooks/redeliver aceitam deposits:write ou withdrawals:write. Em POST /v1/fx/quotes, o purpose do corpo decide qual dos dois vale.
6. Escopo ausente responde 403 insufficient_scope. Método ou rota de escrita que não está nesta lista é negado.

GET /v1/deposits, GET /v1/withdrawals, GET /v1/events e GET /v1/receipts (sem id) usam o balde de listagem do rate limit. Veja Limites e quotas.

As 31 rotas¶

#	Método e caminho	Escopo	operationId	Descrição
1	GET /openapi.yaml	nenhum	—	OpenAPI
2	GET /v1/ping	qualquer chave válida	ping	Ping e moedas
3	GET /v1/currencies	read	listarMoedas	Ping e moedas
4	POST /v1/deposits	deposits:write	criarDeposito	Depósitos
5	GET /v1/deposits	read	listarDepositos	Depósitos
6	GET /v1/deposits/{id}	read	obterDeposito	Depósitos
7	POST /v1/deposits/{id}/cancel	deposits:write	cancelarDeposito	Depósitos
8	POST /v1/withdrawals	withdrawals:write	criarSaque	Saques
9	GET /v1/withdrawals	read	listarSaques	Saques
10	GET /v1/withdrawals/{id}	read	obterSaque	Saques
11	POST /v1/withdrawals/{id}/cancel	withdrawals:write	cancelarSaque	Saques
12	POST /v1/withdrawals/{id}/recall	withdrawals:write	pedirRecallDeSaque	Rotas e campos reservados
13	POST /v1/fx/quotes	deposits:write ou withdrawals:write	criarCotacao	Rotas e campos reservados
14	GET /v1/fx/quotes/{id}	read	obterCotacao	Rotas e campos reservados
15	GET /v1/receipts	read	listarRecebimentos	Rotas e campos reservados
16	GET /v1/receipts/{id}	read	obterRecebimento	Rotas e campos reservados
17	GET /v1/players/{external_ref}/limits	read	limitesDoJogador	Limites do jogador e saldos
18	GET /v1/balances	read	saldosDaOperacao	Limites do jogador e saldos
19	GET /v1/rules	read	obterRegras	Regras (API)
20	POST /v1/rules/change-requests	rules:propose	pedirMudancaDeRegras	Regras (API)
21	GET /v1/reconciliation	read	reconciliacao	Reconciliação
22	GET /v1/events	read	listarEventos	Recuperação com GET /events
23	POST /v1/sandbox/deposits/{id}/pay	deposits:write	sandboxPagarDeposito	Sandbox
24	POST /v1/sandbox/deposits/{id}/expire	deposits:write	sandboxExpirarDeposito	Sandbox
25	POST /v1/sandbox/deposits/{id}/refund	deposits:write	sandboxEstornarDeposito	Sandbox
26	POST /v1/sandbox/deposits/{id}/chargeback	deposits:write	sandboxChargebackDeposito	Sandbox
27	POST /v1/sandbox/withdrawals/{id}/{action}	withdrawals:write	sandboxAgirNoSaque	Sandbox
28	POST /v1/sandbox/bank-transfers/incoming	deposits:write	sandboxTransferenciaRecebida	Rotas e campos reservados
29	POST /v1/sandbox/outage	deposits:write ou withdrawals:write	sandboxQueda	Sandbox
30	GET /v1/sandbox/webhooks	read	sandboxWebhooksEnviados	Sandbox
31	POST /v1/sandbox/webhooks/redeliver	deposits:write ou withdrawals:write	sandboxReentregar	Sandbox

As rotas 23 a 31 respondem 404 not_found em operação Real: a rota não existe para você, nunca devolve 403. Isso vale mesmo que a chave tenha o escopo certo.

Exemplos¶

Do operationId à página: um cliente gerado com o método obterDeposito chama GET /v1/deposits/{id}, que está descrito em Depósitos. Um cliente com reconciliacao chama GET /v1/reconciliation, descrito em Reconciliação.

Da necessidade à rota:

Eu quero...	Rota
Saber se a credencial e o relógio estão certos	GET /v1/ping
Saber quais moedas e métodos minha operação aceita	GET /v1/currencies
Cobrar um jogador	POST /v1/deposits
Confirmar um pagamento antes de creditar	GET /v1/deposits/{id}
Pagar um jogador	POST /v1/withdrawals
Descobrir o destino de um POST cuja resposta se perdeu	GET /v1/deposits?external_id= ou GET /v1/withdrawals?external_id=
Ver quanto cabe no saque automático de um jogador	GET /v1/players/{external_ref}/limits
Monitorar o caixa da operação	GET /v1/balances
Provar que seu livro e o do Dracma batem	GET /v1/reconciliation

Erros e casos de borda¶

• Rota que não existe, ou método que a rota não aceita, responde 404 not_found. Um PUT em /v1/deposits é 404, não 405.
• Caminhos fora de /v1 (exceto o documento OpenAPI) não são públicos.
• Rota de sandbox em operação Real responde 404 not_found.
• A lista completa de code e reason está em Erros.

Veja também¶

• Convenções HTTP: Money, datas, IDs e cabeçalhos.
• Paginação e filtros
• Objetos e campos
• Divergências conhecidas