Evaluar eventos (POST /v1/score)
Llama a /v1/score en cada momento de riesgo del jugador, antes de completar la acción. Responde en tiempo real: el objetivo es p99 < 300 ms.
Tipos de evento
event_type |
Cuándo | Qué detecta sobre todo |
|---|---|---|
signup |
Registro | Multicuentas, menores de edad (CURP), correo desechable, IP de riesgo |
login |
Inicio de sesión | Toma de cuenta, dispositivo nuevo |
deposit |
Depósito | Tarjetas prepago, BIN extranjero, ráfagas de depósitos |
withdrawal |
Retiro | Toma de cuenta, CLABE compartida, sanciones/PEP, umbrales LFPIORPI |
bonus_claim |
Reclamo de bono | Abuso de bonos: varios jugadores en un dispositivo o IP |
bet |
Apuesta | Velocidad |
kyc / profile_update |
Verificación / cambio de datos | Identidad, sanciones |
custom |
Otro | Lo que definan tus reglas |
Campos
Todos son opcionales salvo event_type. Mientras más envíes, mejor la señal. Lo que no envíes simplemente no se evalúa.
| Campo | Formato | Ejemplo |
|---|---|---|
user_id |
Tu id del jugador (máx. 128). Sin datos personales. | "jugador_123" |
session_id |
Tu id de sesión | "s_9f2" |
email |
Correo | "ana@ejemplo.com.mx" |
phone |
E.164 o 10 dígitos MX | "+528112345678" |
ip |
IPv4 o IPv6 del jugador (no la de tu servidor) | "189.203.10.20" |
device_id |
El dv_… del SDK de dispositivo |
"dv_…" |
bin |
Primeros 6–8 dígitos de la tarjeta | "455678" |
clabe |
18 dígitos | "002010077777777771" |
person.full_name |
Nombre completo | "Ana Ejemplo Prueba" |
person.date_of_birth |
AAAA-MM-DD |
"1990-05-01" |
person.curp / person.rfc |
Mayúsculas | |
person.nationality |
ISO de 2 letras | "MX" |
transaction.amount |
Texto decimal | "1500.00" |
transaction.currency |
ISO 4217, por defecto MXN |
|
transaction.method |
card, spei, oxxo, codi, wallet, crypto, other |
|
screen |
true para revisar listas de sanciones/PEP (requiere person.full_name y el permiso screen) |
|
custom |
Objeto libre para tus reglas (custom.vip, …) |
{"vip": true} |
Nunca envíes el número completo de tarjeta: solo el BIN.
La respuesta
| Campo | Qué es |
|---|---|
id |
evt_…, el id del evento. Guárdalo. |
score |
0–100, más alto = más riesgo |
decision |
approve (< 40), review (40–74), decline (≥ 75). Los umbrales se pueden ajustar por cuenta. |
reasons |
Lista de {code, module, weight, description_es, description_en}. Ver el catálogo. |
signals |
Por módulo: status (ok, skipped, timeout, error), latency_ms y facts |
rules_triggered |
Las reglas de tu cuenta que se activaron |
screening |
status (not_requested, clear, potential_match, match, unavailable), hits, lists_version |
ruleset_version |
Versión de tus reglas que se aplicó |
Cómo se calcula el score
Cada razón tiene un peso de 0 a 100. Se combinan con un "o" probabilístico: score = 100 × (1 − Π(1 − peso/100)). Una razón de 90 da 90; dos de 50 dan 75. Agregar razones nunca baja el score.
Tus reglas pueden agregar razones, cambiar pesos o forzar una decisión (decline gana a review, que gana a approve).
Si un módulo falla
Un módulo lento o caído nunca hace fallar la llamada: aparece con status: "timeout" o "error" y sus razones no cuentan. Tus reglas pueden reaccionar a eso; por ejemplo, el paquete iGaming manda a revisión cuando pediste screening y no estuvo disponible.
Screening automático
Si tu cuenta tiene listas propias de nombres (p. ej. la LPB de la UIF), los eventos signup, kyc, profile_update y withdrawal que traen person.full_name se revisan contra listas aunque no envíes screen=true.
Atribuciones
Los datos de país y ASN de la IP (signals.ip.facts.country, asn, as_org) son IP Geolocation by DB-IP y los datos de BIN (signals.bin.facts) son BIN data by BinLookup.io. Ambos tienen licencia CC BY 4.0. Si muestras estos valores en tus pantallas, incluye la misma atribución.