API de agregadores

A API permite que um agregador autorizado, como o Pigmo, cadastre cada novo cassino como um cliente independente da OrbiSportbook. O fluxo é cadastrar → instalar os segredos nas carteiras → validar e ativar → integrar o iframe. Não há aprovação manual por cliente quando a autorização do agregador permite ativação automática.

Baixar contrato OpenAPI 3.1

Autorizar o agregador uma vez

No Admin da plataforma, abra Agregadores e cadastre o parceiro. O registro começa desabilitado. Um administrador da plataforma com MFA autoriza o parceiro diretamente. Não é necessário outro administrador para autorizar o agregador ou emitir sua chave. A autorização define:

Limite de clientes, moedas, jurisdições e territórios permitidos.
Origens HTTPS exatas das carteiras, sem curingas, caminhos ou parâmetros.
Permissão de ativação automática, referência do contrato aprovado e validade de até cinco anos.

Depois emita uma chave do agregador com prazo de até um ano e as permissões necessárias. Ela aparece uma única vez para o administrador que a emitiu. A chave não pode durar mais que a autorização. Guarde-a no cofre de segredos do backend do Pigmo; nunca no navegador, no iframe, em logs ou nas configurações públicas de um cassino.

Permissão	Uso
`clients:read`	Listar e consultar os próprios clientes
`clients:create`	Criar clientes e seus dois ambientes
`clients:activate`	Validar carteiras e ativar clientes
`credentials:rotate`	Substituir as chaves de integração de um ambiente

Autenticação e retries

Base: https://api.orbisportbook.com/api/v1/aggregator.

Envie Authorization: Bearer $AGGREGATOR_API_KEY. Esta API é servidor a servidor: não usa login de jogador, cookie de staff nem X-Tenant-ID. Requisições com Origin são recusadas.

Todo POST exige Idempotency-Key: 8–128 caracteres entre letras, números, _, ., :, -. Use uma chave durável por etapa do cadastro e reutilize-a em retries com o mesmo corpo e a mesma chave de API. Não gere outra chave a cada tentativa.

A resposta original fica disponível, criptografada, por 24 horas. Replays incluem Idempotency-Replayed: true. Mudança de corpo, de credencial ou resposta expirada resulta em 409. O registro da solicitação continua existindo para evitar que um retry antigo repita a operação. O externalId também é único dentro do agregador. Após expiração ou conflito, consulte o estado do cliente e recupere os segredos do seu cofre antes de retomar; não crie outro cliente para contornar o erro.

Limites: 64 KiB por corpo, 120 requisições por minuto por agregador (compartilhadas entre suas chaves), até 100 resultados por página. 429 inclui Retry-After: 60.

1. Cadastrar o cassino

As origens das carteiras precisam estar na autorização. Os caminhos de produção e sandbox devem ser diferentes e atender a bancos de saldo separados. A API da carteira identifica o jogador por playerId; ela não envia um tenant como alternativa ao isolamento de ambientes.

curl --fail-with-body https://api.orbisportbook.com/api/v1/aggregator/clients \
  -H "Authorization: Bearer $AGGREGATOR_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: casino-42-provision-v1' \
  -d '{
    "externalId": "casino-42",
    "name": "Casino 42",
    "legalName": "Casino 42 Ltd",
    "brandName": "Casino 42",
    "currency": "USD",
    "jurisdiction": "ROW",
    "locale": "pt-BR",
    "territories": ["CW"],
    "embedOrigins": ["https://casino42.example"],
    "productionWalletUrl": "https://wallet.partner.example/casino-42/production",
    "sandboxWalletUrl": "https://wallet.partner.example/casino-42/sandbox",
    "reason": "Provisionamento no deploy do cassino"
  }'

Resposta 201 (valores ilustrativos):

{
  "id": "acl_generated",
  "externalId": "casino-42",
  "status": "suspended",
  "nextAction": "install_wallet_secrets_then_activate",
  "credentialsReplaySeconds": 86400,
  "production": {"tenantId": "ob_generated", "walletSecret": "whsec_REDACTED_PRODUCTION"},
  "sandbox": {"tenantId": "ob_generated-sandbox", "walletSecret": "whsec_REDACTED_SANDBOX"}
}

Os IDs internos são gerados pelo servidor. Não é possível anexar um tenant existente ao agregador por essa API. Guarde o id, os dois tenantId e os dois segredos; configure cada segredo somente na respectiva carteira. Ambos os ambientes começam suspensos e ainda não têm chaves de integração utilizáveis.

