Visão geral

A integração é uma API HTTP com corpo em JSON. Todo o fluxo cabe em três passos: gerar uma chave, criar uma sessão de jogo para o seu jogador e abrir a launchUrl devolvida.

1. Em Integração → Credenciais, gere uma chave agk_…. Ela aparece uma única vez.
2. Cadastre o jogador em Jogadores — o saldo dele passa a ser a fonte de verdade das sessões.
3. Chame POST /api/v1/sessions e abra a launchUrl em um iframe ou em uma nova aba.

Endereço base de todas as chamadas:

{{origem}}

Só HTTPS é aceito em produção. As respostas de erro sempre trazem error e, quando ajuda, message.

Authorization: Bearer agk_sua_chave_aqui
Content-Type: application/json

A chave pertence ao agente que a criou: sessões, jogadores e transações de outro agente respondem 404, nunca 403 — assim a API não confirma a existência de tokens alheios. Revogar a chave em Credenciais derruba imediatamente as integrações que a usam.

GET /api/v1/auth/me

Confere a credencial sem criar sessão. Útil no seu deploy.

curl -H "Authorization: Bearer agk_sua_chave_aqui" \
  {{origem}}/api/v1/auth/me

{
  "authenticated": true,
  "type": "agent-api-key",
  "agent": {
    "id": 2,
    "code": "operadora-x",
    "name": "Operadora X",
    "role": "agent",
    "status": "active"
  }
}

GET /api/v1/providers

GET /api/v1/games

GET /api/v1/games?provider=popok

GET /api/v1/games/{provider}/{gameId}

Resposta de um jogo:

{
  "provider": "popok",
  "gameId": 332,
  "code": "fortune_empire",
  "name": "Fortune Empire",
  "currency": "BRL",
  "languages": ["pt-BR"],
  "enabled": true,
  "matrix": { "rows": 5, "columns": 6 },
  "coverUrl": "{{origem}}/game-covers/popok/332?v=9f2c…"
}

currency e languages são fechados: a criação da sessão recusa qualquer valor fora dessa lista.

GET /game-covers/{provider}/{gameId}

A capa do jogo, para o lobby. Vem em coverUrl já como endereço absoluto, e o campo só aparece nos jogos que têm uma capa cadastrada — quem monta a vitrine não precisa de uma segunda chamada. A rota é aberta, aceita /{gameId}.png como sinônimo e responde a If-None-Match.

O ?v= é a impressão digital do arquivo: quando a capa é trocada no painel, o endereço muda junto e o cache do navegador não tem como devolver a antiga. Guardar a URL sem ele, ou copiar a imagem para o seu servidor, é abrir mão dessa troca.

curl -X POST {{origem}}/api/v1/sessions \
  -H "Authorization: Bearer agk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "popok",
    "gameId": 332,
    "playerId": "usuario-123",
    "currency": "BRL",
    "language": "pt-BR",
    "mode": "demo",
    "returnUrl": "https://seu-site.com/lobby"
  }'

Resposta 201

{
  "sessionToken": "0hV4v0Nn…",
  "game": { "provider": "popok", "gameId": 332, "name": "Fortune Empire" },
  "playerId": "usuario-123",
  "mode": "demo",
  "launchUrl": "{{origem}}/play/0hV4v0Nn…?mode=demo&lang=pt-BR",
  "expiresAt": "2026-08-10T21:00:00+00:00",
  "walletMode": "internal"
}

Abra a launchUrl em um iframe ou redirecione o jogador para ela. Não monte essa URL à mão e não reaproveite o mesmo sessionToken para outro jogador: cada sessão é amarrada ao jogo, ao jogador e à validade que você pediu.

<iframe src="LAUNCH_URL" allow="autoplay; fullscreen"
        allowfullscreen width="100%" height="720"></iframe>

Regras válidas para qualquer uma dessas URLs:

