Señales de contexto

Antes de empezar

Las señales de contexto evalúan transacciones de crédito completadas y devuelven una evaluación de riesgo (autofraude o ingeniería social) para enriquecer tu propia decisión antifraude.

Son complementarias a Verificación de Tarjeta No Presente: no cambian el contrato ni el comportamiento de los endpoints de transacciones que ya utilizas. Sigues recibiendo el estado terminal de la transacción (approved, inconclusive, etc.) como de costumbre, y luego consultas las señales de contexto.

Tus solicitudes a la API se autentican mediante un token de acceso. Cualquier solicitud que no incluya un token de acceso válido devolverá un error. Obtén más información en Autenticación.

Acceso controlado por permisos

El acceso a este endpoint está controlado por un permiso (rol) asignado a tu empresa. Sin él, el endpoint devuelve 403. Solicita la habilitación al equipo de Unico.

URL base

• UAT: https://transactions.transactional.uat.unico.app/api/public/v1
• Producción: https://transactions.transactional.unico.app/api/public/v1

Obtener señales de contexto

GET /transactions/{transaction_id}/signals — devuelve la evaluación de riesgo de una transacción completada.

El resultado se precalcula de forma asíncrona en cuanto la transacción alcanza su estado terminal, por lo que este endpoint solo consulta un resultado que ya está disponible.

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
transaction_id	string	sí	ID de la transacción (UUID v4). Por ejemplo, 6ab1771e-dfab-4e47-8316-2452268e5481.

Encabezados

Encabezado	Valor
Authorization	Bearer {token} — un token de acceso válido.
Accept	application/json

Ejemplo de solicitud

GET /api/public/v1/transactions/6ab1771e-dfab-4e47-8316-2452268e5481/signals HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: Bearer {token}
Accept: application/json

200 OK

{
  "signals": {
    "auto_fraud_risk": "high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Campo	Tipo	Presencia	Descripción
signals.auto_fraud_risk	string (enum)	opcional	Nivel de riesgo de autofraude. Presente solo cuando se detecta.
signals.social_eng_risk	string (enum)	opcional	Nivel de riesgo de ingeniería social. Presente solo cuando se detecta.
signals.more_info.limited_data	boolean	siempre	true cuando no hay suficientes datos para una evaluación robusta.
signals.more_info.holder_identified	boolean	siempre	false cuando no se pudo identificar al titular de la tarjeta.

Valores de riesgo posibles: very_low, low, medium, high, very_high.

información

auto_fraud_risk y social_eng_risk son mutuamente excluyentes: nunca aparecen juntos en la misma respuesta. Cuando limited_data es true, se espera que ambos campos de riesgo estén ausentes, ya que no hay suficientes datos para una evaluación.

Ejemplos de respuesta

Riesgo de ingeniería social detectado:

{
  "signals": {
    "social_eng_risk": "very_high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Ningún riesgo identificado — una transacción regular:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Datos insuficientes:

{
  "signals": {
    "more_info": {
      "limited_data": true,
      "holder_identified": true
    }
  }
}

Titular de la tarjeta no identificado:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": false
    }
  }
}

Otros códigos de respuesta

Los errores se devuelven en el formato de error estándar descrito en Errores.

Código HTTP	Código	Situación	Qué hacer
202	—	El resultado aún no se ha calculado — el procesamiento asíncrono todavía está en curso.	Repite la llamada (polling) hasta obtener un 200.
400	40004	transaction_id no es válido (no es un UUID v4) o un parámetro está mal formado.	Corrige el formato del ID antes de enviar la solicitud nuevamente.
403	40305	La empresa no tiene el permiso (rol) habilitado para este endpoint.	Solicita la habilitación al equipo de Unico.
404	40401	No se encontró la transacción.	Verifica el ID de la transacción.
404	40484	No se encontró la transacción para evaluación.	Trátalo como "no habrá resultado" y deja de consultar.
409	40983	La transacción aún no ha alcanzado su estado terminal.	Espera el estado terminal antes de volver a consultar.
500	—	Error interno del servicio.	Reintenta con backoff. Si persiste, contacta al soporte de Unico.

Reglas y buenas prácticas

• Consulta el endpoint solo después de que la transacción alcance su estado terminal. Consultar antes devuelve 409.
• Solo se evalúan las transacciones de crédito. Las transacciones capturadas en modo silencioso no lo son.
• Ante un 202, repite la llamada hasta obtener un 200. Envía la primera solicitud 1 segundo después de la respuesta de la transacción y luego aplica backoff: 2s, 4s, 8s, 16s, hasta 5 intentos.
• El objetivo de nivel de servicio es de 10 segundos después de la respuesta de la transacción.
• Trata un 404 como "no habrá resultado" y deja de consultar.
• auto_fraud_risk y social_eng_risk son mutuamente excluyentes.