Odds, apostas e cupons — documentação técnica da API

• API de URL base;
• login e senha da conta do cliente;
• ao usar retorno de chamada - habilite a função e a frase secreta callback_secret.

Os exemplos usam um endereço condicional:

BASE_URL="https://coupon-api.example.com"

Na produção, use HTTPS. Todas as datas são transmitidas como carimbo de data/hora Unix em milissegundos e os valores monetários são transmitidos como números decimais sem precisão fixa.

Sucesso:

{
  "code": 1,
  "body": {},
  "error_code": null,
  "error_message": null,
  "date": 1784970000000,
  "time_ms": 5,
  "path": "/api/partner/example"
}

O erro comercial geralmente também vem com HTTP 200:

{
  "code": 0,
  "body": null,
  "error_code": 1002,
  "error_message": "Not all params",
  "date": 1784970000000,
  "time_ms": 5,
  "path": "/api/partner/example"
}

Sempre verifique o código HTTP, depois code e depois error_code. Não use o texto error_message como chave de software.

POST /api/partner/login
Content-Type: application/json

{
  "username": "partner-demo",
  "password": "strong-password"
}

O campo login é suportado como um alias compatível username.

Resposta bem sucedida:

{
  "code": 1,
  "body": {
    "token": "<jwt-token>",
    "user_id": 17,
    "username": "partner-demo"
  },
  "error_code": null,
  "error_message": null
}

Em todas as solicitações protegidas, passe:

Authorization: Bearer <jwt-token>

Erros básicos de login:

Esses erros são retornados de HTTP 200, code = 0. HTTP 401 de um método protegido significa que o JWT está ausente, é inválido, expirou ou foi revogado; Faça login novamente. HTTP 403 significa função inadequada ou acesso negado.

Cada resultado selecionado é transmitido como uma linha pronta da linha esportiva:

line_type#game_id#group_id#type_id#rate#coefficient[#player_id]

Exemplos:

line#737779544#1#1#0#1.85
live#738917381|119|5869|0.5#3.6#149439538

• line_type: line ou live;
• rate: parâmetro total/handicap ou 0;
• player_id: ID do jogador opcional;
• delimitadores # e | são suportados.

Não colete ou corrija o ponteiro manualmente - passe o valor obtido na linha inalterado.

POST /api/partner/coupons/place
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "list_bets": [
    "line#737779544#1#1#0#1.85"
  ],
  "amount": 10,
  "currency": "USD",
  "callback_url": "https://partner.example.com/api/coupon-result",
  "lang": "en",
  "mode": "reject",
  "mode_type": null,
  "multi": false
}

Probabilidades

Comum, expresso e multi

Um trem expresso não pode conter mais de 15 eventos. Você não pode combinar múltiplas apostas na mesma partida, incluindo a partida principal, tempos, períodos, escanteios, faltas e outros subeventos relacionados. Esta combinação retorna 506.

Resposta completa bem-sucedida com cupom e dados de apostas aceitas dentro de events_data:

