Contrato da API SportsCore
O SportsCore entrega à sua bet um sportsbook completo. Sua plataforma abre a sessão do jogador via API e mantém o saldo: cada aposta, prêmio e estorno chega ao seu wallet_url por webhook assinado. Token e secret ficam somente no seu servidor.
1. Credenciais
No painel, crie o agente e copie AGENT TOKEN e SECRET KEY (o secret aparece uma única vez). Envie em todas as rotas:
Base: https://SEU_DOMINIO/api/public/v1 X-SportsCore-Agent: SEU_AGENT_TOKEN X-SportsCore-Secret: SEU_AGENT_SECRET Content-Type: application/json
Ordem: 1) implemente o endpoint de carteira com HMAC e idempotência; 2) grave o wallet_url; 3) leia /agent e /events; 4) faça um launch de teste; 5) valide débito, cancelamento e crédito.
2. Agente e catálogo
GET /agent → {"status":true,"agent":{"code","name","wallet_url","active","currency","limits":{...}}}
PUT /agent {"wallet_url":"https://sua-bet.com/api/sportscore/wallet"} → {"status":true,"msg":"SUCCESS"}
GET /sports → {"status":true,"sports":[{"sport_key","group","league","events"}]}
GET /events?sport=KEY → {"status":true,"events":[{"event_id","home","away","starts_at","markets":[...]}]}3. Abertura do sportsbook (launch)
curl -X POST 'https://SEU_DOMINIO/api/public/v1/launch' \
-H 'X-SportsCore-Agent: SEU_AGENT_TOKEN' -H 'X-SportsCore-Secret: SEU_AGENT_SECRET' \
-H 'Content-Type: application/json' \
-d '{"user_code":"jogador_123","user_balance":100.00,"lang":"pt","currency":"BRL"}'
→ {"status":true,"msg":"SUCCESS","launch_url":"https://SEU_DOMINIO/play/…","user_code":"jogador_123","user_balance":100,"user_created":true,"expires_in":28800}Antes de devolver o launch_url, o SportsCore consulta user_balance na sua carteira; se ela recusar ou estiver inacessível, o launch falha (502). Abra o launch_url em nova aba ou iframe. A sessão vale 8 horas.
4. Carteira da sua plataforma (webhook)
O SportsCore faz POST JSON no seu wallet_url. Responda HTTP 200 com {"status":true,"balance":<número>}. Qualquer outra resposta é rejeição.
X-SportsCore-Agent: SEU_AGENT_TOKEN X-SportsCore-Timestamp: 1792690000 X-SportsCore-Signature: v1=HMAC_SHA256_HEX HMAC_SHA256_HEX = hmac_sha256(SECRET_KEY, timestamp + "." + corpo_bruto)
Valide o token, a idade do timestamp (ex.: 5 min), a assinatura sobre os bytes originais e compare em tempo constante.
// Consulta
{"method":"user_balance","agent_code":"sua_bet","user_code":"jogador_123"}
// Aposta aceita — debite stake
{"method":"bet_debit","agent_code":"sua_bet","user_code":"jogador_123","txn_id":"debit:A1B2C3D4E5","bet_id":"…","amount":10.00,"currency":"BRL","odds":3.4,"potential_return":34}
// Prêmio — credite amount
{"method":"bet_credit","txn_id":"credit:A1B2C3D4E5","amount":34.00,"ref_txn_id":"debit:A1B2C3D4E5","reason":"won",…}
// Cancelamento ou aposta anulada — devolva amount
{"method":"bet_refund","txn_id":"refund:A1B2C3D4E5","amount":10.00,"ref_txn_id":"debit:A1B2C3D4E5",…}
// Timeout no débito — desfaça ref_txn_id se ele foi aplicado; senão ignore
{"method":"bet_rollback","txn_id":"rollback:A1B2C3D4E5","amount":10.00,"ref_txn_id":"debit:A1B2C3D4E5",…}Idempotência: grave uma chave única por txn_id. Se o mesmo txn_id chegar de novo, devolva a resposta gravada sem reaplicar. Bloqueie a linha do saldo numa transação. Em bet_debit, saldo insuficiente → {"status":false,"msg":"INSUFFICIENT_FUNDS"}; a aposta é recusada. Créditos e estornos que falharem são reenviados com intervalo crescente.
5. Apostas
GET /bets?user_code=jogador_123 → {"status":true,"bets":[{"bet_id","status","stake","odds","potential_return","payout","selections":[...]}]}
GET /bets/{bet_id}/ → {"status":true,"bet":{...}}
POST /bets/{bet_id}/cancel → {"status":true,"msg":"SUCCESS"} (só antes do início de todas as partidas; dispara bet_refund)Status: processing, pending, won, lost, void, cancelled, rejected. Simples cobram stake por seleção; múltiplas combinam partidas diferentes. Cotações são revalidadas no servidor no momento da aposta.
6. Liquidação
Resultados oficiais são verificados periodicamente. Vencedor, handicap e totais liquidam automaticamente; outros mercados são liquidados pelo painel. Seleção anulada conta odd 1; múltipla com uma seleção perdida é perdida.
7. Erros
Cobrança e saldo dos agentes
O saldo do agente é separado do saldo do jogador, que continua na carteira do cassino. No painel, o administrador define pré-pago ou pós-pago e a porcentagem de GGR. GGR = valores das apostas liquidadas menos prêmios; cancelamentos, rejeições e anulações não geram comissão.
Pré-pago exige saldo maior que zero para abrir jogos e apostar. A comissão é ajustada a cada liquidação pelo GGR líquido acumulado da semana; prejuízos reduzem a comissão já debitada na mesma semana. GGR negativo passa à semana seguinte, sem gerar recarga em dinheiro.
Pós-pago fecha segunda-feira às 00:00 de Brasília, podendo gerar a fatura até cerca de 30 segundos depois. O prazo é de 72 horas: vencimento quinta-feira às 00:00. Sem pagamento, novas aberturas, catálogo e apostas ficam bloqueados; histórico, estornos e prêmios permanecem disponíveis. Confirmar todas as faturas vencidas no painel remove o bloqueio financeiro, sem desfazer uma desativação manual.
Recargas e pagamentos são confirmados manualmente pelo administrador após recebimento. Alterações de modalidade ou taxa são permitidas apenas quando a semana ainda não tem GGR contabilizado.
GET /agent → agent.billing { mode, balance, ggr_fee_percent, carryover, period_ggr }, access
403 AGENT_BALANCE_EXHAUSTED → recarregar saldo do agente
403 AGENT_INVOICE_OVERDUE → pagar faturas vencidas
// Ajuste autorizado pelo dono no painel: sua carteira precisa implementar este método
{"method":"admin_set_balance","user_code":"jogador_123","txn_id":"balance:UUID","amount":150,"balance":150,"reason":"Ajuste do administrador",…}
// Defina o saldo absoluto uma única vez por txn_id e responda com o saldo final
{"status":true,"balance":150}401 INVALID_CREDENTIALS / AGENT_INACTIVE revise token e secret 403 PLAYER_DISABLED jogador bloqueado 404 BET_NOT_FOUND 409 BET_NOT_CANCELLABLE partida iniciada ou aposta liquidada 422 INVALID_LAUNCH_REQUEST / INVALID_WALLET_URL / INVALID_USER 429 RATE_LIMITED mais de 240 pedidos/minuto 500 WALLET_NOT_CONFIGURED 502 WALLET_FAILED sua carteira recusou ou não respondeu 503 PROVIDER_NOT_CONFIGURED