Formato de respuesta

Toda respuesta exitosa de la API viaja envuelta en el mismo formato:

{
  "data": { },
  "timestamp": "2026-07-29T16:43:36.22",
  "status": "OK"
}

Campo	Descripción
`data`	El resultado propio del endpoint. Abajo está la de `POST /analyze`.
`timestamp`	Momento en que se generó la respuesta
`status`	`OK` en lecturas y scoring; `CREATED` al crear una verificación

Los errores usan otro envelope. Ver Códigos de error.

`data` en `POST /analyze`

{
  "transaction_id": "01e6efd4-c884-5bc0-af43-68b3fac8d0f8",
  "order_id": "8788426783",
  "risk_score": 29.07,
  "risk_level": "medium",
  "flags": [
    {
      "code": "AUTH_3DS_FAILED",
      "category": "authentication",
      "severity": "high",
      "description": "3DS authentication explicitly failed"
    }
  ],
  "recommendation": "…",
  "decision": {
    "type": "BLOCK",
    "reason": ["AUTH_3DS_FAILED", "custom_rule:abc123"],
    "confidence": 0.89,
    "conditions": []
  },
  "transaction_state": "BLOCKED"
}

Campo	Descripción
`transaction_id`	Identificador que asigna FraudEG
`order_id`	Identificador de orden que enviaste
`risk_score`	Número de 0 a 100 — campo plano. Ver Score de riesgo
`risk_level`	`low` / `medium` / `high` / `critical` — campo plano
`flags`	Señales de riesgo con `code`, `category`, `severity`, `description`. Catálogo: Flags
`recommendation`	Frase en el idioma de la compañía. Ver abajo
`decision.type`	La decisión — Decisiones de transacción
`decision.reason`	Lista de strings — ver abajo
`decision.confidence`	0 a 1, de la decisión por score. Ver Score de riesgo
`decision.conditions`	Condiciones pendientes cuando `type` es `STEP_UP_AUTH` (hoy: `OTP_VERIFICATION`)
`transaction_state`	Ciclo de vida

risk_score y risk_level son de primer nivel de data. flags también. No hay un objeto risk anidado, y flags no vive dentro de decision.

`recommendation`

Es un string de prosa, en el idioma configurado para tu compañía. Resume la decisión y, cuando hay señales, puede citar códigos públicos de flags. No es un contrato programable:

No hagas switch sobre el texto.
No parsees los códigos desde la frase: ya están en flags y en decision.reason.
El texto puede cambiar de redacción sin aviso; decision.type no.

Úsalo para mostrar algo legible en una UI. Para decidir qué hacer con la transacción, lee siempre decision.type.

Sobre `flags`

Cada entrada es una señal que se activó, con cuatro campos. flags viene [] si no hay señales. Las entradas están deduplicadas por code. Nunca traen el nombre interno de la señal ni un peso numérico. El catálogo completo de code —un solo lugar, no se duplica en otras páginas— está en Catálogo de flags.

Sobre `decision.reason`

Lista de strings, no de objetos. Lectura corta para ramificar sin recorrer flags:

Forma	Qué significa
Un código público (p. ej. `"AUTH_3DS_FAILED"`)	Se activó esa señal. Mismo vocabulario que `flags[].code`
`custom_rule:<id>`	Una regla propia del comercio elevó la decisión
`entity_block:<kind>:<value>`	Una entrada de tu lista de entidades bloqueó la transacción. `<kind>` es el tipo (`user_id`, `device_id`, `ip_address`, `pan_token`, `email`, `expanded_bin`) y `<value>` el valor que coincidió

Si te llega un BLOCK con entity_block:user_id:user-4471, la causa está en tu lista.

Inicio

Transacciones: conceptos

Transacciones: integrar

Identidad

Referencia

Entornos

Formato de respuesta

`data` en `POST /analyze`

`recommendation`

Sobre `flags`

Sobre `decision.reason`

​data en POST /analyze

​recommendation

​Sobre flags

​Sobre decision.reason

`data` en `POST /analyze`

`recommendation`

Sobre `flags`

Sobre `decision.reason`