Recursos

GUIA PARA OPERADORES

Guia de integração de API de loteria: o que especificar

Uma integração de API de loteria não termina quando a primeira solicitação retorna com sucesso. Ela termina quando o operador consegue rastrear uma transação entre sistemas, resolver um resultado incerto sem criar outra compra e atender ao jogador sem adivinhar qual sistema é a fonte oficial.

Este guia de integração de API de loteria é um documento para contratação e implementação. Explica o que especificar antes de escolher a modalidade de entrega e quais evidências solicitar antes do aceite. Não é documentação da API WhiteLotto: os exemplos apresentam requisitos a discutir, não endpoints, métodos de autenticação, integrações ou funcionalidades incluídas confirmados. Comece pela visão geral da solução WhiteLotto e combine o escopo real das interfaces com a equipe de entrega.

Comece pelos limites da integração, não pela lista de endpoints

Identifique o sistema responsável pela conta do jogador, livro-razão da carteira, registro do bilhete, informações do sorteio, decisão de verificação e comunicação com o cliente. Uma interface separada, um back office existente e um serviço externo de pagamentos criam limites diferentes. Uma API pode expor uma função sem transferir sua responsabilidade operacional.

Desenhe a jornada de uma transação e marque cada passagem. Para cada limite, registre sistema chamador, registro oficial, ação permitida, resposta esperada e responsável por um estado não resolvido. Inclua acesso ao back office e relatórios: uma integração que permite comprar, mas impede a conciliação financeira, está incompleta.

Inclua o mapa no documento de avaliação de fornecedores. Classifique cada capacidade solicitada como disponível e comprovada, configurável, personalizada, dependente de terceiros ou fora do escopo. Um item do roadmap não é uma interface com entrega contratada.

API, iFrame ou front-end completo: defina o limite de responsabilidade

Uma integração por API, um iFrame incorporado e um front-end entregue pelo fornecedor colocam partes diferentes da jornada do jogador sob seu controle. Escolha conforme a experiência que precisa gerenciar, os sistemas existentes e a equipe disponível para manter a conexão. Essa decisão é independente da denominação comercial “white label” ou “turnkey”: combine o escopo real da interface e de sua operação.

Use a visão geral dos módulos da plataforma para identificar o que permanece na infraestrutura atual. Compare as alternativas com a mesma jornada de compra, em vez de avaliar uma demonstração isolada.

Modelos de integração de loteria e decisões necessárias
ModalidadeInterface do jogadorResponsabilidades a combinarFoco do aceite
API com front-end próprioSua equipe desenvolve a jornada de loteria sobre as interfaces acordadas.Versões da interface, manutenção do adaptador, correspondência de contas e suporte operacional.O comportamento técnico e a jornada do cliente precisam funcionar juntos.
iFrame incorporadoUma interface de loteria fornecida é inserida no site existente.Transferência de sessão, navegação externa, comunicação entre interfaces e encaminhamento de incidentes.Entrada, compra, recuperação e retorno ao site principal.
Front-end completo fornecidoA jornada do site acordada é entregue dentro do escopo da plataforma.Marca, alterações de conteúdo, contas, limites da carteira, versões e exportações.Toda a jornada acordada, incluindo administração e relatórios.

Resolva os limites de conta, carteira e sessão antes de aprovar o design

Em um cassino ou sportsbook existente, especifique se o jogador de loteria usa a conta atual, uma conta vinculada ou um cadastro separado. Identifique o sistema que aplica restrições e o que acontece se a verificação ou as permissões mudarem durante uma sessão ativa. Pergunte como o jogador retorna após sair da conta, trocar de dispositivo ou abrir um link expirado. Uma tela incorporada atraente não resolve essas questões operacionais.

Separe o saldo exibido do registro financeiro de referência. Combine qual sistema autoriza uma compra e como a interface principal recebe mudanças de fundos, bilhetes ou permissões. O guia de carteira e conciliação trata do limite financeiro; o modelo de integração precisa explicar como o jogador percebe esse limite.

Atribua um responsável a cada erro visível. Diferencie um problema de sessão no site principal, uma interface incorporada indisponível, uma ação de loteria rejeitada e uma transação não resolvida. Defina a mensagem, a próxima ação permitida e a referência para o suporte. Ao reabrir a página, o jogador deve chegar a um estado acordado, com um caminho de investigação se o resultado continuar incerto.

Aceite o modelo de integração, além das transações individuais

Acrescente verificações específicas do modelo à lista de aceite UAT e entrada em produção. Teste a entrada pelo site principal, a expiração de sessão durante a escolha de números, uma alteração de restrições, um componente indisponível e o retorno do pagamento. Inclua navegação móvel, acesso pelo teclado e o caminho até o histórico de bilhetes.

