API

Guia de Integração da API

Especificação técnica para operadores parceiros (agentes).

Voltar ao Painel

Autenticação & Endpoint Base

Todas as requisições para a API do operador devem ser feitas via método POST ou GET para a URL base:

https://www.lumbrabr.online/api/v1

Você deve enviar obrigatoriamente no corpo (JSON ou form-data) as suas credenciais fornecidas no painel:

{
  "agent_code": "SEU_AGENT_CODE",
  "agent_token": "SEU_AGENT_TOKEN"
}

1. Catálogo de Provedores e Jogos

GET / POST https://www.lumbrabr.online/api/v1/providers

Lista todos os provedores de jogos ativos no sistema.

GET / POST https://www.lumbrabr.online/api/v1/games

Retorna a lista completa de jogos disponíveis. É possível filtrar passando o parâmetro opcional provider_code.

// Resposta de Sucesso:
{
  "status": 1,
  "games": [
    {
      "game_code": "fortune-tiger",
      "game_name": "Fortune Tiger",
      "provider_code": "pgsoft",
      "type": "slot",
      "banner": "https://.../banner.png",
      "rtp": "96.81"
    }
  ]
}

2. Lançamento de Jogo (Game Launch)

POST https://www.lumbrabr.online/api/v1/game-launch

Gera a URL de sessão segura para o jogador abrir o jogo no seu aplicativo ou site.

// Requisição:
{
  "agent_code": "SEU_AGENT_CODE",
  "agent_token": "SEU_AGENT_TOKEN",
  "user_code": "jogador_12345",
  "provider_code": "pgsoft",
  "game_code": "fortune-tiger",
  "lang": "pt"
}

// Resposta:
{
  "status": 1,
  "launch_url": "https://plataforma.com/play/SESSION_TOKEN"
}

3. Gerenciamento de Saldo (Transfer Wallet)

Para agentes que utilizam a carteira gerenciada na plataforma (Transfer Wallet):

POST https://www.lumbrabr.online/api/v1/user-balance

Consulta o saldo de um jogador passando user_code.

POST https://www.lumbrabr.online/api/v1/user-deposit

Deposita saldo na conta do jogador (parâmetros: user_code, amount).

POST https://www.lumbrabr.online/api/v1/user-withdraw

Retira saldo da conta do jogador (parâmetros: user_code, amount).

4. Webhook em Tempo Real (Seamless Wallet)

Se o seu agente foi configurado como Seamless Wallet, a cada rodada nossa plataforma enviará uma requisição HTTP POST para a sua callback_url cadastrada contendo:

// Callback enviado ao seu servidor:
{
  "user_code": "jogador_12345",
  "provider_code": "pgsoft",
  "game_code": "fortune-tiger",
  "txn_id": "TXN_987654321",
  "round_id": "RND_1234",
  "txn_type": "debit_credit",
  "bet": 2.00,
  "win": 10.00
}

// Seu servidor deve responder:
{
  "status": 1,
  "user_balance": 158.50
}

5. Apostas Esportivas

Mesma autenticação (agent_code + agent_token). Odds já vêm com a sua margem; limites e campeonatos são os configurados para o seu agente. Só pré-jogo: Resultado (1x2) e Mais/Menos de gols (ou), simples ou múltipla.

EndpointPara quê
GET/POST https://www.lumbrabr.online/api/v1/sports/settingsLimites do seu contrato
GET/POST https://www.lumbrabr.online/api/v1/sports/leaguesCampeonatos liberados
GET/POST https://www.lumbrabr.online/api/v1/sports/events (league_code, date)Jogos e odds
POST https://www.lumbrabr.online/api/v1/sports/betCriar aposta (exige Idempotency-Key)
GET/POST https://www.lumbrabr.online/api/v1/sports/bet-status (bet_id)Consultar aposta
GET/POST https://www.lumbrabr.online/api/v1/sports/player-bets (user_code)Últimas 50 do jogador
POST https://www.lumbrabr.online/api/v1/sports/bet-void (bet_id)Anular aposta aberta (só antes de qualquer jogo começar)
GET/POST https://www.lumbrabr.online/api/v1/sports/report (from, to)GGR do período: prov_* (inclui abertas) e closed_* (liquidadas)

POST https://www.lumbrabr.online/api/v1/sports/bet

Envie o cabeçalho Idempotency-Key (ou idempotency_key no corpo), único por aposta: repetir a mesma chave devolve a aposta original (replayed: true), sem apostar de novo. Se odds diferir da atual: 409 ODDS_CHANGED com changed.

{
  "agent_code": "...", "agent_token": "...",
  "user_code": "jogador_12345", "stake": 10.00,
  "selections": [ { "event_id": 55, "market": "1x2", "pick": "home", "odds": 2.10 } ]
}

