Checklist de go-live¶

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

Você só vai ao ar com a operação Real depois de cumprir esta lista na operação Teste. Cada item tem uma prova: saída de teste, print do painel, log ou dashboard, e não uma promessa. Item sem prova conta como não feito.

O que é¶

Um checklist único para as três frentes: o conector (Dev), o dinheiro (Fin) e o painel (Adm). Ele junta o que antes estava separado em lista geral, lista por operador e itens de painel.

Copie a lista para o seu tracker, preencha a prova de cada item e anexe o resultado ao registro de go-live descrito em Dia do corte e rollback.

Quando usar¶

Antes do pedido de operação Real (passo 10 da linha do tempo): as seções 1 a 9 se provam na operação Teste. A seção 10 se prova no painel e a seção 11 no dia do corte.

Como funciona¶

1. Conformidade¶

• [ ] Suíte de conformidade verde contra a operação Teste, rodada com a URL de webhook real do seu conector (Suíte de conformidade). Prova: saída com todos os casos aprovados e a data.
• [ ] Seu cliente reproduz os vetores de assinatura byte a byte (as três chamadas, os dois webhooks válidos e a recusa do negativo) no seu CI. Prova: teste no seu repositório, como os de Exemplos.
• [ ] GET /v1/ping com a chave de Teste devolve environment: "sandbox" e o operation_id esperado. Prova: saída do comando.

2. Chamadas¶

• [ ] Nonce por CSPRNG, 32 caracteres hexadecimais minúsculos, novo a cada requisição, inclusive em nova tentativa.
• [ ] Timestamp em segundos. Host com NTP e alerta de desvio acima de 5 s contra o server_time de GET /v1/ping. Prova: regra de alerta versionada.
• [ ] Timeout de cliente de 10 s.
• [ ] Todo POST leva Idempotency-Key. Em depósito e saque, Idempotency-Key = external_id, gravado no seu banco antes da chamada (outbox). Prova: teste que mata o processo entre a gravação e a chamada; o worker retoma com a mesma chave e cria um único objeto.
• [ ] Regra de ouro: 4xx não repete; 5xx, 429 e erro de rede repetem com a mesma chave; code desconhecido é tratado pela classe HTTP (Idempotência e repetição). Prova: caso de teste com POST /sandbox/outage {"down": true}: 503, depois retomada com a mesma chave sem duplicar.
• [ ] Valor convertido para a menor unidade sem float. Prova: teste de unidade com 50, 50.5, 0.01, 50.001 (recusa) e 1e3 (recusa).
• [ ] Dracma-Trace-Id registrado em todo log de chamada ao Dracma.

3. Webhooks¶

• [ ] Verificação da assinatura sobre o corpo cru, janela de 300 s, Dracma-Timestamp igual ao t=, aceita qualquer v1 com qualquer segredo ativo (lista para a rotação), comparação em tempo constante.
• [ ] Dracma-Event-Id igual ao id do corpo; senão 400.
• [ ] Deduplicação por Dracma-Event-Id com índice único e retenção de pelo menos 7 dias; duplicata devolve 200 sem efeito. Prova: POST /sandbox/webhooks/redeliver de um evento já processado: 200, saldo inalterado.
• [ ] Fetch-back obrigatório antes de mover dinheiro: o crédito sai do GET /deposits/{id}, nunca do corpo do webhook. Prova: um deposit.paid forjado, com assinatura válida, para um depósito pending na API não credita.
• [ ] No fetch-back, confere external_id (é seu), amount, currency e player_ref com o que gravou. Divergência: não credita, marca para revisão e alerta.
• [ ] Crédito e débito idempotentes por external_id: um depósito credita uma vez, mesmo com dois eventos para o mesmo objeto.
• [ ] Ordem não garantida: version menor ou igual ao já aplicado é ignorada, com 200.
• [ ] Leitor tolerante: tipo de evento, status, method ou campo desconhecido devolve 200, grava, não move dinheiro e é conferido depois.
• [ ] Responde em até 10 s; trabalho pesado vai para fila local.
• [ ] A rota do webhook não usa autenticação de usuário. O Dracma não publica lista de IPs de saída, então não filtre essa rota por IP de origem; a defesa é a assinatura mais o fetch-back (Seu endpoint).

