POST /analyze

POST {API_BASE}/v1/transactions/analyze

{API_BASE} es https://sandbox-api.fraudeg.com/api o https://api.fraudeg.com/api, según tu entorno. En producción:

POST https://api.fraudeg.com/api/v1/transactions/analyze

Scorea una transacción en vivo y devuelve una decisión. Esta ruta sí trata la llamada como tráfico live. Para ver la respuesta del modelo maduro sin tratarla como live —en producción o en pre-official-integration— usa /analyze/sandbox. Ese path es un modo, no el host sandbox.

Headers

Header	Obligatorio	Descripción
`X-Api-Key`	Sí	Scope `TRANSACTIONS_WRITE`. Ver Autenticación
`X-Idempotency-Key`	Sí	16–128 caracteres url-safe. Ver Idempotencia
`Content-Type`	Sí	`application/json`

Request

Campos obligatorios:

Campo	Tipo	Alias de wire aceptado
`order_id`	string	—
`user_id`	string	—
`transaction_amount`	number	`total_value_usd`
`payment_method`	string	`paymentInstrumentType`

El nombre canónico es payment_method. paymentInstrumentType es el mismo campo con otro nombre en el JSON. Ver Métodos de pago y rieles. Todos los demás campos son opcionales. La lista completa está en Campos.

{
  "order_id": "8788426783",
  "user_id": "usr_48213",
  "transaction_amount": 129.90,
  "payment_method": "card",
  "cavv_result": "failed",
  "device_id": "dvc_a91f",
  "ip_address": "190.12.4.55"
}

Response

{
  "data": {
    "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"],
      "confidence": 0.89,
      "conditions": []
    },
    "transaction_state": "BLOCKED"
  },
  "timestamp": "2026-07-29T16:43:36.22",
  "status": "OK"
}

Campo por campo: Formato de respuesta. En particular:

decision.type es el único campo accionable — nunca actúes sobre risk_score.
El catálogo de flags[].code vive en Catálogo de flags, no aquí.
recommendation es una frase en el idioma de la compañía. No ramifiques sobre ella.

Errores

El envelope de error de la API pública es:

{
  "error_code": "DATA_CONFLICT",
  "message": "There is a conflict with the provided information.",
  "details": "A request with this X-Idempotency-Key is already in progress",
  "timestamp": "2026-07-29T16:43:36.22"
}

error_code es el catálogo de códigos de error. El texto que distingue un caso de otro está en details, no en message (message es la prosa genérica del código).

HTTP de este endpoint

HTTP	`error_code` típico	Cuándo
`400`	`BAD_REQUEST`	Header `X-Idempotency-Key` ausente o con formato inválido (16–128, alfabeto url-safe)
`403`	`INSUFFICIENT_PERMISSIONS`	La key no tiene `TRANSACTIONS_WRITE`, o se usa en una ruta que no acepta API keys
`409`	`DATA_CONFLICT`	Dos casos, distinguibles por `details`. Ver abajo
`422`	`VALIDATION_ERROR`	Payload inválido, o la misma `X-Idempotency-Key` se usó con un payload distinto
`429`	`TOO_MANY_REQUESTS`	Límite de tasa
`503`	`SERVICE_UNAVAILABLE`	Scoring no disponible; reintenta

Los dos `409`

Misma key HTTP, distinto details:

`details` (extracto)	Qué pasó	Qué hacer
`A request with this X-Idempotency-Key is already in progress`	Hay una petición en curso con esa clave	Reintenta más tarde con la misma clave
`The response stored for this X-Idempotency-Key was produced by an earlier version of the API and can no longer be replayed`	La transacción sí se scoreó, pero la respuesta guardada ya no se puede releer	Reintenta con una clave nueva. Ver Idempotencia

Un 400, 403 o 422 significa que la petición no llegó a scorear: no se persistió nada. Un 409 es distinto: la transacción puede estar scoreada y guardada ya.

Inicio

Transacciones: conceptos

Transacciones: integrar

Identidad

Referencia

Entornos

Headers

Request

Response

Errores

HTTP de este endpoint

Los dos `409`

​Headers

​Request

​Response

​Errores

​HTTP de este endpoint

​Los dos 409

Headers

Request

Response

Errores

HTTP de este endpoint

Los dos `409`