Integração de API de Sportsbook: Odds, Apostas e Liquidação
Uma odd exibida na página de apostas esportivas não significa que a aposta já foi aceita. O fornecedor de dados publica eventos, mercados e preços; o serviço de apostas toma a decisão de aceitação; a carteira e o mecanismo de liquidação registram os efeitos financeiros. Uma integração de API confiável liga esses componentes com identificadores estáveis, transições de estado bem definidas, tentativas seguras e conciliação auditável. Este guia acompanha o bilhete desde o mercado ao vivo até o pagamento ou a correção do resultado. Receber odds de um fornecedor não comprova que ele também aceite apostas, administre fundos ou conceda direitos de operação em determinada jurisdição.
Publicado em
O preço exibido, o bilhete aceito e o lançamento financeiro são decisões separadas.
Neste artigo
Quais sistemas fazem parte da integração de sportsbook?
Há três responsabilidades principais: catálogo de eventos e mercados com odds variáveis, motor de aceitação de apostas e serviço de liquidação de resultados. Um fornecedor pode cobrir várias funções, ou cada função pode pertencer a parceiros diferentes. O contrato técnico deve identificar quem autoriza cada decisão. [1]
Uma atualização de mercado pode ser a referência válida para aquele preço, mas não autoriza movimentar o saldo do jogador. Do mesmo modo, o clique em Apostar não torna o bilhete aceito. A confirmação precisa vir do serviço competente, com valor e odd gravados.
Como mapear eventos, mercados e seleções?
Mantenha IDs internos para evento, mercado, seleção e bilhete, sem perder os identificadores originais e o namespace do parceiro. Um evento comporta vários mercados; o mesmo mercado pode ter linhas distintas. O rótulo 'Mais de 2,5' não é uma chave única sem o contexto do jogo e dos parâmetros.
Identificador
Função
Cuidado
Evento de origem
Partida no feed
Preservar o fornecedor
Mercado
Tipo de aposta e linha
Guardar parâmetros
Seleção
Resultado escolhido
Não usar só o texto
Versão da odd
Revisão do preço
Rejeitar versão antiga
ID do bilhete
Aposta aceita
Estável em nova tentativa
ID de liquidação
Evento de resultado
Associar ao bilhete
Guarde a versão do mapeamento e o payload original. Uma partida adiada ou um mercado renomeado não pode redirecionar um bilhete existente para outro resultado. As mensagens de fixture, odds e settlement têm funções distintas no feed. [1]
O que muda quando a odd varia ou o mercado é suspenso?
O preço pode mudar ou o mercado pode ser suspenso entre a visualização e o envio da aposta. O consumidor deve aplicar a ordem, o timestamp e os status conforme a semântica do provedor. Manter a última odd na tela não transforma um mercado indisponível em aposta válida. Isso é ilustrado no evento odds_change. [2]
Registrar horário da fonte e última versão aplicada a cada mercado.
Distinguir ativo, suspenso, encerrado e desconhecido conforme o contrato.
Definir validade máxima da cotação e revalidá-la no servidor.
Não prometer aceitação com base em preço ainda presente no cache.
O cache agiliza a vitrine, mas o endpoint de aceitação precisa checar preço atual, elegibilidade do cliente, risco e saldo. Se houver mudança, apresente uma rejeição explícita ou peça confirmação da nova odd.
Como o clique se transforma em uma aposta confirmada?
A requisição deve incluir cliente, marca, evento, mercado, seleção, valor, odd solicitada e chave única. O motor competente avalia status, elegibilidade da conta, limites e fundos. Um feed de dados pode não oferecer endpoint de colocação de apostas.
Receber seleção, stake, preço e uma chave única para a operação.
Checar novamente mercado, cotação, saldo disponível e regras de risco.
Obter a decisão autorizada: aceito, rejeitado ou pendente.
Registrar bilhete e reserva uma única vez; em repetição, retornar o resultado salvo.
⊕Ampliar diagramaAs odds orientam a validação, mas a obrigação financeira começa apenas com a aceitação confirmada.
Timeout depois do envio não significa que a aposta falhou: o parceiro pode ter aceitado sem conseguir responder. Consulte a operação por sua chave antes de reenviar. A semântica HTTP não torna seguro repetir qualquer POST automaticamente. [6]
Como recuperar mensagens após uma falha no feed?
Feeds ao vivo podem cair, atrasar ou repetir mensagens. É importante preservar identidade do produtor, sequência, cursor durável e plano de recuperação. Um evento crítico só deve ser confirmado depois de persistido. A documentação do parceiro pode tratar separadamente eventos de liquidação, cancelamento e replay. [5]
Problema
Ação
Conferência
Mensagem duplicada
Ignorar por chave
Sem segundo efeito
Lacuna na sequência
Suspender uso inseguro
Reexecutar ou consultar
Feed desconectado
Bloquear cotação antiga
Fonte atualizada
Resultado tardio
Processar evento próprio
Bilhete relacionado
Reinicialização
Retomar cursor salvo
Sem pagamento repetido
Um snapshot de odds não garante que todos os eventos financeiros chegaram. Confirme o contrato de recuperação e as janelas de retenção de cada fornecedor; concilie bilhetes ainda abertos em uma rotina separada.
Como tratar resultado, anulação e reversão da liquidação?
A liquidação encerra o bilhete aceito com base nas regras válidas da aposta. Ganho, perda, anulação, liquidação parcial e acumuladas exigem estados e fórmulas contratuais. O Unified Odds Feed descreve tanto bet_settlement quanto rollback_bet_settlement para corrigir uma mensagem anterior. [3] [4]
Conservar stake, odd aceita, parâmetros do mercado e versão das regras.
Aplicar resultados apenas a bilhetes conhecidos e origem autenticada.
Lançar prêmio ou restituição uma vez com chave única de liquidação.
Registrar correção por lançamento reverso com motivo, preservando o histórico.
Um rollback não representa um prêmio novo; cancelar o mercado nem sempre equivale ao mesmo mecanismo de void. Mantenha o tipo de mensagem da fonte. Na Grã-Bretanha, quando aplicável, a RTS 5 exige que o resultado siga as regras divulgadas e que erros relevantes sejam comunicados ao cliente. [7]
Como conciliar carteira, stake e pagamentos?
Use referências imutáveis separadas para reserva, aceitação, liquidação e correção. Receber callback não significa que um pagamento foi efetivado. Cada movimento financeiro deve ter uma chave única, conciliada com o bilhete e a confirmação do parceiro.
Estado do bilhete
Ação na carteira
Evidência
Cotação
Não debitar
Pedido e vencimento
Aceito
Reservar stake uma vez
Referência aceita
Rejeitado
Liberar reserva
Motivo do retorno
Liquidado
Pagar ou encerrar perda
Resultado e lançamento
Corrigido
Reverter ou reembolsar
ID anterior e motivo
A conciliação compara por ticket e moeda os valores exatos, reservas pendentes, pagamentos e lançamentos reversos. Divergências precisam de análise: mensagens sem validação não podem criar créditos compensatórios automáticos.
Quais controles de latência e risco importam no ao vivo?
Durante um evento esportivo, preço e disponibilidade mudam rapidamente. O feed de baixa latência melhora a exibição, mas não substitui sinais de suspensão, prazo de confirmação, limites de exposição ou eventuais atrasos obrigatórios de apostas. Planeje uma resposta conservadora para falhas.
Medir atraso da origem, idade da odd exibida e tempo de resposta da aceitação.
Suspender ou rejeitar quando o status do mercado ou o risco forem incertos.
Armazenar a odd aceita independentemente daquela mostrada antes.
Testar mudanças rápidas, interrupções e envios repetidos sob carga.
A resposta ao jogador precisa diferenciar aceitação de rejeição. Não existe um prazo universal de aprovação ou pagamento aplicável a todos os mercados e jurisdições. [2] [7]
O que auditar em segurança, regras e monitoramento?
Autentique serviços e autorize operações por cliente e marca; proteja segredos, use transporte criptografado e registre uma trilha de auditoria. O leitor de odds não deve poder aprovar apostas ou alterar carteiras. A referência de cada ticket deve passar por verificação de permissão.
Alertar sobre odds antigas, perdas de sequência e tentativas em mercados suspensos.
Comparar bilhetes pendentes, aceitos e liquidados com relatórios autorizados.
Simular POST repetido, timeout, callback falsificado e rollback fora de ordem.
Documentar licenças, guarda de dados e reclamações conforme a jurisdição.
Acompanhe disponibilidade do feed e exatidão financeira em painéis separados. Processar muitas mensagens não elimina necessariamente bilhetes sem resultado, passivos em aberto ou pagamentos duplicados.
Qual checklist usar antes de ativar a API de sportsbook?
Teste todo o ciclo em ambiente controlado: alteração da odd, mercado suspenso, rejeição, aceite, resultado tardio, void, rollback, restauração do feed e diferença de saldo. Cada cenário deve deixar evidências do evento original até o lançamento final.
Validar IDs, permissões comerciais, precisão da odd e validade da cotação.
Exercitar idempotência, timeouts, rejeições e recuperação de reservas.
Demonstrar liquidação, cancelamento, estornos e conciliação em testes.
Obter aprovações técnicas, operacionais e legais antes da ativação.
Uma integração pronta não se resume a mostrar odds ou devolver um número de aposta. Ela consegue demonstrar por que cada ticket foi aceito, como chegou ao resultado e qual registro justifica cada ajuste de dinheiro.