Sessões de jogador

Sua plataforma autentica o jogador e realiza cadastro, validação de CPF, KYC e verificação de elegibilidade antes de solicitar uma sessão do sportsbook. Seu servidor identifica esse jogador existente ao OrbiSportbook por externalPlayerId; não há cadastro ou login de jogador separado no iframe.

O endpoint encontra ou cria um registro interno do sportsbook vinculado a esse id e devolve um launch token de uso único. Criar esse registro não é cadastrar o jogador nem verificar sua identidade pelo OrbiSportbook.

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 HTTP/1.1
Host: api.orbisportbook.com
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 no mesmo tenant é 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	obsoleto	Aceito e ignorado por compatibilidade. Não envie CPF; o campo não é validado nem armazenado.
`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://api.orbisportbook.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`	Registro interno do sportsbook vinculado ao seu jogador (resumido acima). Para jogadores criados por esta integração, `kycStatus: verified` registra a delegação ao operador. Não é resultado de KYC, análise documental ou certificação realizada pelo OrbiSportbook.

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`, `path`, `locale`), ou um campo desconhecido.
403	`account_blocked`	O jogador está bloqueado ou encerrado na plataforma.
403	`account_paused`, `account_closed`	Uma restrição local existente impede a sessão.
404	`not_found`	Tenant desconhecido (`X-Tenant-ID`).
503	`unavailable`	O tenant está suspenso ou o serviço está temporariamente indisponível. Tente novamente depois.

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:

OrbiSportbook.mount('#sportsbook', {
  url: 'https://api.orbisportbook.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).

Compatibilidade da API atual

A sessão usa o externalPlayerId estável da plataforma do cliente, isolado por tenant. O mesmo ID no mesmo tenant reutiliza o jogador; em tenants diferentes identifica jogadores distintos.
CPF não é exigido em nenhum perfil, inclusive BR. O campo legado cpf é aceito como string e ignorado: não é validado, consultado em listas nem armazenado pela integração.
Jogadores antigos continuam usando o mesmo ID interno. Um CPF já armazenado não precisa ser reenviado e não participa das verificações de CPF para apostas desses jogadores integrados.
Cadastro, CPF, KYC e elegibilidade permanecem sob responsabilidade da plataforma do cliente. Não envie CPF nem documentos de identidade na sessão.
Bloqueios, encerramentos, restrições locais e os demais controles de apostas continuam aplicáveis.
kycStatus: verified registra a delegação ao operador; não significa que o OrbiSportbook realizou KYC.