Implemente os quatro endpoints da API de carteira em cada base URL. Responda a /balance com saldo inteiro em unidades menores e a moeda cadastrada. Assinatura inválida deve retornar 401 ou 403. Em staging e produção são exigidos HTTPS público, certificado válido e porta 443; redes privadas, metadados de nuvem, proxies de ambiente e redirecionamentos são bloqueados também nas chamadas financeiras posteriores. Somente desenvolvimento permite HTTP loopback.

2. Validar e ativar automaticamente

Cadastre no seu próprio sistema um jogador de validação em cada ambiente. A OrbiSportbook consulta o saldo desses identificadores; esta etapa não cria jogador, faz débito, crédito ou estorno.

curl --fail-with-body \
  "https://api.orbisportbook.com/api/v1/aggregator/clients/$CLIENT_ID/activate" \
  -H "Authorization: Bearer $AGGREGATOR_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: casino-42-activate-v1' \
  -d '{"productionPlayerId":"validation-prod-42","sandboxPlayerId":"validation-sandbox-42","reason":"Validar integração após deploy"}'

A validação exige saldo com moeda correta e rejeição de assinatura inválida nas duas carteiras. A autorização, a chave e a configuração são verificadas novamente antes da ativação. Se houver revogação ou mudança durante a consulta, nenhum ambiente é ativado e nenhuma chave é emitida. O deployment precisa ter sandboxes dedicados habilitados.

Resposta 200:

{
  "id": "acl_generated",
  "status": "active",
  "credentialsReplaySeconds": 86400,
  "production": {"tenantId":"ob_generated","environment":"production","keyId":"key_generated_prod","integrationApiKey":"bki_production_REDACTED"},
  "sandbox": {"tenantId":"ob_generated-sandbox","environment":"sandbox","keyId":"key_generated_test","integrationApiKey":"bki_sandbox_REDACTED"}
}

Armazene as chaves separadamente no cofre de cada ambiente. Use a integrationApiKey com X-API-Key e o respectivo tenantId para criar sessões de jogador e entregar ao navegador somente o token de lançamento do iframe.

A ativação é uma validação técnica sob uma autorização contratual prévia. Ela não certifica licença, direitos de dados ou homologação financeira completa. As responsabilidades do operador e os requisitos do go-live continuam aplicáveis. Um cliente suspenso posteriormente pela plataforma não pode se reativar por esse endpoint.

Consulta e rotação

Método e caminho	Resultado
`GET /clients?limit=50&cursor=...`	Próprios clientes e `nextCursor`; sem segredos
`GET /clients?externalId=casino-42`	Localiza o cassino pelo ID do Pigmo
`GET /clients/{id}`	IDs dos ambientes, moeda, jurisdição e estado; sem segredos
`POST /clients/{id}/credentials/rotate`	Nova chave de integração para o ambiente informado

Na rotação envie {"environment":"production","reason":"Rotação programada"} e uma nova chave de idempotência. Todas as chaves de integração anteriores desse ambiente são revogadas na mesma transação. O segredo de assinatura da carteira e as sessões já abertas não são rotacionados por esse endpoint; coordene a troca do segredo da carteira pelo fluxo administrativo de integração.

Revogar a chave do agregador bloqueia novas solicitações e a recuperação das respostas daquela chave. Desabilitar o agregador bloqueia seu acesso à API, preservando as integrações dos clientes existentes e pagamentos pendentes. Suspensão de um cassino e revogação de suas credenciais são decisões separadas.

Erros para o job de deploy

HTTP	Ação
`400`	Corrigir payload, carteira, moeda, assinatura ou configuração indicada
`401`	Chave revogada/expirada ou autorização desabilitada/expirada; interromper e revisar acesso
`403`	Escopo, território, moeda, origem ou ativação não autorizados
`404`	Cliente inexistente ou pertencente a outro agregador
`409`	Consultar estado: duplicidade, cota, retry incompatível, configuração alterada ou ativação já concluída
`429`	Aguardar `Retry-After` e repetir com a mesma chave de idempotência
`5xx` / timeout	Retry com backoff e a mesma chave; nunca assumir que a operação não ocorreu

Para o Pigmo, mantenha um job durável por cassino com estados cadastrado, segredos_instalados, validado, integrado. Salve os recibos sem segredos nos logs e os segredos no cofre antes de avançar. Disponibilize o sportsbook aos jogadores apenas depois de guardar as chaves de integração e concluir os testes do iframe.