Testes e Debug

Versão: 1.0
Owner: Engenharia SOFIA
Última revisão: 2026
Aplicável a: Dev Integradores, Backend\

Esta página descreve como:

• Gerar eventos de teste
• Validar assinatura
• Simular webhooks
• Resolver erros comuns (401, 409, 429, 5xx)

Base da API:

https://api.v1sofia.com/api

1. Obter Token do Parceiro

curl -X POST "https://api.v1sofia.com/api/partners/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "seu-email@dominio.com",
    "password": "SUA_SENHA"
  }'

Salvar token como:

SOFIA_SUPABASE_JWT

Validar sessão:

curl "https://api.v1sofia.com/api/partners/me" \
  -H "Authorization: Bearer $SOFIA_SUPABASE_JWT"

Se falhar aqui, não avance.

2. Testar postMessage

Gerar envelope de teste:

curl -X POST "https://api.v1sofia.com/api/partners/me/casino/postmessage/test" \
  -H "Authorization: Bearer $SOFIA_SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "table_id": "TBL-01",
    "balance_cents": 105000,
    "external_user_id": "test-user",
    "session_id": "test-session"
  }'

Retorna:

• envelope
• signing_string

Use o envelope para validar fluxo no browser.

3. Testar Webhook Interno

Criar evento de teste:

curl -X POST "https://api.v1sofia.com/api/partners/me/casino/webhook/test" \
  -H "Authorization: Bearer $SOFIA_SUPABASE_JWT"

Listar eventos:

curl "https://api.v1sofia.com/api/partners/me/casino/webhook/events?limit=20" \
  -H "Authorization: Bearer $SOFIA_SUPABASE_JWT"

Reprocessar:

curl -X POST "https://api.v1sofia.com/api/partners/me/casino/webhook/events/<event_internal_id>/reprocess" \
  -H "Authorization: Bearer $SOFIA_SUPABASE_JWT"

4. Validar Assinatura (Webhook)

Header esperado:

x-sofia-signature: sha256=<hex>

Assinatura deve ser feita sobre raw body.

Erro comum:

• Usar JSON.stringify(req.body) para validar assinatura.

Correto:

crypto.createHmac('sha256', secret).update(rawBody).digest('hex')

Checklist:

• Capturar raw body antes do body parser
• Comparar com timingSafeEqual
• Não logar assinatura

5. Validar Assinatura (postMessage)

String assinada:

<ts>.<table_id>.<balance_cents>.<user_external_id>.<session_id>.<nonce>

Erros comuns:

• Timestamp em segundos (deve ser ms)
• Nonce reutilizado
• Ordem incorreta da string
• Segredo errado

6. Como Interpretar Erros

401 – Não autorizado

Causas:

• Assinatura inválida
• Timestamp fora da janela
• Token expirado

Correção:

• Revalidar segredo
• Sincronizar clock (NTP)
• Renovar token

403 – Bloqueado

Causas:

• IP fora da allowlist
• Origin inválido
• Permissão insuficiente

Correção:

• Conferir allowlist
• Conferir event.origin
• Conferir papel do parceiro

409 – Conflito (Duplicidade)

postMessage

• Nonce reutilizado

Webhook

• event_id já processado

Correção:

• Gerar nonce novo por evento
• Implementar idempotência

429 – Rate Limit

Correção:

• Aplicar backoff exponencial
• Respeitar Retry-After
• Reduzir polling

5xx – Erro do servidor

Correção:

• Retry com limite
• Monitorar recorrência
• Não entrar em loop infinito

7. Logs e Observabilidade

Prioridade de diagnóstico:

1. Status code
2. Body de erro
3. Logs estruturados do backend
4. Sentry (quando configurado)

Procure por:

• CASINO_WEBHOOK
• CASINO_POSTMESSAGE
• invalid_signature
• stale_timestamp
• replay_detected

8. Checklist de Produção

Antes de ativar produção:

• Assinatura validada
• Idempotência implementada
• Origin validado
• Clock sincronizado
• Segredos em environment
• Retry controlado
• Logs sem PII
• Monitoramento ativo

9. Fluxo Mental Correto

Se falha:

• 401 → erro seu
• 403 → bloqueio de segurança
• 409 → duplicidade
• 429 → você está chamando demais
• 5xx → falha transitória

Corrija a causa, não aumente retry.