Integração com a Betshield

A integração tem duas etapas. Vocês enviam uma amostra, nós escrevemos o mapeamento, e então vocês ligam o envio.

Não é necessário renomear campos. Enviem os eventos com os nomes e valores que o sistema de vocês já usa. A tradução é escrita do nosso lado.

Visão geral

Etapa	Responsável	O que acontece
1. Amostra	Vocês	Enviam um arquivo com eventos reais, a descrição dos campos, os dados da conta, e respondem as cinco perguntas
2. Mapeamento	Betshield	Escrevemos a tradução e validamos contra a amostra
3. Credenciais	Betshield	Enviamos o acesso ao painel e uma chave de API por marca
4. Envio	Vocês	Ligam o envio para fluxo contínuo

Aposta esportiva e aposta de cassino

Ambas usam o mesmo endereço e o mesmo tipo de evento. Não há endpoint separado para cassino.

A modalidade é identificada por um campo. Na aposta esportiva, o esporte. No cassino, o que identifica o jogo, seja o nome, o provedor ou a categoria. Se os formatos forem diferentes, incluam exemplo de cada um na amostra.

Liquidação de rodadas de cassino

Vocês emitem evento de liquidação para a rodada que perdeu, ou apenas para a que pagou?

Alguns operadores emitem apenas a rodada premiada. Perda é o principal indicador de risco, e sem ela duas das oito características do score ficam sem dado na maior parte do volume.

Etapa 1 — Amostra

Um arquivo, preferencialmente JSON, com eventos reais de cada tipo que vocês emitem, acompanhado da descrição dos campos.

Requisito	Por quê
Gerada pelo sistema que fará o envio	Se o formato divergir, o mapeamento aponta para campos inexistentes e os eventos são descartados sem erro
Um exemplo de cada tipo de evento	Inclusive os que parecem irrelevantes, e os dois formatos quando esporte e cassino diferem
Indicação dos eventos condicionais	Se algum tipo só é emitido em certas situações, precisamos saber qual

Exemplo

Exemplo fictício. Enviem no formato de vocês.

{
  "eventos": [
    {
      "tipo_evento": "aposta_criada",
      "cpf_cliente": "12345678901",
      "id_evento": "EV-2026-8814-0001",
      "momento": "2026-08-14T14:30:00-03:00",
      "valor_aposta": 25.00,
      "cotacao": 2.35,
      "esporte": "Futebol",
      "ao_vivo": "S"
    },
    {
      "tipo_evento": "aposta_liquidada",
      "cpf_cliente": "12345678901",
      "id_evento": "EV-2026-8814-0002",
      "momento": "2026-08-14T16:52:11-03:00",
      "valor_aposta": 25.00,
      "retorno": 0.00,
      "resultado": "PERDEU"
    },
    {
      "tipo_evento": "deposito",
      "cpf_cliente": "12345678901",
      "id_evento": "EV-2026-8814-0003",
      "momento": "2026-08-14T17:03:45-03:00",
      "valor": 100.00,
      "meio_pagamento": "PIX"
    }
  ]
}

Descrição dos campos

Enviem também a descrição de cada campo. É a partir dela que escrevemos o mapeamento e decidimos o que aproveitar primeiro. Uma linha por campo basta, no formato abaixo.

Campo             Tipo     Descrição
tipo_evento       texto    Tipo do evento. Valores: aposta_criada,
                           aposta_liquidada, deposito, saque,
                           inicio_sessao, fim_sessao
cpf_cliente       texto    CPF do apostador, 11 dígitos, sem pontuação
id_evento         texto    Identificador único do evento, em todos os tipos
momento           texto    Data e hora do evento, ISO 8601 com fuso
valor_aposta      número   Valor apostado, em reais
retorno           número   Valor pago na liquidação. Zero quando perde
resultado         texto    Resultado da aposta. Valores: GANHOU, PERDEU,
                           ANULADA, CASH_OUT
esporte           texto    Esporte. Ausente nas apostas de cassino
ao_vivo           texto    Aposta com o evento em andamento. Valores: S, N
meio_pagamento    texto    Forma de pagamento. Valores: PIX, BOLETO, CARTAO

Nos campos que só aceitam uma lista fixa de valores, como resultado e meio de pagamento, incluam a lista completa, escrita exatamente como o sistema grava.

Campos além dos listados na documentação são bem-vindos. O evento é armazenado íntegro e nada é recusado por não constar da lista.

O que responder junto com a amostra

1. Identificação do apostador

CPF em texto ou já em SHA-256? Se for hash, confirmem que é o SHA-256 do CPF apenas com dígitos. Descubra como calcular o hash.

2. Valores do campo de resultado

A lista completa dos valores possíveis, inclusive os raros, como cancelamento, devolução e encerramento antecipado.

O mesmo vale para qualquer campo que só aceite uma lista fixa de valores, como meio de pagamento ou aposta ao vivo.

3. Identificador único por evento

Existe um identificador próprio em todos os eventos? Com ele, um lote reenviado não é contado duas vezes.

Se existir apenas em parte dos eventos, não declaramos o campo, porque declarar o torna obrigatório e os eventos sem ele são recusados.

4. Marcas

Os eventos de todas as marcas saem do mesmo sistema, no mesmo formato? Cada marca recebe uma chave própria, e o envio é separado por chave.

5. Histórico

Quanto tempo para trás vocês conseguem enviar? A carga histórica usa o mesmo endereço e formato do envio corrente.

Dados para criar a conta

Dado	Detalhe
Razão social	Como consta no CNPJ da licença
CNPJ	Da licença, não das marcas
Marcas	Nome comercial de cada uma
E-mail do administrador	Uma pessoa, com e-mail individual. Recebe o acesso ao painel e convida o restante do time

Etapa 2 — Envio

Com as chaves em mãos, a integração está documentada por completo em Enviar Eventos, com endereço, formato, exemplos em quatro linguagens, data e hora, idempotência e limites.

Um ponto merece atenção antes de ligar o envio. O código 200 indica que a requisição foi recebida, não que os eventos foram aproveitados. Essa informação está em accepted. Quando ele retorna zero com total maior que zero, a resposta traz o campo warning com o motivo, e recebemos um alerta simultâneo.

Resumo

Etapa 1. Enviem a amostra gerada pelo sistema de envio, com um exemplo de cada tipo de evento, a descrição dos campos, as respostas das cinco perguntas e os dados para criar a conta.

Etapa 2. Liguem o envio no mesmo formato, em lotes de até 2.000, acompanhando o campo accepted.

Qualquer alteração no formato de envio deve ser comunicada antes.