Especificação técnica para operadores parceiros (agentes).
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"
}
https://www.lumbrabr.online/api/v1/providersLista todos os provedores de jogos ativos no sistema.
https://www.lumbrabr.online/api/v1/gamesRetorna 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"
}
]
}
https://www.lumbrabr.online/api/v1/game-launchGera 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"
}
Para agentes que utilizam a carteira gerenciada na plataforma (Transfer Wallet):
https://www.lumbrabr.online/api/v1/user-balanceConsulta o saldo de um jogador passando user_code.
https://www.lumbrabr.online/api/v1/user-depositDeposita saldo na conta do jogador (parâmetros: user_code, amount).
https://www.lumbrabr.online/api/v1/user-withdrawRetira saldo da conta do jogador (parâmetros: user_code, amount).
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
}
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.
| Endpoint | Para quê |
|---|---|
GET/POST https://www.lumbrabr.online/api/v1/sports/settings | Limites do seu contrato |
GET/POST https://www.lumbrabr.online/api/v1/sports/leagues | Campeonatos 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/bet | Criar 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) |
https://www.lumbrabr.online/api/v1/sports/betEnvie 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.
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.
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).
market | pick | Regra |
|---|---|---|
1x2 | home · draw · away | Resultado em 90 min |
dc | 1x · x2 · 12 | Dupla chance |
dnb | home · away | Empate anula: empate devolve a aposta |
ou | over · under | Total 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).
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.
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.
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).
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).