Tenants e operações

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

Um tenant é a sua empresa no Dracma e uma operação é cada marca, país e ambiente que você integra. Nesta tela você cria operações de Teste (saem na hora) e de Real (dependem da aprovação de outra pessoa), acompanha os pedidos e revela a primeira chave. Tenants novos são criados pela equipe do Dracma.

O que é

  • Tenant: o espaço da sua empresa. Reúne as operações e as pessoas que as administram. Quem gere os tenants do Dracma vê todos; você vê os tenants de que é dono.
  • Operação: uma integração completa, com as suas chaves, regras, webhook e saldos. Tem um tipo:
    • Teste: simulador, chave key_test_…, nenhum dinheiro se move;
    • Real: gateway de verdade, chave key_live_…, dinheiro de verdade.
  • Nome (slug): de 2 a 63 caracteres, só letras minúsculas, números e hífen, começando por letra ou número. O nome de tenant e o de operação são únicos em todo o Dracma, não só dentro do seu tenant. Uma convenção que evita colisão: <marca>-<país>-<hml|prd>.

Situação da operação, como a tela mostra:

Situação Significa
Configurando A operação foi criada, mas algum passo de provisionamento ainda não terminou (veja abaixo).
Ativa Todos os passos terminaram.
Suspensa A operação está bloqueada pela equipe do Dracma. A API responde 403 com operation_suspended.

Situação de um pedido de operação Real:

Situação Significa
Aguardando aprovação Ninguém decidiu ainda.
Aprovado e criado Foi aprovado e a operação existe.
Recusado Uma pessoa da equipe do Dracma recusou.
Cancelado Quem pediu desistiu.
Falhou ao criar Foi aprovado, mas a criação falhou; nada foi criado. Peça um novo pedido ou fale com o suporte.

Quando usar

Use Tenants e operações para criar uma operação nova: outra marca, outro país, ou a operação Real depois de homologar a integração em Teste. Quem pode criar:

  • o dono do tenant (quem criou o tenant ou o Administrador que aceitou o convite do Dracma);
  • a equipe do Dracma, que também cria tenants. Quem cria um tenant vira administrador (dono) dele.

Os demais papéis não veem o botão Nova operação. O item do menu Tenants e operações só aparece para quem é dono de algum tenant ou integra a equipe do Dracma.

Como fazer

Primeiro acesso: o convite ao administrador

O primeiro administrador do tenant entra por convite, nunca por cadastro aberto.

sequenceDiagram participant D as Equipe do Dracma participant P as Painel participant A as Administrador do operador participant I as Login do Dracma D->>P: Cria o tenant (vira administrador) e informa o e-mail do administrador P->>I: Pede o convite I-->>A: E-mail com o link do convite (72 h, uso único) A->>I: Abre o link, entra com 2 fatores e aceita I-->>P: Convite aceito Note over A,P: A pessoa passa a ser dona do tenant A->>P: Cria a operação Teste e pede a chave
  1. A equipe do Dracma cria o tenant (a pessoa que cria vira administrador dele) e, se quiser, informa o e-mail do seu administrador: o e-mail é opcional e gera um convite adicional. O Dracma não cria a conta nem recebe a senha dele.
  2. O administrador recebe um e-mail com um link. O link vale 72 horas e só pode ser usado uma vez. Se vencer ou for perdido, a equipe do Dracma reenvia (até 5 vezes, com pelo menos 60 segundos entre os reenvios); cada reenvio invalida o link anterior.
  3. Ele abre o link, entra (ou cria a conta) com pelo menos dois fatores e aceita o convite. O e-mail do convite precisa ser o e-mail verificado da conta.
  4. Ao aceitar, ele vira dono do tenant (junto com quem criou) e passa a ver Tenants e operações.
  5. Pessoas da equipe do Dracma não aceitam o convite do operador, e quem criou o convite não pode aceitá-lo.

Na homologação o convite também chega a um e-mail de verdade. Informe o endereço real do administrador, não um endereço de teste.

O dono convida o restante da equipe pela tela Usuários e papéis, com o mesmo tipo de convite: veja Equipe e papéis.

Depois que o tenant tem dono ativo, a equipe do Dracma que não é dona dele não cria mais operações de Teste nele (a resposta é tenant_has_owner): é o dono quem cria e quem recebe a chave. Quem criou o tenant e é dono continua podendo criar.

