Autenticación Zero-Knowledge

El widget opera bajo un modelo de 'Zero-Knowledge', lo que significa que no almacena información personal (PII) de tus usuarios. Para que esto funcione, tu backend debe exponer dos endpoints que el widget consumirá para validar sesiones y procesar apuestas.

1. Endpoint de Perfil (profileUrl)

GETHeaders: Authorization: Bearer <token_del_usuario>

Este endpoint es llamado por el widget para obtener el saldo y nombre del usuario autenticado.

{
  "has_error": false,
  "code": 200,
  "message": "Success",
  "data": {
    "externalId": "user123",
    "name": "Jose Test",
    "balance": 1000.50,
    "currency": "DOP"
  }
}

2. Endpoint de Transacción (transactionUrl)

POSTHeaders: Authorization: Bearer <token_del_usuario>

Este endpoint es llamado cuando el usuario intenta realizar una apuesta. Tu backend debe validar el saldo y registrar la transacción.

{
  "action": "bet",
  "externalId": "user123",
  "amount": 50,
  "ticketId": "60d5ecb8b343d13098547289",
  "betDetails": {
    "numbers": ["15", "28", "99"],
    "currency": "DOP"
  }
}

3. Endpoint de Payout (serverPayoutUrl) - Recomendado

POSTHeaders: x-api-key: <tu_api_key>

Este endpoint es llamado de servidor a servidor de forma asíncrona por el motor cuando el ticket del usuario resulta ganador. No requiere token de usuario ya que ocurre en background, por lo que es la forma más robusta de pagar premios.

{
  "action": "payout",
  "externalId": "user123",
  "amount": 50000,
  "externalTransactionId": "txn_9876543210",
  "ticketId": "60d5ecb8b343d13098547289",
  "drawNumber": 1750878000000,
  "results": {
    "first": "15",
    "second": "28",
    "third": "99"
  }
}

Propiedades del Payload

action
Define el tipo de operación que el backend debe realizar. Puede ser uno de los siguientes valores:
- "bet": El usuario está realizando una jugada. El backend debe descontar el amount del balance del usuario.
- "payout": El ticket del usuario resultó ganador. El backend debe sumar el premio al balance del usuario.
- "rollback": Ocurrió un error local después de registrar la apuesta. El backend debe devolver/reembolsar el dinero al usuario para evitar inconsistencias.
externalId
El identificador único del usuario en tu sistema, recuperado desde el endpoint de perfil.
amount
El monto total de la transacción (ya sea para descontar en apuestas o sumar en premios).
ticketId
Identificador único de la transacción (o ticket) generado por Balotera. Úsalo para garantizar la idempotencia (evitar cobrar o pagar la misma jugada dos veces si ocurren reintentos).
betDetails
(Opcional) Contiene información específica de la apuesta, como los números jugados y la moneda. Útil para tus registros y reportes.
Nota sobre drawNumber: Durante la acción de 'bet', el número de sorteo (drawNumber) no se envía porque es un sorteo asíncrono y aún no se ha generado. Sin embargo, sí te lo enviaremos en el payload cuando la acción sea 'payout', para que tengas la referencia de a cuál sorteo perteneció el ticket ganador.