Para cada cenário, registre o sistema responsável, a tela esperada, o estado de conta ou transação de referência e a pessoa encarregada da resolução. Inclua o encaminhamento de suporte entre equipes. A modalidade está pronta quando essas responsabilidades são aceitas em conjunto, não apenas quando uma tela carrega ou uma interface responde.

CONTATO para discutir seu front-end, seus sistemas de conta e carteira e a jornada de loteria que deseja adicionar.

Crie um registro de requisitos que os fornecedores possam responder

Use uma linha por interface ou operação, em vez de uma única linha chamada “integração de API”. Acrescente responsável, prioridade, dependência, referência da evidência e decisão de aceite às perguntas abaixo.

Requisitos de API de loteria a resolver antes da implementação
ÁreaRequisito a definirEvidência a solicitar
Contrato da interfaceOperações, campos, identificadores, erros, versão e ambiente suportado.Especificação versionada e exemplos representativos de solicitações e respostas sintéticas.
Limite de acessoClientes, funções, marcas e recursos permitidos; emissão, rotação e revogação.Matriz de acesso e testes de ações negadas para a implantação acordada.
Dinheiro e bilhetesRegistros oficiais, transições de estado, encerramento de vendas e duplicações.Rastro conectando referências de bilhete, carteira e fornecedor.
Eventos assíncronosAutenticação, duplicações, ordem, novas tentativas e recuperação após lacunas.Contrato de eventos documentado e resultados de falhas.
Capacidade e limitesPicos previstos, concorrência, timeouts, limites de solicitações e sobrecarga.Premissas de carga acordadas e evidências de testes do escopo.
Dados e relatóriosCampos, retenção, permissões de exportação, timestamps e visões de conciliação.Dicionário de dados e exportação de exemplo utilizável, sem registros pessoais.
Mudanças e suporteCompatibilidade, aviso de descontinuação, incidentes e condições de saída.Processo de versões, escalonamento e escopo contratual.

A especificação OpenAPI fornece uma forma padronizada de descrever interfaces HTTP. Pergunte se a interface proposta tem uma descrição atualizada, qual versão usa e quais comportamentos exigem documentação separada. Um contrato legível por máquinas facilita a revisão; não comprova correção das transações, segurança ou suporte operacional.

Acorde o modelo de dados e o sistema de registro

Mapeie identificadores entre operador, plataforma e serviço externo. Diferencie identificador da solicitação, identificador do bilhete, referência do pagamento e lançamento contábil. Defina como o suporte os relaciona sem colocar informações pessoais em URLs ou logs sem restrição.

Especifique valores, moedas, precisão, fusos, significado dos timestamps e estados. “Aceito” pode significar recebido para processamento, não bilhete confirmado. “Pago” pode representar evento do processador, não liquidação final. Documente quem altera cada estado e como as correções são registradas.

Para sorteios e resultados, defina fonte oficial, atualização, política de correções e responsável por liquidar bilhetes afetados. Especifique o fuso do encerramento e a regra para solicitações próximas ao limite; a contagem regressiva na interface não decide a aceitação do bilhete.

Solicite apenas os dados do jogador necessários a cada integração. Defina acesso, retenção, exportação e uso permitido com os responsáveis. O guia de titularidade dos dados do jogador separa acesso operacional útil de questões contratuais e de privacidade. Conectividade não estabelece direito de transferir ou reutilizar registros.

Projete para resultados incertos e mensagens repetidas

Considere uma compra sintética em que o receptor aceita a solicitação, mas a conexão fecha antes da confirmação chegar ao chamador. Um timeout não prova ausência de processamento. A especificação precisa de um mecanismo suportado para determinar o resultado original e impedir outro efeito financeiro na repetição.

A semântica HTTP da RFC 9110 distingue operações idempotentes e alerta contra repetir automaticamente solicitações não idempotentes sem saber que é seguro. Para compras e alterações na carteira, acorde política de duplicação da aplicação, duração da proteção e tratamento da mesma referência com conteúdo diferente. Não deduza garantias apenas do método HTTP.

Para eventos ou callbacks, pergunte como o receptor verifica origem, detecta duplicações, trata entregas atrasadas ou fora de ordem e recupera processamento perdido. Como exemplo específico de fornecedor, a documentação de webhooks da Stripe aborda assinaturas, repetições e processamento assíncrono. Ilustra perguntas contratuais; não prova uso da Stripe pela WhiteLotto nem suporte ao mesmo modelo.

O aceite deve conectar resultado final aos registros: uma compra pretendida, efeito acordado na carteira, estado rastreável do bilhete e exceção com responsável se a confirmação continuar pendente. Aplique a mesma disciplina a reembolsos, reversões e liquidação. O guia da estrutura de pagamentos de loteria explica por que resposta de pagamento bem-sucedida e conciliação útil são requisitos diferentes.

