Sessões de jogador

O seu servidor informa à plataforma quem é o jogador. Não existe login do sportsbook para os seus jogadores: a chamada abaixo é o login, autenticada pela sua chave de API. A plataforma encontra o jogador pelo seu id (ou o cria), abre uma sessão e devolve um launch token de uso único para o iframe.

Endpoint, servidor a servidor

POST /api/v1/integration/sessions

Launch token

uso único, 120 s

Sessão

12 h no máximo, com expiração por inatividade

Crie uma sessão

POST /api/v1/integration/sessions
Content-Type: application/json
X-Tenant-ID: demo-embed
X-API-Key: <sua chave de API de integração>

{"externalPlayerId": "player-42", "displayName": "Maria", "path": "/live", "locale": "pt-BR"}

Campo	Tipo
externalPlayerId	string	obrigatório	O id estável do jogador no seu sistema, até 128 caracteres. O mesmo id é sempre o mesmo jogador; é o playerId de toda chamada de carteira.
displayName	string	opcional	Exibido no sportsbook, até 64 caracteres. Atualizado quando muda. Padrão Player.
currency	string	opcional	Se enviado, deve ser a moeda do tenant.
cpf	string	tenants BR	O CPF do jogador, só dígitos ou formatado (529.982.247-25). Veja Brasil.
path	string	opcional	Link direto incluído na launchUrl: /, /live, /live/{sportId}, /sport/{sportId}, /competition/{id}, /event/{eventId}, /my-bets.
locale	string	opcional	en ou pt-BR, incluído na launchUrl. Padrão: o idioma do tenant.

Campos desconhecidos são recusados (400 validation), para que erros de digitação não passem em silêncio.

Resposta

200 OK:

{
  "launchToken": "lt_NIpjVSCtwQlG0iLUbF9T7WeY84YSVs3pVQeLxbbH1O0",
  "launchExpiresAt": "2026-10-16T03:01:22.081091Z",
  "launchUrl": "https://sportsbook.example.com/?tenant=demo-embed&launch=lt_NIpjVSCtwQlG0iLUbF9T7WeY84YSVs3pVQeLxbbH1O0&path=%2Flive&locale=pt-BR",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "player": {
    "id": "pl_bd387263c326f44e90808bde",
    "tenantId": "demo-embed",
    "externalId": "player-42",
    "status": "active",
    "displayName": "Maria",
    "currency": "USD",
    "kycStatus": "verified",
    "createdAt": "2026-10-16T02:43:38.465403Z"
  }
}

Campo
launchToken	Entregue à página: passe para o SDK de incorporação (opção launchToken ou setLaunchToken()). Uso único, expira em launchExpiresAt.
launchUrl	O mesmo token já em uma URL de iframe, para integrações sem o SDK.
token	O próprio token de sessão. Mantenha no seu servidor (ou ignore): nunca o coloque em uma URL ou em uma página. Continua na resposta por compatibilidade.
player	O registro do jogador na plataforma (resumido acima). kycStatus é verified porque a verificação de identidade é delegada a você, o que fica registrado como evidência.

A origem da launchUrl é a URL do sportsbook configurada na plataforma (SPORTSBOOK_URL); se não houver, a origem para a qual a sua requisição foi enviada.

Erros

Status	code	Quando
401	unauthorized	X-API-Key ausente ou errada, ou o tenant não tem chave. Toda falha é auditada com o IP de origem.
400	validation	Campo inválido; details.field diz qual (externalPlayerId, displayName, currency, cpf, path, locale), ou um campo desconhecido.
403	account_blocked	O jogador está bloqueado ou encerrado na plataforma.
403	prohibited_bettor, self_excluded	BR: o CPF está na lista de apostadores proibidos ou no sistema nacional de autoexclusão.
404	not_found	Tenant desconhecido (X-Tenant-ID).
503	unavailable	O tenant está suspenso, ou um provedor de compliance está fora do ar. Tente de novo mais tarde.

Launch tokens

O launch token é como a sessão chega ao iframe sem nunca ser posta em uma URL. O sportsbook o troca uma única vez, ao iniciar ou ao receber set_launch_token:

POST /api/v1/integration/launch
Content-Type: application/json
X-Tenant-ID: demo-embed

{"launchToken": "lt_NIpjVSCtwQlG0iLUbF9T7WeY84YSVs3pVQeLxbbH1O0"}

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…", "player": { "id": "pl_bd387263c326f44e90808bde", "…": "…" } }

Você nunca chama este endpoint; o iframe chama. Ele guarda o token de sessão em memória e no sessionStorage daquele iframe, e remove launch do próprio endereço antes de qualquer outra coisa.

Regra
Uso único	A troca marca o token como usado no mesmo comando do banco: uma segunda troca (uma URL repetida ou compartilhada, o histórico do navegador) recebe 401 com details.reason: "launch_token_used", e a repetição é auditada.
Expiração	120 segundos após a emissão (launchExpiresAt): 401, launch_token_expired. Crie a sessão logo antes de renderizar o sportsbook.
Tenant	Um token só vale para o próprio tenant: em outro é launch_token_invalid, como um token desconhecido.
Sessão	A sessão ainda precisa estar ativa: uma sessão encerrada ou expirada dá 401 (unauthorized ou session_expired).
Armazenamento	Só um hash SHA-256 do token é guardado. Tokens usados e expirados são apagados um dia depois.

Se a troca falhar na inicialização, o sportsbook continua anônimo e envia à sua página um evento error (code = o motivo) seguido de session_expired, para que o onSessionExpired do SDK busque um token novo.

Duração e renovação da sessão

• Uma sessão dura no máximo 12 horas e termina após o tempo de inatividade da jurisdição (60 minutos para tenants .com, 30 minutos para o Brasil). Toda chamada autenticada do iframe (saldo, apostas, Minhas Apostas) conta como atividade; navegar pelas cotações não conta.
• Cada chamada a integration/sessions abre uma sessão nova; as sessões anteriores do jogador continuam valendo até expirarem. Quando o jogador sair do seu site, chame logout() no SDK para encerrar também a sessão do sportsbook.
• Para renovar, chame integration/sessions de novo e envie o novo launch token ao iframe. Com o SDK, devolva-o em onSessionExpired:

BookmakerSportsbook.mount('#sportsbook', {
  url: 'https://sportsbook.example.com',
  tenant: 'seu-tenant',
  launchToken,
  // chamado quando a sessão do sportsbook termina (inatividade, expiração, token recusado)
  onSessionExpired: async () => {
    const res = await fetch('/meu-site/sportsbook-launch', { method: 'POST' }); // seu endpoint
    return res.ok ? (await res.json()).launchToken : null; // null: continua deslogado
  },
});

O mesmo mecanismo faz o login do jogador sem recarregar o iframe: depois do seu diálogo de login, chame sb.setLaunchToken(novoLaunchToken).

Brasil: CPF

Tenants brasileiros precisam enviar cpf em toda sessão. A plataforma valida o CPF e o confere na lista de apostadores proibidos do operador e no sistema nacional de autoexclusão antes de abrir a sessão. Se o jogador já existir com outro CPF, a chamada é recusada (400 validation, campo cpf). Para os demais tenants, cpf é opcional e, quando enviado, é conferido do mesmo jeito.

Nota

As apostas de quota fixa estão atualmente proibidas no Brasil (MP 1.394/2026); os tenants brasileiros ficam atrás de um kill switch de jurisdição que está fechado em produção.