4. Depósitos¶

• [ ] Só paid credita, pelo valor registrado na criação (Ciclo do depósito).
• [ ] under_review, pending, created e qualquer estado desconhecido não creditam. Prova: receitas de PAYER_MISMATCH e de valor divergente no Teste (Receitas).
• [ ] refunded e chargeback depois de paid: política definida e escrita. Recomendação: não mover automaticamente; abra uma exceção (needs_decision) com alerta e deixe uma pessoa decidir (Política de exceções).
• [ ] Pagamento depois de expirar ou cancelar (paid_amount em objeto terminal): não credita; vai para exceção.
• [ ] player.external_ref opaco e imutável; documento consistente entre depósito e saque.
• [ ] Exigências por operação lidas de GET /v1/currencies (method_details[].deposit_requirements) no boot e periodicamente. Prova: depósito sem o campo exigido volta 400 com reason: required_by_operation, tratado como recusa sem repetição.
• [ ] Fora de produção, e-mails de jogador só de domínio reservado (.test, .invalid, .example).
• [ ] Mostra ao jogador o instructions.pix.expires_at devolvido.

5. Saques¶

• [ ] Reserva do saldo do jogador antes do POST /withdrawals, na mesma transação que grava o external_id.
• [ ] A reserva só é devolvida em rejected, failed ou cancelled, confirmados por fetch-back, ou em 4xx conclusivo na criação. Nunca em timeout ou 5xx sem resposta conclusiva.
• [ ] paid finaliza a reserva e guarda psp_reference.
• [ ] player.ip com o IP do jogador em todo saque (sem ele o saque nunca é automático). Prova: no Teste, um saque dentro do limite da regra, com player.ip, vira approved.
• [ ] Chave PIX normalizada (tipos cpf, cnpj, email, phone, random; telefone em +55…). Prova: teste de unidade.
• [ ] returned depois de paid: política definida; recomendação de não recreditar automaticamente.
• [ ] 409 idempotency_key_reused no envio vira exceção, com a reserva mantida.
• [ ] review_requested: true quando a sua pré-checagem desconfiar (só torna a decisão mais restritiva).
• [ ] decision.reasons aparece para o seu time de suporte e risco; nenhum motivo de bloqueio vai ao jogador (mensagem genérica).
• [ ] Prova: no Teste, um saque acima do limite vai para under_review com AUTO_MULTIPLIER_EXCEEDED, e reject e fail devolvem a reserva exatamente uma vez.

6. Dinheiro: provas¶

• [ ] Uma reserva por saque. Repetir o POST com a mesma chave não cria segunda reserva nem segundo saque. Prova: o teste da seção 2 e uma consulta ao seu livro com uma linha de reserva por external_id.
• [ ] Uma devolução por saque. Receitas reject e fail no Teste: a reserva volta uma vez; repetir o evento não devolve de novo. Prova: livro do jogador antes e depois.
• [ ] Um crédito por depósito. Receita de redeliver: continua um crédito.
• [ ] O seu livro bate com o do Dracma. Um dia de Teste reconciliado nos dois lados, sem divergência (Reconciliar com o seu livro). Prova: relatório do dia, digest e assinatura conferidos, e o seu extrato por external_id.
• [ ] Limites conservadores configurados na operação Real. Leia a regra ativa em GET /v1/rules ou na tela "Regras e listas"; proponha a mudança pelo painel ou por POST /v1/rules/change-requests (escopo rules:propose). Endurecer vale na hora; afrouxar pede aprovação de outra pessoa e 24 h. Este guia não publica valores padrão. Prova: print da regra ativa e do pedido aprovado.
• [ ] Caixa inicial conferido em GET /v1/balances. O caixa de saques só cresce com depósitos pagos e devoluções. Prova: leitura de GET /v1/balances depois do primeiro depósito pago.

7. Recuperação e reconciliação¶

