Integración del sistema de cálculo de apuestas y cupones

¿Cómo funciona el sistema de cálculo de cuotas y resultados?

La integración con nuestro sistema de cálculo de apuestas y cupones consta de tres etapas clave:

Paso 1: Autorización

En la primera etapa debes autorizarte en el sistema. Esto se hace realizando una petición POST con las credenciales del usuario (login y contraseña). Una autorización correcta devuelve una sesión representada como una cookie, que debe guardarse. Estas cookies son necesarias para todas las peticiones posteriores, ya que se usan para identificar la sesión del usuario en el sistema.

Paso 2: Envío de una apuesta

En esta etapa se envía a nuestro sistema un código de apuesta que contiene:

• ID del partido, correspondiente al evento.
• Código de apuesta, que describe el resultado seleccionado (por ejemplo, victoria del equipo, hándicap o total).
• Cuota de la apuesta, válida en el momento del envío.

Al enviar los datos, deben incluirse las cookies obtenidas durante la autorización. Esto garantiza la correcta identificación del usuario y el procesamiento de la apuesta.

Paso 3: Recepción de resultados

Tras calcular los resultados o los cupones, nuestro sistema envía peticiones POST al remote_host indicado. Esta petición incluye:

• Estado del cupón (ganada, perdida o devolución).
• Estados de todos los resultados incluidos en el cupón.

Los resultados se envían en cuanto se determina el resultado. Por ejemplo:

• Si la apuesta se hizo sobre un resultado intermedio (por ejemplo, hándicap 2.5, y se marca el tercer gol), el cálculo puede realizarse durante el partido.
• Si la apuesta es sobre el resultado final (por ejemplo, victoria del equipo), la información de estado se enviará inmediatamente después de que finalice el partido.

Ahora revisa cada paso por separado. Hemos descrito en detalle las peticiones, los parámetros y las respuestas de la API REST.

El login, la contraseña y el host para enviar peticiones se pueden obtener del manager.

URL de la petición:

{APIHOST}/WebServices/BCService.asmx/LogIn/

Tipo de envío de datos: POST

Datos enviados:

Parámetro	Descripción
login	Login del usuario
password	Contraseña del usuario

¡Importante!

• Durante la autorización, la respuesta incluye cookies. Estas cookies deben guardarse y enviarse con las peticiones posteriores.

Recomendaciones para una integración más sencilla:

• Asegúrate de que el campo login se pase como cadena.
• Verifica el correcto guardado y envío de las cookies, ya que esto afecta a la ejecución de las peticiones posteriores.
• En caso de error, la petición devolverá un objeto vacío. Asegúrate de gestionar este escenario adecuadamente.

Las cookies son válidas durante 3 meses. Sin embargo, pueden restablecerse si se reinicia el servidor. Por lo tanto, debes volver a autorizarte si encuentras un error al guardar un cupón.

"errorCode":1,
"fullErrorCode":99,
"errorMessage":"Invalid access level"

Ejemplo de respuesta:

Correcta:

{"d":{"UserId":"36557"}}

Incorrecta:

{"d":{}}

Descripción de los campos de respuesta:

Campo	Descripción
UserId	Identificador único del usuario
d	Objeto raíz de la respuesta

Recomendaciones generales:

• Antes de la primera petición, asegúrate de que el usuario haya introducido las credenciales correctas.
• Configura la gestión de errores para mostrar al usuario los motivos del fallo de autorización (por ejemplo, login o contraseña incorrectos).
• Registra los intentos correctos e incorrectos para su análisis y monitorización.

Las cookies deben guardarse y enviarse con las peticiones posteriores.

import requests
import json

url = "https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/"

payload = json.dumps({
  "login": "demo-login@demosportapi.net",
  "password": "demo-password"
})
headers = {
  'Content-Type': 'application/json'
}

print(response.text)

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
    "login":"demo-login@demosportapi.net",
    "password":"demo-password"
}',
    CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
    ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify({
    "login": "demo-login@demosportapi.net",
    "password": "demo-password"
});

const requestOptions = {
    method: "POST",
    headers: myHeaders,
    body: raw,
    redirect: "follow"
};

fetch("https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/", requestOptions)
    .then((response) => response.text())
    .then((result) => console.log(result))
    .catch((error) => console.error(error));

OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"login\":\"demo-login@demosportapi.net\",\r\n    \"password\":\"demo-password\"\r\n}");
Request request = new Request.Builder()
.url("https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();

Para enviar una apuesta debes usar las cookies obtenidas durante la etapa de autorización. Estos datos son necesarios para identificar tu sesión y procesar las peticiones.

URL de la petición:

{HOST_API}/bet/place/

{
    "data":{
        "list_bets":[
            "line#586464528|17|954|2.5#4.27",  "live#586464528|87|4|0#1.12"
        ],
        "realAmount":"2",
        "currency":"USD",
        "lang":"en",
        "remote_host":"https://mysites.com",
        "rate_mode":"reject"
    }
}

Descripción de los campos

Parámetro	Descripción
list_bets	Código de apuesta y cuotas. Formato: "tipo_evento#ID_partido|código_apuesta#cuota". Ejemplo: "live#579216393|1|1|0#2.1"
realAmount	Importe de la apuesta. Debe pasarse como cadena, p. ej., "150".
currency	Moneda del cupón.
lang	El idioma en el que se guardan la apuesta y el cupón. Por ejemplo: "en", "ru" o "tr".
remote_host	La URL a la que enviar los resultados de cálculo del cupón. No incluyas una barra final.
rate_mode	Opción para gestionar la aceptación del cupón cuando cambian las cuotas: "reject" (rechazar ante cambios) o "accept" (aceptar independientemente de los cambios). Por defecto: "accept".

Nota: Asegúrate de que los parámetros se pasen en el formato correcto. Por ejemplo, list_bets debe ser un array, aunque solo haya una apuesta.

No validamos el importe de la apuesta. Puedes enviar el importe real de la apuesta o cualquier valor arbitrario. Esto se hace para garantizar la confidencialidad de tus datos financieros. Nuestra tarea es proporcionar los resultados de cálculo. Tú eres responsable de acreditar las ganancias a tus jugadores.

Parámetros obligatorios para enviar una apuesta:

• list_bets — contiene información sobre la apuesta y el partido correspondiente.
• remote_host — la URL a la que enviaremos los resultados de cálculo del cupón o del resultado.
• rate_mode — determina cómo gestiona el sistema los cambios de cuotas.

El resto de parámetros también deben enviarse, pero son opcionales y pueden usarse para tu comodidad.

Descripción del parámetro remote_host

remote_host es la dirección de tu servidor a la que enviamos peticiones con los resultados de cálculo de apuestas. Este host debe estar configurado para aceptar peticiones de nuestro servidor. A continuación se muestran ejemplos de posibles valores y detalles específicos sobre el trabajo con este parámetro.

Puedes especificar varias opciones para remote_host:

• Host simple: https://mysites.com
• Host con puerto: https://mysites.com:78665
• Host con rutas adicionales: https://mysites.com/request/sportapi/sender
• Host con parámetros: https://mysites.com/request.php?action=webhook

Importante: Al enviar una petición, nuestro sistema añade automáticamente la cadena /api/bet/result al remote_host indicado. Así, la dirección final para recibir peticiones se forma como remote_host + "/api/bet/result". Asegúrate de que tu servidor esté configurado para recibir datos en esta ruta.

Ejemplos:

• Especificas remote_host = https://mysites.com. Enviamos peticiones a: https://mysites.com/api/bet/result.
• Especificas remote_host = https://mysites.com/request.php?action=webhook. Enviamos peticiones a: https://mysites.com/request.php?action=webhook/api/bet/result.

Detalles técnicos:

• Las peticiones se envían mediante el método POST.
• Tu servidor debe estar listo para aceptar los datos JSON que enviamos.
• Tu servidor debe devolver un código de estado 200 al recibir correctamente los datos.

Asegúrate de que tu servidor procese correctamente la ruta y las peticiones indicadas. La siguiente sección muestra un ejemplo de la estructura de datos enviada por nuestro servidor.

Descripción del parámetro rate_mode

El parámetro rate_mode define el comportamiento del sistema cuando cambian las cuotas. Puede tomar dos valores:

• accept: En este modo, el cupón se aceptará con las cuotas actuales, incluso si han cambiado. Por ejemplo, un jugador añade una apuesta "Gana el Manchester" con una cuota de 2.02. Mientras pulsa el botón "Hacer apuesta", la cuota cambia a 1.37 o 2.78. En el modo accept, el sistema guarda el cupón con las nuevas cuotas sin notificar a tu sistema.
• reject: En este modo, el sistema rechaza el cupón si las cuotas han cambiado. La respuesta incluirá un error notificando que las cuotas han cambiado.

Elige el modo que mejor se adapte a tus procesos de negocio y ofrezca comodidad a tus usuarios.

Recomendaciones importantes

1. Formato JSON: Asegúrate de que los datos se serialicen correctamente en formato JSON antes de enviarlos.
2. Cookies: Incluye las cookies obtenidas durante la autorización para identificar correctamente la sesión del usuario.
3. Gestión de errores: Gestiona las respuestas del servidor, especialmente los casos en que se devuelve errorCode = 1.
4. Pruebas: Realiza pruebas en todas las etapas de la integración, incluido el envío de apuestas individuales y múltiples.

Campos de respuesta

Parámetro	Descripción
betCode	Número único de la apuesta en nuestro sistema
errorCode	Estado principal del resultado de la petición
fullErrorCode	Detalle del error
errorMessage	Mensajes de texto de errores del sistema
AmountOut	Importe potencial de ganancia
CountEvents	Número de apuestas en el cupón
Coef	Cuotas de los resultados
IsLive	Tipo de apuesta: en vivo o pre-partido (true/false)
LinesId	ID del partido
EventDate	Fecha del partido

Descripción de errores en el envío de apuestas

Al enviar una apuesta pueden producirse diversos errores. La respuesta del servidor contiene tres campos clave:

• errorCode: Estado principal de la petición.
• fullErrorCode: Detalle del error.
• errorMessage: Descripción de texto del error.

Si la apuesta se acepta correctamente, el servidor devuelve una respuesta correcta (ver arriba). El cupón se ha aceptado y no hay errores.

Si se produce un error, el servidor devuelve una respuesta de error general (ver arriba). Se ha producido uno de los posibles errores. A continuación se muestran los códigos y mensajes de error.

Posibles códigos y descripciones de error

Código de error (fullErrorCode)	Mensaje de error (errorMessage)	Descripción
1	error_wrong_bet_data	Datos de apuesta incorrectos. Comprueba el parámetro list_bets y otros campos obligatorios.
1	error_block_bet_data	La apuesta está bloqueada temporalmente y no se puede aceptar.
1	error_repeat_bet_data	No se permiten apuestas duplicadas sobre el mismo resultado de un mismo partido.
2	label_change_rate	Las cuotas han cambiado. El cupón se rechazó debido a una discrepancia entre las cuotas indicadas y las actuales.
3	error_exist_bet	El resultado de apuesta indicado ya no existe. Comprueba la exactitud de los datos.
99	Invalid access level	El usuario no tiene permisos para realizar esta operación. Lo más probable es que sea necesario volver a autorizarse, falten las cookies o la cuenta esté bloqueada.
99	Error exist remote host!	El parámetro remote_host es incorrecto o falta. Comprueba la configuración de tu servidor.

Recomendaciones para la gestión de errores

• Validación de datos de entrada: Asegúrate de que todos los parámetros obligatorios se proporcionen correctamente. Comprueba el formato de list_bets y la presencia de todos los campos obligatorios.
• Trabajo con cuotas: Si se usa rate_mode = reject, gestiona los errores relacionados con cambios de cuotas (label_change_rate).
• Configuración del servidor: Asegúrate de que tu servidor esté correctamente indicado en el parámetro remote_host.
• Registro de errores: Registra todos los errores (errorCode, fullErrorCode, errorMessage) para simplificar la depuración y la interacción con el soporte.
• Acciones ante errores críticos: En caso de errores de nivel 99, comprueba los permisos de acceso y la configuración de la API en tu lado.

{
  "errorCode": 1,
  "fullErrorCode": [ERROR_CODE],
  "errorMessage": "[ERROR_DESCRIPTION]"
}

Cuando se añade una apuesta a nuestro sistema y se calcula, enviamos los resultados del cupón a tu servidor. Estos pueden incluir:

• Resultados del cupón (cálculo completo).
• Estados del cupón (ganada, perdida, devolución).

Las peticiones se envían a la dirección que indicaste en el parámetro remote_host. A esta dirección se le añade automáticamente la cadena /api/bet/result. Asegúrate de que tu servidor esté configurado para recibir datos en esta ruta.

Ejemplo de la dirección final:

Si indicaste: remote_host = https://mysite.com, enviaremos los datos a: https://mysite.com/api/bet/result.

{
    "remote_host": "https://mysite.com",
    "Heads": [{
        "KeyHead": {
            "Id": "344143",
            "BarCode": "x9c52i8411"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 11130,
        "DateReceive": "1597075782"
    }]
}

Descripción de los campos

Campo	Descripción
remote_host	La dirección de tu servidor a la que se envían los datos.
Id	Identificador único de la apuesta en nuestro sistema. Se ignora en la mayoría de los casos.
BarCode	Número único del cupón.
Status	Estado actual del cupón. Valores posibles: 2 — ganada, 4 — perdida.
ExtStatus	Estado adicional en caso de devolución: 0 — sin cambios, 1 — uno o más resultados se calcularon con una cuota modificada.
AmountOut	Importe de ganancia (si el cupón ganó).
DateReceive	La hora y fecha en que se calculó el cupón.

Cómo interpretar Status y ExtStatus

• Status = 2 y ExtStatus = 0: El cupón ganó.
• Status = 4 y ExtStatus = 0: El cupón perdió.
• Status = 2 y ExtStatus = 1: Devolución. El cupón se calculó con una cuota de 1.

Puntos importantes para la integración

• Gestión de ExtStatus = 1: Esto puede ocurrir si un partido se canceló o terminó antes de tiempo. En tales casos, todas las apuestas se calculan con una cuota de 1.
• Requisitos técnicos: Las peticiones se envían mediante el método POST. Tu servidor debe estar listo para aceptar datos JSON en la ruta remote_host + /api/bet/result.

{
    "remote_host": "https://mysite.com",
    "Heads": [{
        "KeyHead": {
            "Id": "313",
            "BarCode": "75vz48t935"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 19.85,
        "DateReceive": "1592937968"
    }, {
        "KeyHead": {
            "Id": "312",
            "BarCode": "77i0r6e15t"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 12.51,
        "DateReceive": "1592937280"
    }]
}