Criar uma operação de Teste

  1. Abra Tenants e operações e clique em Nova operação.
  2. Escolha o tenant e o nome da operação.
  3. Em Tipo, deixe Teste ("Simulador, chave key_test_. Nenhum dinheiro real. Sai na hora").
  4. Se já tiver, preencha a URL do webhook. O formulário não pede lista de IPs.
  5. Se a confirmação de identidade estiver vencida, use Confirmar identidade agora antes de enviar.
  6. Clique em Criar operação. A operação aparece como Configurando e o painel mostra o aviso Operação criada com o botão Revelar chave.

Os campos do formulário:

Campo Regra
Tenant Só aparecem os tenants em que você pode criar operação.
Nome da operação Slug de 2 a 63 caracteres, único no Dracma.
Tipo Teste ou Real. As opções dependem da instância (veja abaixo).
URL do webhook Opcional. https://, sem usuário e senha, até 512 caracteres, com domínio público: localhost, endereço IP privado ou de loopback e nomes sem ponto são recusados.
Motivo Só para Real: de 10 a 1000 caracteres.

IP liberado e webhook: opcionais, altamente recomendados

A operação nasce sem lista de IPs e pode nascer sem URL de webhook, e isso é permitido: sem IP liberado, qualquer origem com a chave válida chama a API; sem webhook, a operação não recebe avisos de pagamento. É o que deixa o teste livre. Em operação Real informe os dois: o painel avisa enquanto faltarem (com Lembrar depois por 7 dias) e, após as primeiras chamadas, sugere Bloquear para estes IPs. Veja IPs do conector e Webhooks.

Tipos permitidos por instância:

Instância Teste Real
Desenvolvimento sim não
Homologação sim só se o ambiente estiver habilitado para isso; senão a criação é recusada com environment_not_allowed
Produção não sim

Em produção, portanto, não existe operação de Teste: o Teste do operador vive na homologação. Veja Ambientes, tipos de operação e hosts.

Fora de produção, o endereço do webhook também passa pela política de destinos de teste. Não use endereços de túnel: peça no onboarding a liberação do domínio do seu receptor. Veja Seu endpoint.

Criar uma operação Real

A operação Real passa por um pedido com a aprovação de outra pessoa.

stateDiagram-v2 [*] --> Aguardando: Você pede (motivo + confirmação) Aguardando --> Criado: Uma pessoa da equipe do Dracma aprova Aguardando --> Recusado: Uma pessoa da equipe do Dracma recusa Aguardando --> Cancelado: Quem pediu cancela Criado --> Falhou: A criação falha Criado --> [*]: Quem pediu revela a chave
  1. No formulário, escolha Real, escreva o motivo (de 10 a 1000 caracteres: para que serve a operação) e preencha IPs e webhook como no Teste.
  2. Clique em Criar operação. O pedido entra em Aguardando aprovação e aparece na tabela do tenant com essa situação e em Seus pedidos.
  3. Uma pessoa da equipe do Dracma abre Tenants e operações, vê o pedido em Aguardando a sua aprovação e escolhe Aprovar ou Recusar, com um motivo opcional. Ela precisa de confirmação recente.
  4. Aprovado, a operação é criada na hora e o pedido passa a Aprovado e criado. Não há espera de 24 h neste pedido.
  5. Em Seus pedidos, você (quem pediu) clica em Revelar chave.

Regras do pedido:

  • Quem pediu nunca aprova o próprio pedido. A tela só mostra os botões de voto para outra pessoa.
  • Só quem pediu cancela, e só enquanto estiver Aguardando aprovação (botão Cancelar pedido).
  • Um voto de recusa encerra o pedido.
  • Para pedir uma nova operação depois de uma recusa, abra outro pedido.

O que a operação ganha ao ser criada

Ao ser criada, a operação recebe:

  • moeda BRL com o método PIX;
  • nenhuma lista de IPs (sem restrição de IP até você cadastrar; recomendado em Real);
  • a primeira chave de API, com os quatro escopos: Criar depósitos, Pedir saques, Ler dados e Propor mudança de regra;
  • o conjunto de regras inicial do Dracma, já em vigor (não é preciso aprová-lo). Qualquer mudança depois dele é por pedido, como descrito em Regras, listas e emergência;
  • o vínculo de permissões das pessoas da operação;
  • o endereço de webhook, se você informou a URL (sem aprovação nem espera de 24 h; mudar a URL depois passa por pedido, veja Webhooks no painel).

Os três últimos itens são feitos em segundo plano. Até terminarem, a operação aparece como Configurando. Se um passo falha (um serviço fora do ar, por exemplo), o Dracma tenta de novo sozinho, com esperas crescentes de 5 segundos até 10 minutos, e a operação não é perdida.

Exigências do gateway

