Dados de teste

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

Que CPF, e-mail, chave PIX e valores usar na operação Teste, e o que nunca usar. Nada aqui é de uma pessoa real, e nada chega a ninguém.

O que é

Os dados de teste têm três regras:

  1. Documento: um CPF gerado, com os dois dígitos verificadores válidos e sem titular real conhecido.
  2. E-mail e domínios: só domínios reservados (.test, .invalid, .example). É a API que impõe: numa operação Teste, um player.email fora desses domínios responde 400 validation_failed com reason: reserved_domain_required.
  3. Valores: inteiros na menor unidade, como em produção. Só o valor terminado em 77 tem significado especial no simulador (saque que espera por você, em Receitas por caminho).

Nunca use dados de uma pessoa real

Nem o seu CPF, nem o seu e-mail, nem o de um cliente. Um e-mail de pessoa real em dados de teste é um risco: dado pessoal em ambiente de teste e, se algum dia a operação for ligada a um destino de verdade, e-mail enviado a quem não pediu. O domínio de produção do seu produto também não entra em fixture.

Quando usar

Em fixtures, seeds de teste, testes de carga e na demonstração para o time. Vale igualmente para o hml (operação Teste) e para a sua máquina de desenvolvimento.

Como funciona

CPF de teste

O Dracma valida o documento do jogador pelo módulo 11. Um CPF é recusado com 422 document_invalid quando:

  • não tem exatamente 11 dígitos;
  • tem todos os dígitos iguais (11111111111);
  • um dos dois dígitos verificadores não confere.

Para gerar um CPF válido de teste, use o script exemplos/shell/cpf-teste.sh, que também tem teste:

bash exemplos/shell/cpf-teste.sh 3        # imprime 3 CPFs de teste, só dígitos

O algoritmo, para você portar à sua linguagem:

  1. Sorteie 9 dígitos.
  2. Primeiro dígito verificador: some cada dígito multiplicado por 10, 9, 8, 7, 6, 5, 4, 3, 2; seja r o resto dessa soma por 11. O dígito é 0 se r < 2, senão 11 - r.
  3. Segundo dígito verificador: repita sobre os 10 dígitos, com pesos 11, 10, 9, ..., 2.
  4. Descarte o resultado se os 11 dígitos forem todos iguais.

Estes CPFs são válidos nas receitas e nos exemplos: 52998224725 e 11144477735. Eles passam no dígito verificador, mas são conhecidos e públicos: use-os só como dado fictício, nunca como o documento de alguém.

Dois pontos de atenção:

  • O documento do jogador é fixado no primeiro uso de um external_ref: um CPF diferente depois dá 422 document_mismatch. Em teste, use um external_ref novo para cada CPF novo.
  • Na chave PIX do saque, key_type: cpf exige o mesmo CPF do jogador. Veja a Receita 8.

E-mail e outros dados do jogador

  • player.email: local@dominio.tld com até 254 caracteres e domínio terminado em .test, .invalid ou .example. Por exemplo jogador1@operador.test.
  • player.name: até 120 caracteres. Use nomes obviamente fictícios.
  • player.ip: endereços de documentação (203.0.113.0/24, 198.51.100.0/24, 2001:db8::/32). Eles servem para a regra de titularidade do saque; sem player.ip, o saque nunca é automático.
  • player.external_ref: o seu id interno, imutável e opaco. Nunca e-mail, telefone ou CPF.
  • Quais campos a operação exige para criar depósito: GET /v1/currencies (deposit_requirements). Veja Ping e moedas.
  • URL de webhook: https://pagamentos.operador.example/dracma/webhook. O Dracma entrega fora de produção apenas a domínios reservados ou liberados para você no onboarding (Seu endpoint).

Numa operação Real (inclusive no hml) a regra do e-mail é a de produção, sem restrição de domínio. Isso não é licença para usar e-mail de verdade em teste: use a operação Teste.

E-mail real no hml: painel e convites

O e-mail que não é reservado também existe no hml: o do painel. No hml e em produção, o código de acesso e o convite do administrador da sua empresa são entregues de verdade, por e-mail. Por isso:

  • Informe, no onboarding, o e-mail real de quem vai administrar. É para esse endereço que o convite chega (Conta, login e dispositivos).
  • Não use um endereço fictício (.test, .invalid, .example) para convidar uma pessoa do painel: o convite não chegaria a ninguém.
  • Não misture os dois mundos. O e-mail do painel é de gente. O player.email da API é sempre fictício.

Valores

  • Dinheiro é sempre string de inteiro na menor unidade: "5000" é R$ 50,00. Nunca use ponto flutuante (Convenções HTTP).
  • O mínimo e o máximo por depósito e por saque vêm das regras da operação (GET /v1/rules). Valores abaixo ou acima dão 422 amount_below_minimum ou 422 amount_above_maximum.
  • Único valor mágico do simulador: saque terminado em 77 na menor unidade ("2077") fica em processing até você agir. Qualquer outro valor é pago sozinho. Depósitos não têm valor mágico: o desfecho se controla por pay, expire e pelo corpo do pay.
  • Para provar AMOUNT_MISMATCH, pague com paid_amount diferente do valor do depósito.

Chaves PIX de teste

key_type Valor de teste Titular que o simulador devolve
cpf O CPF do próprio jogador O próprio CPF (titularidade confirmada)
cpf Outro CPF de teste Esse CPF (não bate com o jogador: document_mismatch)
cnpj Um CNPJ válido de teste O próprio CNPJ (para pessoa física, document_mismatch)
email, phone, random chave@operador.test, +5511999990000, qualquer texto Um CPF sintético, estável para a mesma chave, que não é o do jogador

O nome do titular que o simulador devolve é sempre fictício.

Exemplos

{
  "external_ref": "jogador-0001",
  "document": {"type": "CPF", "number": "52998224725", "country": "BR"},
  "name": "Jogador Teste",
  "email": "jogador1@operador.test",
  "ip": "203.0.113.10"
}

Erros e casos de borda

Você vê Causa O que fazer
400 validation_failed, reason: reserved_domain_required, campo player.email E-mail fora de .test, .invalid e .example numa operação Teste Troque o domínio
400 validation_failed, reason: format E-mail sem local@dominio.tld ou com nome de exibição Envie só o endereço
400 validation_failed, reason: required_by_operation A operação exige um campo que você não mandou Leia deposit_requirements em GET /v1/currencies
422 document_invalid CPF com dígito errado, tamanho errado ou todos iguais Gere o CPF com o script
422 document_mismatch Documento diferente do já fixado para esse external_ref, ou chave PIX de outro titular Use um external_ref novo, ou a chave do próprio jogador

Veja também