{
  "code": 1,
  "body": {
    "coupons": [
      {
        "coupon_code": "000000000272",
        "amount": 10,
        "win": 18.5,
        "potential_win": 18.5,
        "real_win": null,
        "coef": 1.85,
        "original_coef": 1.85,
        "calculate_coef": null,
        "has_return": false,
        "date": 1784970000000,
        "status": 0,
        "asian": false,
        "calculate_date": null,
        "coupon_type": 1,
        "events_count": 1,
        "events_data": [
          {
            "id": 912,
            "game_id": 737779544,
            "main_game_id": 737779544,
            "is_sub_game": false,
            "parent_game_id": null,
            "sub_game_key": null,
            "raw_pointer": "line#737779544#1#1#0#1.85",
            "line_type": "line",
            "is_live": false,
            "bet_group_id": 1,
            "bet_group_name": "Match result",
            "bet_id": 1,
            "bet_name": "First team to win",
            "sport_id": 1,
            "sport_name": "Football",
            "tournament_id": 10001,
            "tournament": "National League",
            "event_date": 1784971800000,
            "status": 0,
            "opp1": "Team A",
            "opp2": "Team B",
            "coef": 1.85,
            "calc_coef": null,
            "bet_score": "line#737779544#1#1#0#1.85",
            "calculate_date": null,
            "calculate_score": null,
            "settlement_reason_code": null,
            "settlement_reason": null,
            "placement_score_full": null,
            "placement_score_periods": null,
            "calculation_score_full": null,
            "calculation_score_periods": null,
            "timer": null,
            "dop_name": null,
            "rate": "0",
            "sgame_id": null,
            "game_num": null,
            "stat_id": null,
            "team1_id": 101,
            "team2_id": 102,
            "opp_icon1": 101,
            "opp_icon2": 102
          }
        ]
      }
    ]
  },
  "error_code": null,
  "error_message": null,
  "date": 1784970000015,
  "time_ms": 45,
  "path": "/api/partner/coupons/place"
}

Campos de cupom

Cada item body.coupons[] é um cupom separado criado.

Campos de lance

Cada elemento de events_data[] descreve uma aposta específica aceita dentro do cupom.

O valor null é normal para dados que ainda não foram calculados ou não estão disponíveis. Não o substitua automaticamente por 0 ou pela sequência vazia.

Considerar o cupom aceito somente se code = 1 e presença de objetos em body.coupons. Antes disso, a cesta é uma escolha preliminar: a seleção pode desaparecer, ser bloqueada ou as probabilidades mudarem.

Depois do sucesso:

1. salve todos os objetos body.coupons, não apenas o primeiro;
2. armazene coupon_code como uma string com zeros à esquerda;
3. salve os dados necessários de events_data;
4. combinar o cupom com o usuário final;
5. registrar a transação financeira do usuário no sistema do parceiro.

Identificadores:

currency não é retornado no modelo completo e no retorno de chamada. Se a moeda for necessária, salve o valor da solicitação de criação.

Para 501–504, a nova API retorna as taxas problemáticas em body.changes[]. Campo change_type: 1 - o coeficiente aumentou, 2 - diminuiu, null - a direção não é aplicável.

Não tente POST /coupons/place cegamente após o tempo limite: a primeira solicitação pode ter sido aceita e tentar novamente criará uma duplicata.

Você pode transferir até 100 valores usando códigos:

{
  "coupon_ids": ["000000000272", "000000000273"]
}

Ou passe o período de criação no máximo 24 horas:

{
  "start_date": 1784880000000,
  "end_date": 1784966400000
}

Não combine coupon_ids e datas na mesma consulta. results filtra por horário de criação e calculated filtra por horário de liquidação final.

Status do cupom:

Status de lance:

Para provisionamento financeiro para o usuário final, use o real_win pronto. Não use potential_win e não recalcule o pagamento você mesmo. Antes do cálculo, real_win, calculate_coef, calc_coef e calculate_date são iguais a null, não 0.

No primeiro status do cupom 15, caso o resultado anterior já tenha sido processado financeiramente, o parceiro debita novamente amount do usuário final, espera um novo status final e cobra um novo real_win. Proteja as operações contra reprocessamento.

Cada aposta no modelo completo e retorno de chamada possui:

Antes do cálculo, ambos os campos são iguais a null. Para uma notificação localizada, use um código como:

• MATCH_POSTPONED - a partida foi adiada;
• MATCH_CANCELLED - partida cancelada;
• MARKET_PUSH – retorno conforme regras de mercado.

Se o código for desconhecido, salve-o e use settlement_reason não vazio como texto substituto. Não calcule o pagamento por motivo - use status e real_win.

Esses campos explicam o cálculo ou retorno que já foi realizado e não são um feed separado em tempo real do status da correspondência.

O retorno de chamada é opcional. Um parceiro só pode trabalhar por meio de votação. Para callback o gestor deve habilitar a função e criar callback_secret; A URL é enviada em cada cupom criado.

