Integração com agentes de IA

Este é o ponto de partida para entregar a integração a um agente de programação. Ele reúne o contexto que o agente precisa, a ordem de implementação e a evidência necessária para considerar a integração pronta.

Para o agente: leia este guia e os contratos vinculados antes de editar o sistema do operador. A origem hospedada atualmente atende staging; o nome de um ambiente de cliente como production não transforma esse deployment em produção comercial.

• Baixar este guia em Markdown
• Índice para agentes — llms.txt
• Manifesto de integração em JSON
• Contrato OpenAPI da carteira
• Contrato OpenAPI de agregadores

1. Entenda o que está sendo integrado

O OrbiSportbook entrega um sportsbook em iframe: odds, mercados, boletim, apostas, liquidações e cash-out. O cassino mantém cadastro, login, KYC, elegibilidade, depósitos, saques e saldo dos jogadores. Não crie uma segunda conta ou um segundo caixa no iframe.

Jogador autenticado no cassino
  → backend do cassino cria sessão na OrbiSportbook
  → navegador recebe somente launchToken
  → SDK abre o iframe
  → OrbiSportbook chama a carteira do cassino por HTTPS + HMAC
  → cassino aplica cada movimentação uma vez e responde com o saldo

O identificador usado na carteira é o mesmo externalPlayerId fornecido na criação da sessão. Ele é estável e isolado por tenant. Não envie CPF, documentos ou senhas do jogador. kycStatus: verified na resposta representa delegação ao operador, não uma verificação de identidade realizada pela OrbiSportbook.

2. Reúna os dados antes de implementar

Peça os valores abaixo ao responsável pela integração. Para segredos, peça o nome ou caminho no cofre, não que sejam colados em prompts, tickets ou logs.

Dado	Como usar
Ambiente autorizado: local, sandbox hospedado ou produção aprovada	Define o que pode ser testado e publicado. Confirme também o ambiente do deployment.
SPORTSBOOK_URL	Origem confirmada; staging hospedado: https://api.orbisportbook.com.
TENANT_ID e moeda	Um conjunto por ambiente; não reutilize o tenant de sandbox em produção.
INTEGRATION_API_KEY	Segredo somente do backend, enviado em X-API-Key.
WALLET_SECRET	Segredo de HMAC da carteira desse tenant e ambiente. Não é a chave de integração.
WALLET_BASE_URL	Base HTTPS pública dos quatro callbacks; precisa estar configurada na OrbiSportbook.
Origens do cassino	Origens exatas de frontend autorizadas a incorporar o iframe, incluindo esquema e porta quando houver.
Autenticação e identificador de jogador do cassino	Middleware de sessão existente e mapeamento estável para externalPlayerId.
Ledger e banco da carteira	Onde aplicar débito/crédito e persistir idempotência atomicamente.
Jogadores e saldo fictício de teste	Contas locais ou sandbox autorizadas para homologação.
Opcional: AGGREGATOR_API_KEY	Apenas para provisionamento pelo backend de um agregador já autorizado.

Se faltar uma credencial, autorização ou decisão de identidade financeira, registre a pendência e avance nas partes independentes. Não invente valores, não utilize credenciais locais no ambiente hospedado e não substitua uma carteira real por um mock silenciosamente.

3. Leia os contratos nesta ordem

Ordem	Referência	O que resolve
1	Sessões de jogador	Payload, autenticação, token de lançamento, renovação e erros.
2	Carteira e OpenAPI	Callbacks, HMAC, idempotência, rollback e conciliação.
3	SDK e iframe	Montagem, tamanho, login, logout e callbacks de UI.
4	Protocolo postMessage	Eventos e comandos; necessário se não usar o SDK.
5	Testes e homologação	Evidências de funcionamento e casos financeiros difíceis.
6	Segurança e go-live	Segredos, origens, operação e requisitos de publicação.
Opcional	API de agregadores	Cadastro automático de cassinos e ambientes isolados.

Use os schemas e as referências detalhadas como contrato. Se o ambiente responder de forma incompatível, registre a requisição e a resposta sem segredos e confirme a versão com a equipe; não tente adivinhar endpoints ou campos.

4. Implemente o backend de sessão

Crie uma rota no servidor do cassino, protegida pela autenticação existente. Um nome possível é POST /sportsbook/session; esse é um exemplo de rota do cassino, não um endpoint da OrbiSportbook.

1. Resolva o jogador a partir da sessão autenticada. Nunca confie em um externalPlayerId arbitrário enviado pelo navegador.
2. Verifique os bloqueios e a elegibilidade do jogador no cassino.
3. Chame POST {SPORTSBOOK_URL}/api/v1/integration/sessions com X-Tenant-ID, X-API-Key e Content-Type: application/json.
4. Envie o ID estável, nome de exibição e, opcionalmente, moeda, path e locale suportados.
5. Confira o status HTTP e o envelope de erro. Devolva à página somente os dados de lançamento necessários, com Cache-Control: no-store.

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

