Ambientes, tipos de operação e hosts

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

Duas coisas independentes definem onde uma chamada cai: o ambiente (a instância do Dracma, hml ou prd) e o tipo da operação (Teste ou Real). Esta página mostra a combinação de cada um, os hosts, o que cada host publica e como você descobre onde a sua chave está.

O que é

  • Ambiente é a instância do Dracma que atende o host. Existem duas: hml (homologação, no domínio dracma.cfd) e prd (produção, em um domínio que o Dracma informa no onboarding).
  • Tipo da operação é uma propriedade da operação, escolhida ao criá-la:
Tipo no painel environment na API Chave PSP Dinheiro
Teste sandbox key_test_… simulador do Dracma nunca se move; o PIX é sintético
Real production key_live_… PSP de verdade real, em qualquer instância

Dinheiro real

Uma operação Real move dinheiro de verdade também no hml. Quem testa paga o PIX e recebe o saque de fato. Só uma operação Teste é isolada do PSP real. O selo HML · sandbox do painel descreve a instância, não o tipo da operação: ele também aparece quando você olha uma operação Real do hml.

Quando usar

  • Desenvolva e valide o conector em hml com uma operação Teste: nenhum dinheiro, simulador completo, rotas /v1/sandbox/* abertas.
  • Vá para prd com uma operação Real quando o checklist de go-live estiver completo.
  • Use uma operação Real no hml só quando o Dracma tiver habilitado essa via para o seu tenant e você quiser exercitar o PSP de verdade antes da produção. Isso exige as mesmas cautelas de produção.

O fluxo do seu lado é: Teste no hml, Real (opcional) no hml, Real em prd. Cada passo pede um pedido e uma chave próprios. Veja De Teste para Real.

Como funciona

Hosts

Cada papel tem um host. No hml eles são fixos; em prd o Dracma informa o domínio-base no onboarding e os nomes seguem o mesmo padrão (api., auth., painel. sob o mesmo domínio-base).

Papel Host no hml Em prd Quem usa O que atende
API de operações Teste api.dracma.cfd não existe seu conector /v1/* com chaves key_test_; /v1/sandbox/* aberto
API de operações Real api-live.dracma.cfd api. do domínio de produção seu conector /v1/* com chaves key_live_; /v1/sandbox/* sempre 404
Login auth.dracma.cfd auth. do domínio de produção pessoas cadastro, login, conta, convite
Painel painel.dracma.cfd painel. do domínio de produção pessoas painel do operador
Callback dos PSPs cb.dracma.cfd domínio de callback de produção os PSPs recebe a confirmação de pagamento. Não é seu: não chame nem configure
Portal de desenvolvedores (este guia) developers.dracma.cfd — quem integra documentação estática da API, llms.txt e openapi.yaml
Documentação do painel docs.dracma.cfd — quem usa o painel documentação estática

Não existe host sandbox.. Os exemplos do guia usam $DRACMA_BASE_URL para você colocar o host certo.

Matriz instância × tipo

Instância Tipo Host da API Prefixo da chave /v1/sandbox/* PSP Dinheiro real
hml Teste api. key_test_ aberto simulador não
hml Real api-live. key_live_ 404 PSP real sim
prd Teste não existe — — — —
prd Real api. do domínio de produção key_live_ 404 PSP real sim

Não disponível

O Dracma não cria operação Teste em prd. O pedido volta 422 com environment_not_allowed. O Teste do integrador vive no hml. Em prd só existe operação Real.

O que cada host publica

A API pública é só /v1/*. Qualquer outro caminho nos hosts da API recebe 404 sem corpo. O mesmo vale para /v1/sandbox/* nos hosts de operação Real. O guia e o contrato não descrevem outras rotas porque elas não são publicadas.

  • O corpo de um pedido tem teto de 1 MB na borda (a API aplica um teto menor; veja Convenções HTTP).
  • O host de login atende as páginas de cadastro, login, conta e convite e os endereços OIDC que o painel usa. A API de serviço do login nunca é pública.
  • O painel e o login só falam HTTPS.

Webhooks fora de produção

Em hml e em qualquer ambiente que não seja produção, o host da URL do seu webhook precisa ser de um domínio reservado (.test, .invalid, .example) ou de um domínio que o Dracma tenha habilitado para você. Isso vale também para a operação Real do hml.

Peça no onboarding a liberação do domínio do seu conector de homologação. Túneis públicos temporários (ngrok e semelhantes) não funcionam. Em produção a regra é outra: veja Seu endpoint.

Exemplos

Descobrir o ambiente: GET /v1/ping

GET /v1/ping aceita qualquer chave válida e devolve o ambiente e a operação derivados da chave:

{ "ok": true, "operation_id": "0192a3b4-0000-7000-8000-0000000000a1", "environment": "sandbox", "server_time": "2026-10-18T12:00:00Z" }

environment é sandbox para operação Teste e production para Real. Compare server_time com o seu relógio: um desvio acima de 5 s derruba a assinatura (janela de 300 s) muito antes de chegar a esse ponto.

Três sinais independentes dizem onde você está:

  1. Prefixo da chave: key_test_ é Teste; key_live_ é Real.
  2. environment no ping: sandbox ou production.
  3. Selo do painel: HML · sandbox ou PRD · produção, no topo. A lista de operações mostra o tipo (Teste ou Real) de cada uma.
flowchart TD A["Chamei a API com uma chave"] --> B{"Resposta"} B -- "401 unknown_key" --> C["Chave de um ambiente em outro host.<br/>key_test_ só em api.dracma.cfd,<br/>key_live_ só no host de operação Real"] B -- "200 no ping" --> D{"environment"} D -- "sandbox" --> E["Operação Teste: nenhum dinheiro se move"] D -- "production" --> F["Operação Real: dinheiro real"] B -- "404 em /v1/sandbox/*" --> G["Host de operação Real ou prd:<br/>sandbox nunca existe aí"]

Erros e casos de borda

O que você vê Causa O que fazer
401 unknown_key A chave pertence ao outro tipo ou ambiente (por exemplo key_test_ no host de operação Real), tem formato inválido ou foi revogada Confira o host contra a matriz. Use GET /v1/ping com a chave correta
404 sem corpo em /v1/sandbox/... O host é de operação Real ou de prd Rodar rotas de simulação só no host de Teste
404 sem corpo em outro caminho Só /v1/* é publicado Corrija o caminho
422 environment_not_allowed ao criar operação Ambiente não permitido na instância: prd não cria Teste Crie o Teste no hml
Webhook não entrega no hml Host fora dos reservados e não habilitado Peça a liberação do domínio no onboarding

Em produção, um 403 sem corpo problem+json vindo da borda (antes da API) indicaria uma restrição de origem aplicada à instância. Veja Rede, allowlist e mTLS.

Não disponível

Uma única operação não troca de tipo: não existe converter Teste em Real. A operação Real é outra operação, com outra chave. Veja De Teste para Real.

Veja também