Inclua segurança e capacidade no aceite

Confirme autenticação real, escopos, responsável por credenciais, armazenamento, rotação e revogação. Nunca coloque credenciais de produção em documento de contratação, exemplo compartilhado ou código entregue ao navegador. Separe ambientes e use dados sintéticos nas demonstrações.

Verifique autorização para a operação e o recurso solicitado, não apenas a existência de login válido. Peça testes de função não autorizada, limite entre marcas ou contas e cliente revogado. O OWASP API Security Top 10 orienta questões de acesso a objetos, autenticação, consumo de recursos e inventário. Não é certificação nem evidência de aprovação de uma plataforma.

Descreva carga esperada: tráfego regular, pico de sorteio, compras concorrentes, relatórios e recuperação de eventos atrasados. Acorde reação aos limites e solicitações que podem ser adiadas com segurança. Registre fronteiras de medição de latência e disponibilidade, incluindo dependências, em vez de inserir metas sem comprovação. Use o checklist de segurança, disponibilidade e SLA para ampliar evidências e escalonamento.

Use um pacote de aceite pequeno e completo

Registre versão, configuração, ambiente, dados sintéticos, resultado esperado e evidência real de cada teste. Inclua chamador, receptor e responsável operacional. Uma gravação da tela não estabelece sozinha o estado resultante do livro-razão ou bilhete.

  • Rastreie uma jornada bem-sucedida da solicitação ao resultado confirmado e relatório.
  • Exercite solicitação recusada ou inválida, limite de encerramento e resposta não resolvida.
  • Repita solicitação e evento de teste permitidos para verificar a política acordada.
  • Teste acesso negado, expirado ou revogado, entradas malformadas e limites.
  • Interrompa dependência externa e demonstre recuperação ou fila de exceções com responsável.
  • Verifique investigação por suporte e finanças com registros permitidos.

Separe defeitos bloqueantes de melhorias opcionais. O checklist de demonstração da plataforma organiza uma discussão baseada em evidências, mas uma demonstração não substitui o aceite da integração contratada.

Teste operações API não resolvidas, não apenas respostas corretas

Solicite uma demonstração isolada com registros sintéticos: envie uma solicitação de bilhete, interrompa a confirmação e tente novamente com a mesma chave de operação. A evidência deve conectar solicitação, estado do bilhete e registro financeiro sem fazer um pagamento real.

  • Especifique qual sistema controla o resultado definitivo e como consultá-lo quando a primeira resposta não está disponível.
  • Defina estados pendente, aceito, rejeitado e cancelado; uma expiração não significa automaticamente que a compra falhou.
  • Repita solicitação e notificação para verificar que bilhetes e lançamentos financeiros não são duplicados.
  • Inclua operações não resolvidas em uma exportação de conciliação, com referências, horários e um responsável pela resolução.

Inclua tempo de recuperação e responsáveis pelo escalonamento nos requisitos de serviço. Leve os mesmos cenários à matriz de aceitação do RFP, sem tratar uma lista de interfaces API como prova de recuperação.

Escolha primeiro a arquitetura e depois priorize cada integração

Mantenha este guia como o mapa principal de requisitos. Não comece com todos os fornecedores disponíveis ao mesmo tempo: escolha os sistemas oficiais de registro e a menor jornada completa exigida para a versão acordada. Registre, para cada interface, a dependência de negócio, o responsável pelos dados, o responsável pelo adaptador, o acesso exigido de terceiros e a evidência de aceite.

Frentes específicas de integração de loteria
Frente de trabalhoDecisão antes do desenvolvimentoGuia detalhado
Sorteios e resultadosIdentidade autoritativa do sorteio, encerramento das vendas, revisões de resultados e responsabilidade pela liquidação.Integração de sorteios e resultados
PagamentosRegra de crédito da carteira, repetição segura, eventos verificados e conciliação financeira.Integração de gateway de pagamento
KYCMapeamento de estados de decisão, permissões da conta, tratamento manual e dados necessários.Requisitos de integração KYC
VarejoAceitação válida do bilhete, política offline, recuperação de dispositivos e acerto dos pontos de venda.Integração POS no varejo
Contas de jogadores (PAM)Responsabilidade pela identidade, estados, restrições, acesso à sessão e recuperação de eventos.Integração de gestão de contas
Assinaturas e múltiplos sorteiosRenovação versus compra antecipada, novas tentativas de pagamento, encerramento e alocação de bilhetes.Requisitos de assinaturas e múltiplos sorteios
Prêmio instantâneo e raspadinhas digitaisCompromisso da rodada, responsabilidade pelo resultado, lançamentos e recuperação de partidas interrompidas.Checklist de integração de prêmio instantâneo
Risco de jackpot e financiamento de prêmiosObrigações de prêmios, origem dos recursos, limites de exposição e evidências de liquidação.Financiamento de prêmios e avaliação de risco