A resposta contém launchToken, launchExpiresAt e launchUrl. O token de lançamento vale por 120 segundos e só pode ser consumido uma vez. O campo legado token contém uma sessão de maior duração: mantenha-o no servidor ou descarte-o. Não envie a resposta inteira da API ao navegador e não persista tokens em analytics ou logs.

Use a proteção CSRF da plataforma quando a rota do cassino autenticar por cookie. A rota deve derivar o tenant de configuração confiável, não de parâmetros livres do jogador. Em renovação, crie um launch token novo; não repita o anterior.

5. Implemente a carteira sem duplicar dinheiro

Exponha estes endpoints sob a base de carteira de cada ambiente:

Endpoint	Operação
POST /balance	Consulta do saldo do playerId; nenhuma movimentação.
POST /debit	Débito de aposta ou correção; valide saldo e aplique o valor integral.
POST /credit	Liquidação, reembolso, cash-out ou correção; aceite também valor zero.
POST /rollback	Reversão do débito indicado em ref, inclusive rollback que chega antes do débito.

Verifique X-Signature sobre os bytes originais antes de interpretar o JSON:

hex(HMAC-SHA256(WALLET_SECRET, X-Timestamp + "." + rawBody))

Use comparação em tempo constante e rejeite timestamps fora de ±300 segundos. O vetor offline permite validar a implementação sem usar segredos reais; o timestamp fixo do vetor não serve para uma chamada ao vivo.

Regras obrigatórias:

• Valores e saldo são inteiros em unidades menores, nunca ponto flutuante. Confirme a moeda.
• Autentique cada chamada; associe a URL/segredo à carteira correta. Callbacks não carregam um X-Tenant-ID que substitua esse isolamento.
• Persista movimentação, resultado e identidade completa do txId na mesma transação do banco. Duplicatas concorrentes devolvem o resultado original sem movimentar novamente.
• Mesmo txId com jogador, endpoint, valor, moeda, tipo, aposta ou referência diferentes: recuse com 409 duplicate_tx.
• Sucesso financeiro inclui o txId exato, saldo inteiro explícito e moeda correspondente. /balance não exige ecoar txId.
• Rollback anterior ao débito deixa um registro durável de ref; um débito atrasado deve ser recusado como rolled_back.
• Recusa definitiva usa 4xx e error.code. Falha temporária usa 5xx ou timeout. Não transforme resultado desconhecido em sucesso ou recusa definitiva.
• Não crie saldo negativo nem débito parcial para uma correção sem fundos. Preserve a recusa e encaminhe a exceção para conciliação.

{"txId":"bet:example-id","balance":49500,"currency":"USD"}

Não acrescente um endpoint de consulta de transação presumindo que a plataforma irá chamá-lo: o transporte publicado possui quatro endpoints. Entrega pode se repetir após falhas; idempotência durável é necessária. Estado da aposta e HTTP 200 de uma ação não comprovam que a carteira confirmou o pagamento.

6. Conecte a interface

Carregue https://api.orbisportbook.com/embed/v1.js e use OrbiSportbook.mount. O exemplo abaixo pressupõe funções do cassino já implementadas; não é um backend completo.

const sb = OrbiSportbook.mount('#sportsbook', {
  url: 'https://api.orbisportbook.com',
  tenant: tenantId, // identificador público do ambiente correto
  launchToken: await requestLaunchTokenFromYourBackend(),
  locale: 'pt-BR',
  height: 'fill',
  onLoginRequired: async () => {
    if (await openYourLogin()) {
      sb.setLaunchToken(await requestLaunchTokenFromYourBackend());
    }
  },
  onDepositRequested: () => openYourCashier(),
  onSessionExpired: () => requestLaunchTokenFromYourBackend(),
  onBalanceChanged: ({ balance, currency }) => updateBalanceDisplay(balance, currency),
});
// Ao sair do cassino: sb.logout(). Ao desmontar a tela: sb.destroy().

Dimensione o contêiner para o modo fill; veja os modos responsivos no guia do SDK. Anônimos podem navegar sem launchToken. Na renovação, retorne null se o jogador já saiu do cassino. Após depósito confirmado no caixa, sb.refreshBalance() atualiza a exibição.

Eventos do navegador servem para UI, não para lançar créditos no ledger. Não confie em balance_changed ou bet_settled como autorização financeira. Se implementar postMessage diretamente, valide origem, janela de origem e o envelope do protocolo; não use * como destino para dados de sessão.

7. Automatize o provisionamento quando aplicável

Para agregadores autorizados, use o fluxo completo de provisionamento:

1. POST /api/v1/aggregator/clients: cria cliente e ambientes suspensos; persista IDs e segredos nos cofres separados.
2. Instale cada segredo em sua carteira e crie jogadores de validação nos sistemas do operador.
3. POST /api/v1/aggregator/clients/{id}/activate: verifica saldo, moeda e rejeição de assinatura inválida nas duas carteiras. Ativa automaticamente quando a política permite e devolve chaves de integração separadas.
4. Use essas chaves apenas nos backends dos respectivos ambientes e conclua os testes de sessão e iframe.

Autenticação: Authorization: Bearer com a chave do agregador, sem X-Tenant-ID. Todo POST exige Idempotency-Key durável. Em retry, preserve corpo, chave de idempotência e credencial. Recuperação da resposta original tem janela de 24 horas; depois consulte o estado e o cofre, sem cadastrar outro cliente para contornar conflito. Essa validação não executa débitos/créditos e não substitui homologação financeira ou licença.

8. Teste e registre evidência

Execute testes de dinheiro apenas em local/sandbox com saldo fictício e contas autorizadas. Para produção, obtenha autorização explícita e conclua o go-live.

Grupo	Evidência mínima
Sessão	Jogador autenticado correto; ID arbitrário do navegador não troca a identidade; segredo ausente do bundle/resposta/log.
Tokens	Launch token reutilizado, expirado ou de outro tenant falha; renovação funciona; logout encerra a sessão.
Iframe	Origem permitida funciona; não permitida falha; desktop e celular sem corte ou rolagem bloqueada.
Assinatura	Válida aceita; corpo alterado, segredo errado e timestamp antigo rejeitados.
Idempotência	Duas chamadas concorrentes com mesmo txId movem uma vez; payload divergente é recusado.
Ciclo financeiro	Vitória, perda com crédito zero, anulação, cash-out, rollback antes/depois do débito e correção sem fundos.
Recuperação	Timeout após commit, retry e indisponibilidade não duplicam saldo; obrigações pendentes ficam visíveis.
Isolamento	Tenant, chaves, URLs, jogadores e saldos de sandbox/produção permanecem separados.
Conciliação	Compare ledger, txId, aposta e confirmação da carteira; não use apenas o status visual da aposta.

Registre ambiente, versão, cenários executados, resultado esperado/observado e IDs de transação sem segredos ou dados pessoais. Distinga implementado, testado localmente, homologado em sandbox e aprovado para produção. Um build, um iframe aberto ou uma consulta de saldo isolada não comprovam a integração inteira.

9. Prompt pronto para o seu agente

Copie o texto abaixo e forneça acesso ao repositório e aos nomes dos segredos no cofre:

Integre o OrbiSportbook neste cassino usando o guia oficial:
https://api.orbisportbook.com/docs/pt-br/ai-integration/
Índice para ferramentas: https://api.orbisportbook.com/docs/llms.txt

Primeiro leia o guia, o contrato de sessões, o OpenAPI da carteira e o SDK.
Mapeie nossa autenticação, o ID estável do jogador, o ledger e as convenções
do repositório. Identifique dados e autorizações ausentes antes de depender deles.

Implemente uma rota de sessão no backend autenticado, os quatro callbacks
de carteira com HMAC sobre raw body e idempotência transacional, e o iframe
com login, caixa, renovação, logout e layout responsivo.
Se houver chave de agregador autorizada, siga o provisionamento documentado.
Não invente endpoints, credenciais, aprovações ou regras financeiras.
Não exponha chaves ou tokens de sessão no frontend, prompts ou logs.

Rode os cenários de aceite em local/sandbox com saldo fictício. Preserve
isolamento entre ambientes. Não movimente dinheiro real sem autorização.
Entregue arquivos alterados, configuração por nome de variável, resultados
dos testes, instruções de operação e pendências concretas para go-live.
Não declare produção pronta se alguma dependência não foi comprovada.

Diagnóstico rápido

Sintoma	Verifique
401 ao criar sessão	Chave, tenant e ambiente; não use chave de agregador como chave de integração.
launch_token_used ou launch_token_expired	Emita token novo imediatamente antes de montar ou renovar; não reutilize uma URL antiga.
Iframe bloqueado	Origem exata cadastrada, políticas CSP e configuração de incorporação.
Assinatura inválida	Raw body, segredo do ambiente, relógio Unix em segundos e comparação HMAC.
Dinheiro pendente	Resposta válida com txId/moeda/saldo, logs por transação e fila financeira.
409 no provisionamento	Estado existente, idempotência, limite e mudanças de configuração; não crie outro ID às cegas.

Decida por error.code e details.reason, nunca pelo texto traduzido de message. Ao escalar, envie ambiente, horário, endpoint e IDs relevantes com headers e corpos sensíveis removidos.