Integrações de API iGaming

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.

Três camadas conectadas de sportsbook representando mercados de odds, validação de apostas e registros de liquidação
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.

IdentificadorFunçãoCuidado
Evento de origemPartida no feedPreservar o fornecedor
MercadoTipo de aposta e linhaGuardar parâmetros
SeleçãoResultado escolhidoNão usar só o texto
Versão da oddRevisão do preçoRejeitar versão antiga
ID do bilheteAposta aceitaEstável em nova tentativa
ID de liquidaçãoEvento de resultadoAssociar 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.

  1. Receber seleção, stake, preço e uma chave única para a operação.
  2. Checar novamente mercado, cotação, saldo disponível e regras de risco.
  3. Obter a decisão autorizada: aceito, rejeitado ou pendente.
  4. Registrar bilhete e reserva uma única vez; em repetição, retornar o resultado salvo.
Fluxo da integração de sportsbook com feed de odds, confirmação do bilhete e liquidação da aposta
As 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]

ProblemaAçãoConferência
Mensagem duplicadaIgnorar por chaveSem segundo efeito
Lacuna na sequênciaSuspender uso inseguroReexecutar ou consultar
Feed desconectadoBloquear cotação antigaFonte atualizada
Resultado tardioProcessar evento próprioBilhete relacionado
ReinicializaçãoRetomar cursor salvoSem 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]

  1. Conservar stake, odd aceita, parâmetros do mercado e versão das regras.
  2. Aplicar resultados apenas a bilhetes conhecidos e origem autenticada.
  3. Lançar prêmio ou restituição uma vez com chave única de liquidação.
  4. 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 bilheteAção na carteiraEvidência
CotaçãoNão debitarPedido e vencimento
AceitoReservar stake uma vezReferência aceita
RejeitadoLiberar reservaMotivo do retorno
LiquidadoPagar ou encerrar perdaResultado e lançamento
CorrigidoReverter ou reembolsarID 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.

  1. Validar IDs, permissões comerciais, precisão da odd e validade da cotação.
  2. Exercitar idempotência, timeouts, rejeições e recuperação de reservas.
  3. Demonstrar liquidação, cancelamento, estornos e conciliação em testes.
  4. 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.

Fontes e leituras complementares

Visualizador de diagramas