API de feed de odds: do snapshot à liquidação das apostas

Um ecrã de apostas parece estático: uma lista de jogos, uma coluna de odds. Por baixo, um feed de odds é um fluxo de milhares de pequenas alterações, e o trabalho do operador é aplicar cada uma delas pela ordem certa. Este guia percorre esse fluxo desde o primeiro pedido até à aposta liquidada.

1. O modelo de dados

Quase todos os feeds usam a mesma hierarquia:

• Desporto: futebol, ténis, esports.
• Torneio ou liga: Premier League, ATP Tóquio, League of Legends Worlds.
• Evento: um jogo, com hora de início e participantes.
• Mercado: uma pergunta sobre o evento, como 1X2, mais/menos de 2,5 golos ou handicap de mapa.
• Resultado: uma resposta, com uma odd e um estado (ativo, suspenso, liquidado).

Cada elemento tem um identificador estável. A maioria dos bugs de integração vem de tratar nomes como identificadores: os nomes das equipas mudam de grafia, os IDs não.

2. Primeiro o snapshot, depois os deltas

No arranque, o cliente pede um snapshot: o estado atual completo. A partir daí recebe deltas, pequenas mensagens que dizem “esta odd mexeu”, “este mercado está suspenso”, “este evento começou”.

Os bons feeds numeram os deltas. A Nocturn Sport, por exemplo, descreve o seu feed como um snapshot completo mais deltas com versão. Se o cliente tem a versão N e recebe a N+2, sabe que se perdeu uma mensagem e recarrega em vez de mostrar uma odd desatualizada. Os feeds sem versões obrigam o cliente a adivinhar, e é a adivinhar que as casas acabam a oferecer as odds de ontem.

3. Push e pull

O futebol ao vivo pode mudar de odd várias vezes por minuto, por isso os feeds ao vivo costumam enviar mensagens em push através de uma ligação persistente. As odds pré-jogo mexem devagar o suficiente para que fazer pull por HTTP a cada poucos segundos funcione muitas vezes bem. Muitos operadores usam os dois: pull para o catálogo pré-jogo, push para o ao vivo.

4. Suspensões

Uma suspensão é o feed a dizer “não aceite apostas nisto agora”. Os gatilhos incluem um golo, um penálti, uma quebra de serviço, o fim de um mapa ou a perda da fonte de dados do próprio fornecedor. O cliente tem de aplicar as suspensões mais depressa do que tudo o resto; uma odd aceite nos segundos a seguir a um golo é a forma clássica de perder dinheiro.

Os mercados pré-jogo também fecham antes do apito inicial. A Nocturn Sport, por exemplo, fecha-os um minuto antes do início.

5. Colocar a aposta

Se a API vai além de publicar odds, a colocação de apostas segue um padrão:

1. O cliente envia a seleção, a odd que mostrou e o valor apostado, com um ID de pedido único.
2. O servidor verifica se a odd continua válida e o mercado aberto.
3. Aceita, rejeita ou propõe uma nova odd.
4. Se a rede falhar, o cliente reenvia com o mesmo ID de pedido, e o servidor devolve a resposta original em vez de criar uma segunda aposta.

Este último passo, a idempotência, protege tanto o saldo do jogador como as contas do operador.

6. Liquidação

Quando o evento termina, o feed publica os resultados por seleção: ganha, perdida, anulada, ou meio ganha e meio perdida nas linhas divididas como os handicaps asiáticos. A plataforma liquida cada aposta com base neles. Há correções: um resultado pode ser alterado depois de revisto, por isso um processo de liquidação tem de conseguir voltar a liquidar de forma limpa.

7. O que testar antes de entrar em produção

• Corte a ligação a meio de um jogo e verifique a recuperação.
• Reproduza um delta fora de ordem e verifique se o cliente dá por isso.
• Coloque a mesma aposta duas vezes com um único ID de pedido.
• Liquide uma múltipla em que uma das seleções é anulada.

Um feed que sobrevive a estes quatro testes está pronto para uma tarde de sábado.