Reglas y listas

Reglas

Las reglas de tu cuenta se evalúan después de las señales. Pueden agregar una razón, cambiar el peso de una razón o forzar una decisión.

Reglas, listas y umbrales son de cada entorno: una llave test solo ve y cambia los de prueba, una live los de producción.

{
  "id": "r_bono_multi_dispositivo",
  "name": "Bono reclamado desde dispositivo con varias cuentas",
  "enabled": true,
  "when": {"all": [
    {"fact": "event_type", "op": "eq", "value": "bonus_claim"},
    {"fact": "velocity.device_id.distinct_user_id.24h", "op": "gte", "value": 3}
  ]},
  "then": {"action": "add_reason", "code": "DEVICE_MULTI_ACCOUNT", "weight": 80}
}

• Datos (fact): campos del evento (event_type, transaction.amount, custom.*), datos de las señales (email.disposable, ip.country, screening.status, …) y reasons.
• Operadores: eq neq in nin gt gte lt lte contains starts_with exists regex, eq_fact / neq_fact (comparar dos datos, p. ej. país de la IP contra país del teléfono) e in_list.
• Velocidad: velocity.<llave>.<métrica>.<ventana>, con llaves user_id, device_id, ip, email, phone, clabe, bin, curp; métricas count, distinct_<campo>, sum_amount; ventanas 1h, 24h, 7d, 30d. Los conteos incluyen el evento actual.
• Acciones: add_reason, set_weight, force_review, force_decline, force_approve.
• Modo sombra: "mode": "shadow" registra lo que la regla habría hecho sin cambiar el resultado.

Un dato que no existe hace que la condición sea falsa (salvo exists: false), así que una regla nunca falla por un campo ausente.

API

• GET /v1/rules (rules:read) lista tus reglas.
• PUT /v1/rules (rules:write) inserta o reemplaza por id. Todo se valida antes de guardar: si algo está mal, regresa 422 y no se guarda nada.
• DELETE /v1/rules/{id}.

Paquete iGaming

Te entregamos un paquete de reglas para iGaming listo para usar, con parámetros que ajustas a tu operación: países permitidos (allowed_countries), cuentas por dispositivo (device_max_accounts_30d), depósitos por hora (deposit_burst_per_hour), monto de retiro en 24 h (withdrawal_24h_mxn), umbral de aviso LFPIORPI (aml_aviso_threshold_mxn) y otros.

Listas

Dos tipos:

• values: identificadores para bloquear o permitir (correos, dominios, teléfonos, IPs o rangos CIDR, device_id, user_id, BIN, CLABE, CURP, RFC). Se usan en reglas con {"fact": "email", "op": "in_list", "value": "correos_bloqueados"}.
• names: nombres para screening, como la LPB de la UIF o tu propia lista de PEP. Se revisan junto con las listas oficiales.

curl -s "$SAFEGATE_URL/v1/lists" -H "Authorization: Bearer $SAFEGATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "correos_bloqueados", "name": "Correos bloqueados", "type": "values", "field": "email"}'

curl -s "$SAFEGATE_URL/v1/lists/correos_bloqueados/entries" -H "Authorization: Bearer $SAFEGATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values": [{"value": "fraude@ejemplo.com", "note": "contracargo 2026-10"}]}'

Los valores se guardan solo como hash con llave más una versión enmascarada para mostrar (f***@ejemplo.com); nunca en texto claro. Hasta 1,000 entradas por llamada. Necesitas lists:read / lists:write.