O parceiro determina o URL de retorno de chamada de forma independente. Na produção deverá usar https://; em um ambiente de teste, http:// é permitido.

O sistema envia:

POST {callback_url}
Content-Type: application/json
X-Coupon-Signature: sha256=<hex_hmac_sha256>

Carga útil curta:

{
  "event": "coupons.settled",
  "batchId": "d407e986f3a64d9d36a77bf532322ef8",
  "couponCount": 1,
  "coupons": [
    {
      "coupon_code": "000000000272",
      "realWin": 18.5,
      "calculate_coefficient": 1.85,
      "status": 2,
      "calculate_date": 1784973600000,
      "events_data": [
        {
          "uuid": "912",
          "status": 1,
          "calculate_coefficient": 1.85,
          "calculate_date": 1784973600000,
          "calculate_score": "2:1",
          "settlement_reason_code": "REMOTE_WIN",
          "settlement_reason": "Win",
          "timer": 0
        }
      ]
    }
  ]
}

Regras obrigatórias:

1. calcule sha256=<hex(HMAC-SHA256(raw_body, callback_secret))> a partir dos bytes de origem exatos do corpo antes da análise JSON e compare as assinaturas de maneira segura;
2. processar todos os itens coupons, o pacote pode conter até 100 cupons;
3. armazene batchId com um índice exclusivo;
4. batchId repetido não deve repetir a baixa ou acumulação;
5. um coupon_code pode vir com diferentes batchId durante cálculo progressivo e recálculo;
6. retorne HTTP 200 somente depois que todo o pacote tiver sido armazenado com segurança.

A resposta mínima bem-sucedida é um HTTP 200 vazio. Avançado:

{
  "success": true,
  "processed": 1
}

processed deve ser igual a couponCount. As respostas 201, 202 e 204 não são consideradas bem-sucedidas.

As repetições são realizadas apenas em caso de timeout, erro de transporte ou HTTP 500, 502, 503, 504: imediatamente, depois de 1, 5, 15 e 60 minutos - não mais que cinco envios. Não há nova tentativa automática em HTTP 200 com success: false ou processed parcial.

Mesmo com retorno de chamada, verifique periodicamente os resultados:

GET /api/partner/coupons/calculated?time=10

Após um intervalo de mais de 120 minutos, use POST /api/partner/coupons/results em coupon_ids salvo ou em períodos de criação de até 24 horas. Receber novamente a mesma fortuna não deve repetir transações financeiras.

• armazenar login, senha, JWT e callback_secret somente no servidor;
• não passe JWT na URL e não escreva o token completo nos logs;
• use o tipo decimal para dinheiro;
• armazene coupon_code como uma string;
• salve amount, os dados de lance necessários e currency, se usado;
• distinguir entre status de cupom e lance;
• aceitar campos desconhecidos e códigos de motivo sem erros;
• Torne todas as transações financeiras do usuário final idempotentes.

Rotas antigas continuam sendo suportadas, mas novas integrações devem usar /api/partner/**. Respostas e erros antigos têm formatos diferentes. Para atualizar um cliente existente, use um único arquivo “Migrando da API antiga”.

O saque está em desenvolvimento, não foi totalmente testado e não é recomendado para produção.

• Recebido BASE_URL, login e senha.
• JWT é transmitido como um token de portador.
• Os ponteiros são retirados da linha sem modificação.
• O carrinho é salvo como cupom aceito somente após code = 1.
• multi processado, restrições expressas e erros 501–507.
• Foi considerada a baixa automática do saldo do cliente.
• Todos os coupon_code e IDs de lance são salvos.
• O pagamento final é retirado de real_win.
• O retorno de chamada é verificado em relação aos bytes de origem e desduplicado usando batchId.
• A pesquisa de backup foi configurada.
• O saldo do usuário é separado do saldo do cliente SportAPI.

A documentação detalhada começa com Visão geral da API. O mapa completo do endpoint está no manual.