• [ ] Job de GET /events?after=<último evento> a cada 5 minutos, com cursor persistido, passando pelo mesmo dedup e fetch-back do webhook. Prova: teste com o receptor desligado durante um pagamento; o job credita uma vez em até 5 minutos (GET /events).
• [ ] Reconciliação diária por moeda (GET /reconciliation) com digest e assinatura conferidos.
• [ ] Alerta de divergência: todo paid do Dracma tem crédito ou débito seu, e vice-versa. Qualquer diferença abre incidente. Prova: um dia de Teste comparado, zero divergência.
• [ ] Alertas para: webhook com assinatura inválida, 401 ou 403 na sua saída, fila de exceções parada acima de 4 h, job de /events atrasado, desvio de relógio.
• [ ] A fila de exceções do seu produto tem permissão própria, confirmação forte e motivo. Prova: print e teste de permissão.

8. Segredos e rede¶

• [ ] Chave, segredo de webhook e demais segredos no cofre, entregues ao host pela ferramenta de deploy, arquivo 0400 do usuário do conector. Prova: stat do arquivo e busca por key_live_ no repositório e na imagem, sem resultado (Segredos e vazamento).
• [ ] O Dracma é chamado só do servidor; nenhum app ou navegador de jogador fala com ele.
• [ ] Logs não registram segredo, Dracma-Signature inteiro, documento completo nem chave PIX em claro (Dados pessoais).
• [ ] Opcional: saída para o host do Dracma restrita ao usuário do conector. Altamente recomendado em Real: a lista de IPs de origem da operação está cadastrada com os IPs públicos de saída fixos do conector (opcional, mas sem ela qualquer origem com a chave chama; veja Rede, allowlist e mTLS), e a URL do webhook está cadastrada (sem ela você não recebe avisos de pagamento).
• [ ] Rotação de chave e de segredo de webhook ensaiada no Teste sem downtime, com o verificador aceitando dois segredos ao mesmo tempo.
• [ ] Procedimento de emergência escrito: quem revoga a chave, quem pede a reposição, como a chave nova chega ao conector e quanto tempo isso leva (24 h de espera + aprovação).

9. Ambientes¶

• [ ] Homologação aponta para o host de Teste com key_test_; produção aponta para o host de Real com key_live_. Prova: chamar o host de Real com a chave de Teste devolve 401 unknown_key.
• [ ] Fixtures, seeds e testes usam só domínios reservados e documentos de teste; nenhum dado real de jogador fora de produção.
• [ ] Os testes automáticos não chamam /v1/sandbox/* contra a operação Real (essas rotas respondem 404).

10. Painel e equipe¶

• [ ] Pelo menos duas pessoas com acesso, cada uma com dois fatores e um fator forte. Convites pendentes não contam: a segunda pessoa precisa ter aceitado o convite. Prova: lista "Quem tem acesso" sem a pessoa em "Aguardando aceite" (Equipe e papéis).
• [ ] Operação Real aprovada e chave key_live_ revelada (janela de 24 h). Prova: GET /v1/ping com a chave nova devolve environment: "production" (De Teste para Real).
• [ ] Conexão de gateway ativa na operação Real. Prova: print da tela "Gateways" (Gateways).
• [ ] Webhook de produção cadastrado em https e primeiro segredo girado e instalado no receptor. Prova: evento entregue ao receptor de produção.
• [ ] Alertas configurados, no mínimo caixa baixo e webhook falhando (Alertas e e-mails). Prova: print da tela e um disparo de teste.
• [ ] Contatos de alerta de e-mail informados ao Dracma, porque o painel não os edita.
• [ ] Suspensão do saque automático ensaiada em operação Teste, com a segunda pessoa confirmando. Prova: registro na lista de emergências.

Exemplos¶

Linha de tracker preenchida:

Item	Responsável	Prova	Data
Dedup por Dracma-Event-Id	Dev	saída do redeliver: 200 sem crédito novo	2026-10-12
Limites conservadores	Fin	print da regra ativa e do pedido aprovado	2026-10-14
Gateway ativo	Adm	print de "Gateways"	2026-10-15

Erros e casos de borda¶

• Item que não se aplica: escreva por que não se aplica. Em branco conta como não feito.
• Prova antiga: refaça a prova se você mudou o conector, a regra ou a chave depois dela.
• Seção 10 sem pessoas suficientes: com uma só pessoa, os pedidos do painel não fecham. Convide a segunda antes de pedir a operação Real.

Veja também¶

• Dia do corte e rollback
• De Teste para Real
• Suíte de conformidade
• Referência rápida