Organize as dependências ao redor de uma transação recuperável

Para uma jornada de compra, acorde em conjunto o limite de conta e controles, as regras de adição de fundos ou carteira, o registro do bilhete aceito, o tratamento de sorteios e resultados e a exportação financeira. Desenvolva e teste uma jornada fictícia de ponta a ponta antes de multiplicar os fornecedores. Um conjunto desconectado de chamadas de API bem-sucedidas ainda pode deixar o suporte sem condições de resolver uma compra incerta.

Separe “precisa estar pronto para a versão” de “extensão comercial posterior”. O escopo da integração inclui monitoramento, acesso a ambientes de teste, recuperação de eventos, documentação e coordenação de parceiros, não apenas o código do adaptador. Um fornecedor que ainda não aprovou o modelo operacional ou forneceu um ambiente de testes utilizável continua sendo uma dependência, mesmo quando o desenvolvimento interno terminou.

Inclua a responsabilidade pelas mudanças no contrato

Mantenha um inventário versionado de interfaces com o responsável e a política de descontinuação. Acorde como mudanças em campos, assinaturas, significados de status e relatórios são anunciadas e aceitas. Preserve o caminho para a versão anterior quando isso for seguro, mas reconheça que reverter um adaptador não desfaz os registros financeiros já gravados.

A especificação OpenAPI é uma referência para descrever contratos HTTP. As transições de estado de negócio, os procedimentos de recuperação e os limites de responsabilidade ainda precisam de documentação explícita complementar. Converta os requisitos acordados na matriz de aceite UAT e use o modelo de KPIs para confirmar que a integração em produção permanece observável.

Orce a responsabilidade após a primeira versão

Nomeie responsáveis por adaptadores, regras de monitoramento e incidentes. Acorde compatibilidade, avisos de mudanças, atualização segura e quem paga mudanças fora do escopo. Inclua coordenação de parceiros, relatórios, acesso de teste e migrações futuras, não apenas programação da conexão inicial.

Leve o registro a uma conversa de escopo de integração com WhiteLotto. Apresente diagrama entre sistemas, operações, premissas de tráfego, sequência e dependências pendentes. Pergunte o que pode ser comprovado agora e o que exige descoberta adicional. Não envie exportações de jogadores, credenciais ou logs privados de produção.

Perguntas frequentes sobre integração de API de loteria

Este guia documenta a API WhiteLotto?

Não. É um guia de requisitos e aceite. Obtenha da equipe a especificação vigente acordada e o escopo antes de desenvolver sobre uma interface.

Uma API elimina a conciliação?

Não. Interfaces transportam informações; a conciliação determina a correspondência de registros e o responsável pelas diferenças. Defina-a para carteira, bilhetes, pagamentos e liquidação.

É possível estimar integração com uma lista de fornecedores?

A lista é um começo. Uma estimativa confiável também precisa de operações, contratos, ambientes, mapeamento, falhas, carga e responsabilidades de aceite.

Podemos manter nossos sistemas atuais de carteira, pagamentos, KYC e CRM?

A manutenção de um sistema existente deve ser avaliada conforme o escopo acordado e suas interfaces atuais e documentadas; a expressão “integração por API” não a garante. Identifique o sistema que mantém o registro de referência de contas, saldos, decisões de verificação e mensagens ao cliente e, em seguida, mapeie identificadores e estados de negócio entre os sistemas. Defina as ações permitidas, o tratamento de exceções, as evidências de aceite e um responsável por cada conexão. Inclua esses requisitos na lista de avaliação para a solicitação de propostas antes de decidir quais componentes serão mantidos, quais precisarão de adaptadores e quais exigirão uma divisão diferente de responsabilidades operacionais.

Como devem ser tratadas as novas tentativas e as notificações duplicadas?

Defina no contrato da interface o comportamento exigido para novas tentativas: uma referência de negócio estável e um escopo explícito de idempotência, com um período de proteção acordado. As notificações recebidas exigem verificação de origem e detecção persistente de duplicatas para impedir que uma repetição crie outro bilhete ou lançamento financeiro. Quando uma resposta for incerta, exija consulta de status ou conciliação antes de repetir a operação às cegas. Os testes de aceite devem cobrir notificações duplicadas ou fora de ordem, respostas interrompidas e solicitações repetidas com conteúdo alterado. O guia de integração de gateways de pagamento apresenta uma lista específica de requisitos; não documenta os endpoints da WhiteLotto.

Wojciech Lysak é o diretor-geral da WhiteLotto.com. LinkedIn