Erros (status:0, msg): INSUFFICIENT 400 · NO_WALLET 404 · ODDS_CHANGED 409 · STAKE_RANGE/CLOSED/VALIDATION 422 · CREDIT_LIMIT_REACHED 402 (créditos de GGR esgotados) · USER_BLOCKED 403 · WALLET_UNAVAILABLE/WALLET_UNCERTAIN 503 (seamless: o débito ficou sem confirmação; a aposta fica pending e é resolvida automaticamente, consulte bet-status ou repita a mesma Idempotency-Key). Status da aposta: pending, open, won, lost, void, rejected.

Seamless Wallet: callback das apostas esportivas

No modo seamless usamos a mesma callback_url. Além de user_balance, enviamos method: "transaction" com game_type: "sports". Seu servidor deve ser idempotente por sports.txn_id (mesmo id = mesmo resultado, sem mover dinheiro de novo; responda normalmente com o saldo).

// Enviado ao seu servidor
{ "method": "transaction", "agent_code": "...", "agent_secret": "...", "user_code": "jogador_12345",
  "game_type": "sports",
  "sports": { "type": "bet",            // bet = debitar a aposta | win = creditar o prêmio | refund = devolver
              "amount": 10.00, "currency": "BRL",
              "txn_id": "sportbet:812:stake",   // :stake (bet) · :payout (win) · :refund (refund)
              "bet_id": 812,
              "reverses": "sportbet:812:stake" } }   // só no refund: devolva o valor que aquele débito tirou

// Respostas
{ "status": 1, "user_balance": 158.50 }
{ "status": 0, "msg": "INSUFFICIENT_USER_FUNDS" }   // saldo insuficiente no débito
{ "status": 0, "msg": "USER_NOT_FOUND" }             // jogador inexistente

Timeout, erro de rede ou resposta inválida são tratados como incertos: repetimos com o mesmo txn_id (débitos pendentes por até 30 min; prêmios e estornos até você confirmar, com espera crescente). Um refund de débito que você nunca recebeu deve ser aceito sem efeito, e o débito daquele txn_id não deve ser aceito depois.

Cobrança: o GGR de esportes (apostado − prêmio, só quando a casa ganha) é descontado do seu saldo pré-pago ao liquidar cada aposta, pelo % configurado para o seu agente. Anulações não geram cobrança.

6. Esportes: tela pronta, mercados, limites e segurança

POST https://www.lumbrabr.online/api/v1/sports/launch (user_code, lang)

Abre a tela de apostas pronta para o jogador, para usar em iframe (igual ao game-launch). Resposta: { "status": 1, "launch_url": "...", "expires_at": "..." }. A sessão vale 12 h; o saldo é o da carteira do agente (transfer ou seamless).

Mercados

marketpickRegra
1x2home · draw · awayResultado em 90 min
dc1x · x2 · 12Dupla chance
dnbhome · awayEmpate anula: empate devolve a aposta
ouover · underTotal de gols na linha informada; gols iguais à linha devolvem

Prorrogação/pênaltis e jogos cancelados devolvem a aposta. Palpite com odd abaixo do mínimo não é oferecido (vem null).

Erros de risco

ODDS_STALE 422 (odds em atualização) · SUSPENDED 422 (jogo suspenso) · LIABILITY_LIMIT 422 (limite de risco do palpite) · DAILY_LIMIT 422 (teto diário do jogador) · MARKET_UNAVAILABLE 422.

Assinatura dos callbacks (jogos e esportes)

Todo POST para a sua callback_url leva X-Timestamp e X-Signature = HMAC-SHA256(sua secret_key, "{X-Timestamp}.{corpo bruto}") em hexadecimal. Valide a assinatura e recuse timestamps com mais de 5 minutos. O agent_secret continua no corpo por compatibilidade.

Seamless: estorno de prêmio e aviso de liquidação

Se um resultado for corrigido depois de pago, enviamos sports.type: "chargeback" (debitar um prêmio já pago, txn_id terminado em :unpay:vN) e, se a aposta tinha sido devolvida, um novo bet com txn_id :restake:vN; depois o novo prêmio/devolução vem com sufixo :vN. Se o jogador não tiver saldo, nada é alterado e a aposta vai para revisão manual. Com o aviso ligado no painel, cada aposta liquidada gera method: "sports_settled" com bet: {bet_id, user_code, status, stake, payout, settled_at}; responda {"status": 1} (repetimos até confirmar).

Cobrança do GGR

Configurável por agente: por aposta (padrão: ao liquidar, só quando a casa ganha) ou mensal líquida (dia 1: GGR líquido do mês anterior × %, uma vez; mês negativo não cobra).