Cuotas, apuestas y cupones — documentación técnica de API

• API de URL base;
• inicio de sesión y contraseña de la cuenta del cliente;
• cuando utilice la devolución de llamada, habilite la función y la frase secreta callback_secret.

Los ejemplos utilizan una dirección condicional:

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

En producción, utilice HTTPS. Todas las fechas se transmiten como marca de tiempo Unix en milisegundos y los valores monetarios se transmiten como números decimales sin precisión fija.

Éxito:

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

El error comercial generalmente también viene con HTTP 200:

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

Verifique siempre el código HTTP, luego code, luego error_code. No utilice el texto error_message como clave de software.

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

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

El campo login se admite como alias compatible username.

Respuesta exitosa:

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

En todas las solicitudes protegidas, pase:

Authorization: Bearer <jwt-token>

Errores básicos de inicio de sesión:

Estos errores se devuelven desde HTTP 200, code = 0. HTTP 401 de un método protegido significa que el JWT falta, no es válido, ha caducado o está revocado; Inicia sesión nuevamente. HTTP 403 significa rol inadecuado o acceso denegado.

Cada resultado seleccionado se transmite como una línea ya preparada de la línea deportiva:

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

Ejemplos:

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

• line_type: line o live;
• rate: parámetro total/handicap o 0;
• player_id: ID de jugador opcional;
• Se admiten los delimitadores # y |.

No recopile ni corrija el puntero manualmente; pase el valor obtenido de la línea sin cambios.

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

Ordinario, expreso y multi

Un tren expreso no puede contener más de 15 eventos. No puedes combinar múltiples apuestas en el mismo partido, incluido el partido principal, mitades, períodos, córners, faltas y otros subeventos relacionados. Esta combinación devuelve 506.

Respuesta completa exitosa con cupón y datos de apuesta aceptada 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 cupón

Cada artículo body.coupons[] es un cupón independiente creado.

Campos de oferta

Cada elemento de events_data[] describe una apuesta aceptada específica dentro del cupón.

El valor null es normal para datos que aún no se han calculado o no están disponibles. No lo reemplace automáticamente con 0 o la cadena vacía.

Considere el cupón aceptado sólo si code = 1 y la presencia de objetos en body.coupons. Ante esto, la canasta es una elección preliminar: la selección podría desaparecer, ser bloqueada o cambiar las cuotas.

Después del éxito:

1. guarde todos los objetos body.coupons, no solo el primero;
2. almacene coupon_code como una cadena con ceros a la izquierda;
3. guarde los datos requeridos de events_data;
4. hacer coincidir el cupón con el usuario final;
5. registrar la transacción financiera del usuario en el sistema del socio.

Identificadores:

currency no se devuelve en el modelo completo ni en la devolución de llamada. Si se necesita la moneda, guarde el valor de la solicitud de creación.

Para 501–504, la nueva API devuelve las tasas problemáticas en body.changes[]. Campo change_type: 1: el coeficiente ha aumentado, 2: disminuido, null: la dirección no es aplicable.

No vuelva a intentar ciegamente POST /coupons/place después del tiempo de espera: es posible que la primera solicitud haya sido aceptada y volver a intentarlo creará un duplicado.

Puede transferir hasta 100 valores usando códigos:

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

O pasar el período de creación no más de 24 horas:

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

No combine coupon_ids y fechas en la misma consulta. results filtra por hora de creación y calculated filtra por hora de liquidación final.

Estados de los cupones:

Estados de las ofertas:

Para la acumulación financiera para el usuario final, utilice el real_win ya preparado. No utilice potential_win y no vuelva a calcular el pago usted mismo. Antes del cálculo, real_win, calculate_coef, calc_coef y calculate_date son iguales a null, no a 0.

En el primer estado del cupón 15, si el resultado anterior ya ha sido procesado financieramente, el socio debita nuevamente amount del usuario final, espera un nuevo estado final y cobra un nuevo real_win. Proteger las operaciones del reprocesamiento.

Cada apuesta en el modelo completo y callback tiene:

Antes del cálculo, ambos campos son iguales a null. Para una notificación localizada, use código como:

• MATCH_POSTPONED - el partido ha sido pospuesto;
• MATCH_CANCELLED - partido cancelado;
• MARKET_PUSH - devolución según las reglas del mercado.

Si desconoce el código, guárdelo y utilice el settlement_reason que no esté vacío como texto alternativo. No calcule el pago por motivo: utilice estados y real_win.

Estos campos explican el cálculo o la devolución que ya se ha realizado y no son una fuente separada en tiempo real del estado del partido.

La devolución de llamada es opcional. Un socio sólo puede trabajar mediante encuestas. Para la devolución de llamada, el administrador debe habilitar la función y crear callback_secret; La URL se envía en cada cupón creado.

El socio determina la URL de devolución de llamada de forma independiente. En producción se deberá utilizar https://; en un entorno de prueba, se permite http://.

El sistema envía:

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

Carga útil corta:

{
  "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
        }
      ]
    }
  ]
}

Reglas obligatorias:

1. calcule sha256=<hex(HMAC-SHA256(raw_body, callback_secret))> a partir de los bytes de origen exactos del cuerpo antes de analizar JSON y comparar firmas de forma segura;
2. procese todos los artículos coupons, el paquete puede contener hasta 100 cupones;
3. almacene batchId con un índice único;
4. repetido batchId no debe repetir la cancelación o acumulación;
5. un coupon_code puede venir con diferentes batchId durante el cálculo progresivo y el recálculo;
6. devuelva HTTP 200 solo después de que todo el paquete se haya almacenado de forma segura.

La respuesta mínima exitosa es un HTTP 200 vacío. Avanzado:

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

processed debe ser igual a couponCount. Las respuestas 201, 202 y 204 no se consideran exitosas.

Las repeticiones se realizan solo en caso de tiempo de espera, error de transporte o HTTP 500, 502, 503, 504: inmediatamente, luego después de 1, 5, 15 y 60 minutos, no más de cinco envíos. No hay reintento automático en HTTP 200 con success: false o processed parcial.

Incluso con devolución de llamada, verifique periódicamente los resultados:

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

Después de una pausa de más de 120 minutos, use POST /api/partner/coupons/results sobre coupon_ids guardado o períodos de creación de hasta 24 horas. Recibir nuevamente la misma fortuna no debería repetir transacciones financieras.

• almacene el inicio de sesión, la contraseña, JWT y callback_secret solo en el servidor;
• no pase JWT en la URL y no escriba el token completo en los registros;
• use tipo decimal para dinero;
• almacene coupon_code como una cadena;
• guarde amount, los datos de oferta requeridos y currency, si se utilizan;
• distinguir entre estados de cupón y oferta;
• aceptar campos desconocidos y códigos de motivo sin errores;
• Haga que todas las transacciones financieras del usuario final sean idempotentes.

Se siguen admitiendo rutas antiguas, pero las nuevas integraciones deben utilizar /api/partner/**. Las respuestas antiguas y los errores tienen formatos diferentes. Para actualizar un cliente existente, utilice un único archivo “Migración desde la API anterior”.

El retiro está en desarrollo, no está completamente probado y no se recomienda su producción.

• Recibido BASE_URL, nombre de usuario y contraseña.
• JWT se transmite como un token al portador.
• Los punteros se toman de la línea sin modificaciones.
• El carrito se guarda como cupón aceptado solo después de code = 1.
• Procesado multi, restricciones expresas y errores 501–507.
• Se ha tenido en cuenta la cancelación automática del saldo del cliente.
• Se guardan todos los coupon_code y los ID de oferta.
• El pago final se obtiene de real_win.
• La devolución de llamada se compara con los bytes de origen y se deduplica mediante batchId.
• Se ha configurado el sondeo de respaldo.
• El saldo del usuario es independiente del saldo del cliente SportAPI.

La documentación detallada comienza con descripción general de API. El mapa completo de terminales se encuentra en manual.