Boas práticas
Checklist de produção
Marque tudo antes de subir produção. Cada item linka para a seção correspondente.
| Item |
|---|
clientReference único e determinístico em toda criação. Ver Idempotência. |
Dedupe de callback por id + status, não só id. |
| Storage de dedupe persistente (Redis/DB), não em memória local. |
| TTL do dedupe ≥ 30 dias. |
| Item |
|---|
callbackUrl configurado em todo POST /pix, POST /withdraw, POST /internal-transfer. |
Handler responde 2xx em menos de 5s. Processamento pesado em fila/worker. |
| Testado com payload simulado via curl + ngrok. |
| Endpoint restringido ao IP oficial da Magen (peça ao suporte). |
Inspeção via GET /user/callbacks configurada para auditoria. |
| Item |
|---|
virtualAccount enviado em todas as criações. |
Listagem filtrada por virtualAccount. |
Roteamento do callback usa tx.virtualAccount, com fallback para tenant desconhecido. |
| Onboarding de novo tenant não exige deploy (mapping em DB ou config dinâmica). |
| Item |
|---|
Valores armazenados como inteiro em centavos ou NUMERIC(15,2), nunca FLOAT. |
| Conversão centavos ↔ reais isolada em helper, testada. |
| Validação no callback: valor recebido bate com valor esperado do pedido. |
Tarifa (serviceFeeCharged) contabilizada na conciliação. |
| Limites mínimos respeitados (cobrança ≥ R$ 1, saque ≥ R$ 0,01, QR ≥ R$ 0,10). |
| Item |
|---|
Token em Secret Manager, não em .env versionado. |
| Token nunca exposto ao front-end. |
Logger mascara header Authorization e campos sensíveis (payerDocument, pixKey). |
| Tokens separados para sandbox e produção. |
| Plano de rotação documentado (quando, quem, como). |
| DICT consultado antes de saque por chave em valores altos. |
| Item |
|---|
Retry só em 5xx e 429, com backoff exponencial e jitter. |
4xx (exceto 429) não retentado. |
Timeout tratado com consulta por clientReference antes de recriar. |
requestId da Magen logado em todo erro. |
Erros traduzidos pro usuário final (não expõe message cru). |
| Item |
|---|
Iteração de listagem usa hasNextPage, não data.length. |
limit ≤ 100. |
Job diário de conciliação cruzando GET /user/transactions com tabela de pedidos local. |
Para volumes grandes, POST /user/report agendado. |
| Divergências de status disparam alerta. |
| Item |
|---|
Logs estruturados com id local + id Magen + endToEndId + clientReference. |
| Métricas: taxa de sucesso de criação, latência p95, erros por tipo. |
| Alertas: erro 5xx > X% em janela curta, callback não processado > N minutos. |
Trace distribuído (OpenTelemetry) propagando requestId da Magen. |
| Item |
|---|
| Sandbox usado em desenvolvimento e testes. |
| Produção só com valores e clientes reais. |
Variáveis de ambiente separadas (MAGEN_TOKEN, MAGEN_BASE_URL). |
| Webhook em produção via URL estável (não túnel temporário). |
| Item |
|---|
| Runbook para incidente: callback parou de chegar, erro 5xx persistente, saldo divergente. |
| Contato direto com suporte Magen (canal, SLA). |
Procedimento de reenvio de callback documentado (POST /user/callbacks/resend). |
| Plano de rollback de feature que toque saque ou transferência. |