Os dados do jogador que o gateway de depósito exige (deposit_requirements em GET /v1/currencies) são declarados pelo Dracma junto com a configuração do gateway, não pelo formulário da operação. Numa operação criada só pelo painel, a lista pode vir vazia até o Dracma declará-la, e a coluna Gateway de entrada mostra —. Se um depósito for recusado com required_by_operation, o erro diz qual campo faltou; peça ao suporte para conferir as exigências da operação. Veja Ping e moedas.

Espere a situação Ativa antes de integrar. Se a operação continuar em Configurando por mais de alguns minutos, algum passo está falhando: acione o suporte com o nome da operação.

Revelar a primeira chave

  • Teste: o aviso Operação criada traz o botão Revelar chave.
  • Real: o botão está em Seus pedidos, na linha do pedido Aprovado e criado.

A chave (key_test_… ou key_live_…, mais o segredo que começa com sk_test_ ou sk_live_) é mostrada uma única vez, só para quem criou a operação (Teste) ou fez o pedido (Real), em até 24 horas e com confirmação recente. Copie para um cofre antes de sair da tela: ela não é exibida de novo.

Se a janela vencer (reveal_expired) ou a chave já tiver sido mostrada (already_revealed), peça outra chave em Chaves de API.

Editar, apagar ou suspender

Não disponível

O painel não edita nem apaga tenants e operações, e não tem botão "Suspender operação". Para mudar o nome, apagar ou suspender uma operação, peça ao suporte do Dracma. Uma operação suspensa pela equipe do Dracma aparece como Suspensa e a API responde 403 com operation_suspended em todas as rotas.

O botão de contenção que você tem no painel é Suspender automático, que desliga a aprovação automática de saques de uma moeda. Veja Regras, listas e emergência. Para parar o uso de uma chave, revogue a chave.

Exemplos

Formulário de uma operação de Teste, com dados fictícios:

Campo Valor
Tenant acme
Nome da operação acme-br-hml
Tipo Teste
URL do webhook https://webhooks.acme.example/dracma

Mensagens que o formulário pode mostrar:

Mensagem Causa
"Use de 2 a 63 caracteres: letras minúsculas, números e hífen, começando por letra ou número." Nome fora do padrão.
"A URL do webhook deve começar com https:// e não pode ter usuário ou senha." URL com http:// ou com credencial.
"Escreva o motivo com 10 a 1000 caracteres (obrigatório para operação real)." Real sem motivo.

Erros e casos de borda

Mensagem Causa O que fazer
"Já existe um tenant com esse nome." O nome do tenant está em uso. Escolha outro nome.
"Já existe uma operação com esse nome neste tenant." O nome da operação está em uso (a unicidade vale para todo o Dracma, apesar do texto). Escolha outro nome.
"Este tipo de operação não é permitido neste ambiente." Teste em produção, ou Real numa instância sem esse tipo habilitado (environment_not_allowed). Crie o tipo certo para a instância.
"Quem pediu não pode aprovar o próprio pedido." Você tentou votar no seu pedido (self_review_forbidden). Peça a outra pessoa.
"Você já votou neste pedido." Voto repetido (already_voted). Nenhuma.
"Confirme com o fator forte para concluir." Confirmação recente vencida (step_up_required). Use Confirmar identidade agora e repita.
"A chave já foi mostrada e não pode ser mostrada de novo." already_revealed. Peça outra chave.
"O prazo para revelar a chave venceu." reveal_expired. Peça outra chave.
"Sem permissão para esta ação." Seu papel não permite (forbidden). Peça a um Administrador.
"Tenant, operação ou pedido não encontrado." Item de outro tenant ou inexistente (not_found). Confira o tenant.
"Serviço indisponível agora. Tente de novo em instantes." Dependência fora do ar (service_unavailable). Repita em instantes.
"Executor indisponível agora" O serviço de gateways não respondeu. Repita em instantes.

Casos de borda:

  • Duas pessoas, um pedido. Com uma só pessoa na equipe do Dracma que pode aprovar, quem pediu não consegue aprovar; peça que outra pessoa dessa equipe esteja disponível.
  • Pedido aprovado, operação não criada. O pedido fica Falhou ao criar e nada é criado. Abra um novo pedido; se repetir, acione o suporte.
  • Operação em "Configurando" para sempre. Um passo repete a falha. O motivo mais comum é um endereço de webhook recusado fora de produção. Veja Seu endpoint e acione o suporte.
  • Convite vencido. Peça o reenvio à equipe do Dracma (veja o fluxo do convite acima).

Veja também