FAQ

Credenciais e Autenticação

Qual a diferença entre API Key e Secret Key?

A API Key (op_live_...) é um identificador público — ela aparece nos headers de todas as suas requisições como X-Operator-Id e identifica seu operador. A Secret Key (sk_live_...) é um segredo que nunca deve sair do seu servidor — ela é usada para gerar a assinatura HMAC. Pense na API Key como seu "identificador" e na Secret Key como a "chave criptográfica" que prova que você é quem diz ser.

Por que não usar Bearer token como em outras APIs?

Tokens Bearer podem ser roubados e reutilizados até expirarem. Com HMAC-SHA256, cada requisição tem uma assinatura única que inclui o timestamp atual — mesmo que alguém intercepte a requisição, não pode reutilizá-la (o servidor rejeita timestamps a mais de 5 minutos do atual). Isso oferece segurança muito maior para transações financeiras.

Recebi "Invalid signature". O que verificar?

Verifique nesta ordem:

Timestamp em milissegundos? X-Timestamp deve ter 13 dígitos. Use Date.now() (Node.js), int(time.time() * 1000) (Python), (int)(microtime(true) * 1000) (PHP)
Fórmula correta? data = apiKey + timestamp + JSON.stringify(body) — sem separadores
Body idêntico? O JSON usado para calcular a assinatura deve ser exatamente o mesmo enviado no request
Credenciais corretas? Confirme que X-Operator-Id contém a API Key e o HMAC usa a Secret Key

Recebi "Request expired". O que fazer?

O timestamp enviado está a mais de 5 minutos do horário atual do servidor FourPlay. Verifique:

date -u         # hora atual do servidor em UTC
timedatectl status  # status NTP (Linux/systemd)
ntpq -p         # estado da sincronização NTP

Se o NTP estiver inativo, ative com sudo timedatectl set-ntp true.

Modelo Seamless Wallet

O que é "seamless wallet" e por que a FourPlay o usa?

No modelo seamless wallet, o operador mantém o saldo do jogador no próprio sistema — não na FourPlay. Durante o jogo, a FourPlay consulta e atualiza o saldo via callbacks em tempo real. Isso permite que o jogador use o mesmo saldo em jogos FourPlay e em outros produtos do operador, sem precisar mover fundos entre carteiras.

Como a FourPlay sabe qual operador está criando a sessão?

Pelo header X-Operator-Id presente nas requisições. Cada operador tem uma API Key única. A assinatura HMAC prova que quem enviou a requisição conhece a Secret Key correspondente àquela API Key.

O callbackUrl é definido onde?

O callbackUrl é registrado no Portal Admin ao configurar sua conta de operador. É a URL base do seu servidor que a FourPlay usará como prefixo para todos os callbacks (/wallet/balance, /wallet/debit, /wallet/credit, /wallet/rollback).

Callbacks de Wallet

Os callbacks são obrigatórios? O que acontece se não responder?

Os callbacks são obrigatórios para que o jogo funcione. Se /wallet/balance não responder, o jogo não iniciará a rodada. Se /wallet/debit não responder dentro de 5 segundos, a FourPlay pode acionar um /wallet/rollback para cancelar a operação.

Meu servidor de callback precisa ser HTTPS?

Em produção, sim. A FourPlay requer TLS 1.2+ no servidor de callbacks em produção. No Sandbox (usando ngrok, por exemplo), HTTPS também é necessário — o ngrok fornece o HTTPS automaticamente.

O que fazer se o mesmo `gameId` chegar duplicado?

Retorne 200 com os dados da transação original — não processe novamente. Isso é idempotência e é o comportamento esperado. Nunca retorne 409 ou 4xx em caso de duplicata.

O que é o rollback e quando ocorre?

O rollback é chamado quando uma operação precisa ser desfeita. Cenários comuns:

Timeout no callback /wallet/debit (sem resposta em 5s)
Erro interno no jogo após o debit já ter sido processado

Você deve reverter o debit e retornar 200. O FourPlay não lê o body da resposta do rollback, apenas verifica HTTP 200.

Meu callback de balance está sendo chamado com frequência alta. É normal?

Sim — o /wallet/balance é chamado antes de cada rodada. Em jogos de alta frequência, isso pode ocorrer várias vezes por minuto. Recomendações:

Mantenha queries de banco de dados otimizadas no caminho de balance
Use cache com TTL curto (1-2 segundos em Redis) se necessário

Sessões e JWT

O token expira? O que fazer quando expirar?

Sim, o token expira 24 horas após a criação. O jogo detecta a expiração. O jogador precisa iniciar uma nova sessão pelo site do operador. Não é possível renovar um token expirado — crie uma nova sessão com POST /api/operator/session/create.

Posso decodificar o JWT localmente?

Sim, para leitura dos claims (playerId, operatorId, username, isDemo, iat, exp):

const [, payload] = token.split('.');
const claims = JSON.parse(Buffer.from(payload, 'base64url').toString());

Para validação e autorização, use o endpoint /api/operator/session/validate.

Qual a diferença entre `playerId` e `externalPlayerId`?

externalPlayerId — ID do jogador no sistema do operador. Você define ao criar a sessão.
playerId — UUID interno do banco do FourPlay Mines. É gerado automaticamente e retornado nos claims do JWT. Os callbacks recebem externalPlayerId.

Operacional e Go-Live

Como testar sem expor meu servidor localmente?

Use o ngrok:

ngrok http 3000  # substitua 3000 pela porta do seu servidor local

Copie a URL HTTPS gerada (ex: https://a1b2c3.ngrok.io) e use como base do callbackUrl. Veja o guia completo em Sandbox → Testar com Servidor Local.

Como funciona o jogo Mines especificamente?

Mines é um jogo de campo minado onde o jogador:

Define o número de minas (1–24) e o valor da aposta
Clica em células do grid para revelar diamantes ou minas
Pode "cashout" a qualquer momento para receber o multiplicador atual
Se clicar em uma mina, perde a aposta

Do ponto de vista da integração: o /wallet/debit ocorre quando o jogador confirma a aposta. O /wallet/credit ocorre no cashout (vitória). O /wallet/rollback ocorre em caso de erro.

Posso embutir o jogo em iframe em mobile?

Sim. O jogo é responsivo. Recomendações para iframe mobile:

<iframe
  src="https://mines.fourplay.studio/?token=eyJ..."
  width="100%"
  height="100dvh"
  frameborder="0"
  allow="fullscreen"
  style="border: none;"
></iframe>

Use height: 100dvh (dynamic viewport height) para lidar corretamente com a barra de endereço do browser mobile.

Como entrar em contato para suporte?

Para dúvidas técnicas ou solicitação de ativação de conta:

E-mail: suporte@fourplay.studio
Portal: https://admin.fourplay.studio

On this page