• Esquema https, no máximo 8192 caracteres.
• Sem usuário e senha embutidos (https://user:senha@…).
• Host, caminho e parâmetros exatamente os da provedora.

PG Soft metadata.pgLaunchUrl

O caminho tem de ser /{gameId}/index.html do próprio jogo da sessão e a query precisa trazer o token ot. Recusa: invalid_pg_launch_url.

{
  "provider": "pgsoft",
  "gameId": 2100928,
  "playerId": "usuario-123",
  "metadata": {
    "pgLaunchUrl": "https://m.exemplo.com/2100928/index.html?ot=…&l=pt"
  }
}

A resposta de sessões PG Soft traz também localUrl, que abre o cliente servido daqui em vez do remoto.

Evolution metadata.evolutionLaunchUrl

Nos jogos que sabemos lançar sozinhos, deixe o campo de fora: o servidor pede um lançamento novo à vitrine a cada sessão, porque a URL expira em minutos. Se a vitrine não responder, a criação falha com 502 evolution_launch_failed — repita a chamada.

Quando você mesmo informa a URL, ela é conferida contra o jogo e a mesa da sessão; apontar para outra mesa, outro jogo ou outro host devolve invalid_evolution_launch_url. Para o Bac Bo ao vivo, o endereço tem de estar em betconstructlatam.evo-games.com/frontend/evo/r2/ com provider=evolution, game=bacbo, table_id=BacBo00000000001 e um ua_launch_id no fragmento.

iSoftBet metadata.isoftbetLaunchUrl

Aceita apenas o Gem Roulette em modo fun, em static-fun-stable.isoftbet.com, com identifier=pulse_gem_roulette, licenseId=1015 e funmode=true. Recusa: invalid_isoftbet_launch_url.

InOut Games metadata.inoutLaunchUrl

Chicken Road 2, em chicken-road-two.inout.games/api/modes/game, com gameMode=chicken-road-two, o operatorId da integração, um authToken e currency igual à moeda da sessão — uma URL em outra moeda abriria o jogo com valores que não batem com a carteira. Recusa: invalid_inout_launch_url.

Spribe metadata.spribeUser / metadata.spribeToken

Opcionais no Aviator; sem eles a sessão usa as credenciais da demo. Não passam por validação de formato e não geram erro próprio.

GET /api/v1/sessions/{sessionToken}

Devolve os dados da sessão. O segredo da carteira nunca é exposto — apenas mode e baseUrl.

GET /api/v1/sessions/{sessionToken}/transactions?limit=100

Extrato das chamadas de carteira daquela sessão, para conciliação. limit vai de 1 a 500 (padrão 100).

GET /api/v1/sessions/{sessionToken}/pg-protocol

Diagnóstico do protocolo binário, disponível nas sessões PG Soft e Pragmatic. Campos sensíveis já vêm mascarados.

As três rotas exigem a chave e só enxergam sessões da sua própria conta.

Configuração seamless

{
  "provider": "popok",
  "gameId": 332,
  "playerId": "usuario-123",
  "mode": "real",
  "wallet": {
    "mode": "seamless",
    "baseUrl": "https://seu-site.com/api/wallet/",
    "token": "segredo-do-operador"
  }
}

A baseUrl precisa ser HTTPS (HTTP só é aceito quando aponta para localhost, em teste). O token volta para você em Authorization: Bearer a cada chamada.

O que chamamos no seu servidor

Campos comuns a todas: sessionToken, playerId, provider, gameId e currency.

POST https://seu-site.com/api/wallet/bet
Authorization: Bearer segredo-do-operador

{
  "sessionToken": "0hV4v0Nn…",
  "playerId": "usuario-123",
  "provider": "popok",
  "gameId": 332,
  "currency": "BRL",
  "transactionId": "b7f1…",
  "roundId": 4821,
  "amount": 0.20
}

O que devolver

{ "success": true, "balance": 999.80 }

balance é obrigatório e é o saldo depois da operação. Para recusar, responda {"success": false, "code": "insufficient_funds", "message": "…"} — a rodada é cancelada com essa mensagem. Um HTTP 5xx é tratado como indisponibilidade temporária e pode ser repetido.

Cada transactionId é gravado e reenviado de forma idempotente: se o mesmo chegar duas vezes, devolva o resultado da primeira em vez de debitar de novo.

Cabeçalhos e corpo

Content-Type: application/json
X-Webhook-Event: session.created
X-Webhook-Id: 5f3c9a…
X-Webhook-Signature: sha256=9d2b…

{
  "eventId": "5f3c9a…",
  "event": "session.created",
  "agentCode": "operadora-x",
  "sentAt": "2026-08-10T20:31:00+00:00",
  "data": { }
}

Eventos

Conferindo a assinatura

X-Webhook-Signature é o HMAC-SHA256 do corpo exato que chegou, com o segredo do webhook. Calcule sobre os bytes crus, antes de qualquer parse — reserializar o JSON muda a assinatura.

// Node.js / Express
const bruto = req.body;                       // Buffer, via express.raw()
const esperado = "sha256=" + require("crypto")
  .createHmac("sha256", SEGREDO_WEBHOOK)
  .update(bruto)
  .digest("hex");

const recebido = req.get("X-Webhook-Signature") || "";
if (!crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(recebido))) {
  return res.sendStatus(401);
}

// PHP
$bruto = file_get_contents('php://input');
$esperado = 'sha256=' . hash_hmac('sha256', $bruto, SEGREDO_WEBHOOK);
if (!hash_equals($esperado, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Responda 2xx assim que receber e processe depois. Como reenviamos após falha, o mesmo eventId pode chegar duas vezes — guarde-o e descarte repetições.

• A chave agk_… fica só no seu servidor — nunca no navegador nem em aplicativo distribuído.
• Uma chave por ambiente, para revogar a de teste sem parar a produção.
• O webhook confere a assinatura e responde 2xx rápido, guardando o eventId contra repetições.
• A carteira seamless trata transactionId de forma idempotente e devolve sempre balance.
• Sessões são criadas sob demanda, com expiresInSeconds curto o bastante para a sua operação.
• Você acompanha Sessões e Auditoria no painel para conferir o que a sua integração fez.