API de informes

La API de informes es la forma en que tu backend lee el resultado de cada operación evaluada por el motor antifraude. El SDK envía la transacción; la API devuelve el informe. La referencia completa se genera a partir de la especificación OpenAPI, con ejemplos de petición en varios lenguajes.

La API ofrece una verificación de identidad fluida que reduce el tiempo necesario para verificar y dar de alta a usuarios de confianza, y detecta el fraude en aplicaciones. Comprueba el comportamiento de ubicación del dispositivo para ofrecer una evaluación de riesgo con las evidencias que la respaldan. Cuando un dispositivo es nuevo en la red de Ironchip, Ironchip determina la ubicación del nuevo usuario; a partir de ahí, cada operación recoge datos de ubicación y actualiza la evaluación de riesgo. Para evaluar un alta nueva, Ironchip necesita recibir un token que identifique el dispositivo de origen.

Autenticación

Todas las peticiones llevan la API key en la cabecera Authorization, sin prefijo:

GET /reports/example-transaction-id HTTP/1.1
Host: report.lbfraud.ironchip.com
Accept: application/json
Authorization: example-api-key

Para generarla, ve a la página Credentials de la consola y haz clic en Generate api-key. La API key da acceso a todas las peticiones de la API. El código QR que aparece junto a ella sirve para vincular la aplicación móvil con la consola.

Sección Api key de la consola con el botón Generate api-key, la clave oculta y el código QR difuminado

Consultar el informe de una transacción

El flujo habitual es pedir el informe inmediatamente después de que la app envíe la transacción. El parámetro timeout hace que la API espere a que el informe esté listo. El lenguaje que elijas aquí se recuerda en el resto de la documentación.

GET /reports/{transaction_id} acepta estos parámetros:

Parámetro	Origen	Tipo	Por defecto	Descripción
`transaction_id`	ruta	string		Obligatorio. ID de la transacción.
`limit`	query	integer	`20`	Número máximo de informes (máximo `100`).
`page`	query	integer	`1`	Página de informes.
`since`	query	string	`30d`	Antigüedad máxima del informe, desde su generación (número y sufijo de unidad: `30d`, `12h`, `15m`).
`timeout`	query	string	`5s`	Tiempo máximo de espera a que el informe esté procesado (por ejemplo, `5s` o `1m`). Úsalo si lo pides antes de que termine la transacción.

curl 'https://report.lbfraud.ironchip.com/reports/example-transaction-id?since=30d&timeout=5s' \
  -H 'Accept: application/json' \
  -H "Authorization: $IRONCHIP_API_KEY"

const url = new URL('https://report.lbfraud.ironchip.com/reports/example-transaction-id');
url.search = new URLSearchParams({ since: '30d', timeout: '5s' }).toString();

const res = await fetch(url, {
  headers: { Accept: 'application/json', Authorization: process.env.IRONCHIP_API_KEY },
});
if (!res.ok) throw new Error(`Ironchip ${res.status}: ${await res.text()}`);

const [report] = await res.json();
console.log(report.event.risk_assignment, report.event.fraud_cases);

import os
import requests

response = requests.get(
    "https://report.lbfraud.ironchip.com/reports/example-transaction-id",
    params={"since": "30d", "timeout": "5s"},
    headers={"Accept": "application/json", "Authorization": os.environ["IRONCHIP_API_KEY"]},
    timeout=10,
)
response.raise_for_status()

report = response.json()[0]
print(report["event"]["risk_assignment"], report["event"]["fraud_cases"])

req, _ := http.NewRequest(http.MethodGet,
  "https://report.lbfraud.ironchip.com/reports/example-transaction-id?since=30d&timeout=5s", nil)
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", os.Getenv("IRONCHIP_API_KEY"))

res, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer res.Body.Close()

var reports []struct {
  Event struct {
    RiskAssignment string   `json:"risk_assignment"`
    FraudCases     []string `json:"fraud_cases"`
  } `json:"event"`
}
if err := json.NewDecoder(res.Body).Decode(&reports); err != nil {
  log.Fatal(err)
}
fmt.Println(reports[0].Event.RiskAssignment, reports[0].Event.FraudCases)

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://report.lbfraud.ironchip.com/reports/example-transaction-id?since=30d&timeout=5s"))
    .header("Accept", "application/json")
    .header("Authorization", System.getenv("IRONCHIP_API_KEY"))
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 200) {
    throw new IllegalStateException("Ironchip " + response.statusCode() + ": " + response.body());
}
// response.body() es un array JSON de informes; léelo con Jackson, Gson o la librería que uses.
System.out.println(response.body());

La respuesta es una lista de informes (normalmente uno). Los campos que deciden son event.risk_assignment y event.fraud_cases:

[
  {
    "id": 184233,
    "application_id": "banca-movil",
    "transaction_id": "example-transaction-id",
    "timestamp": 1759920000000000000,
    "event": {
      "risk_assignment": "high_risk",
      "fraud_cases": ["SIM Swapping / ATO"],
      "timestamp": 1759920000
    },
    "user": { "id": "usuario-123" },
    "device": {
      "id": "6f1c…",
      "model": "Pixel 8",
      "integrity": { "rooted": false, "emulated": false, "debugged": false, "gps_spoofed": false },
      "sensors": { "gps": true, "wifi": true, "wifi_connected": false, "mobile_networks": true }
    },
    "ip": { "vpn": true, "tor": false, "address": { "country_code": "ES", "city": "Madrid" } },
    "location": { "location_type": "lte", "address": { "country_code": "ES", "city": "Bilbao" } },
    "descriptive_report": "New device for the user, operating through a VPN, 400 km away from the usual zone."
  }
]

Campos del informe

Cada informe de una respuesta 200 incluye estos campos. La referencia completa detalla los objetos anidados.

Campo	Tipo	Descripción
`id`	integer	Identificador único del informe; sirve para comprobar si la evaluación cambió en llamadas posteriores.
`transaction_id`	string	Identificador único de la transacción del usuario.
`application_id`	string	ID de la aplicación.
`timestamp`	integer	Momento en que se generó el informe, en nanosegundos.
`event`	object	Resultado de la evaluación: el riesgo asignado y los casos de fraude.
`user`	object	Información del usuario que realizó la transacción.
`device`	object	Información del dispositivo usado en la transacción.
`ip`	object	Información de la IP usada en la transacción.
`location`	object	Información de la ubicación de la transacción.
`geo_location`	object	Ubicación obtenida por GPS.
`em_location`	object	Ubicación obtenida a partir de las redes Wi-Fi y móviles del entorno.
`extra_data`	object	Datos adicionales enviados con la transacción (JSON).
`descriptive_report`	string	Resumen comprensible para cualquier cliente.

Interpretar el nivel de riesgo

`risk_assignment`	Significado	Recomendación
`fraud`	Ironchip considera la operación fraudulenta.	Bloquear y revisar.
`high_risk`	La operación es potencialmente fraudulenta.	Pedir una verificación adicional.
`low_risk`	La operación es segura y se puede aceptar.	Continuar.
`unknown_risk`	Ironchip no puede dar una evaluación precisa en el momento de la petición.	Aplicar la política por defecto.

Los valores de fraud_cases y de las evidencias por sensor se describen en Evidencias y decisiones.

Enviar feedback

Cuando un analista confirma o corrige el resultado de una operación, tu backend lo comunica con POST /feedback/{transaction_id}. Ironchip usa este feedback para mejorar las detecciones de fraude futuras:

curl -X POST 'https://report.lbfraud.ironchip.com/feedback/example-transaction-id' \
  -H 'Accept: application/json' \
  -H "Authorization: $IRONCHIP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "behaviour": {
      "desired": {
        "fraud_cases": ["device swapping", "location swapping"],
        "risk_assignment": "clear"
      }
    },
    "impact": {
      "description": "La transacción se ha detectado como fraude en lugar de riesgo bajo"
    },
    "reporter": {
      "email": "analista@banco.example",
      "name": "Nombre",
      "surname": "Apellido"
    },
    "situation": {
      "description": "El cliente ha descargado la app en un dispositivo desconocido ubicado en un país nuevo"
    },
    "valuation": {
      "annotations": "No es posible distinguir a un cliente real de uno falso sin la confirmación del cliente",
      "score": 8,
      "type": "Corrective"
    }
  }'

La API responde 200 sin cuerpo cuando registra el feedback, y 400 si el cuerpo no es un JSON válido. Estos son los campos:

Campo	Tipo	Descripción
`behaviour.desired.risk_assignment`	string	Resultado que esperabas: `fraud`, `high`, `low` o `clear`.
`behaviour.desired.fraud_cases`	array	Casos de fraude que deberían (o no) haberse detectado.
`impact.description`	string	Impacto que tuvo el resultado (máximo 100 caracteres).
`situation.description`	string	Contexto de la operación cuando se evaluó (máximo 100 caracteres).
`reporter.name`, `surname`, `email`	string	Quién envía el feedback (máximo 50 caracteres cada uno).
`valuation.type`	string	`Positive`, `Negative` o `Corrective`.
`valuation.score`	integer	Puntuación de 0 a 10.
`valuation.annotations`	string	Anotaciones libres (máximo 100 caracteres).

Listar informes

GET /reports devuelve todos los informes de la aplicación, paginados de 20 en 20 por defecto (parámetros limit, con un máximo de 100, y page). Solo puedes consultar los informes de la aplicación a la que pertenece la clave. Es útil para conciliaciones y para alimentar el SIEM, pero para decidir en tiempo real usa siempre la consulta por transacción.

curl 'https://report.lbfraud.ironchip.com/reports?limit=20&page=1' \
  -H 'Accept: application/json' \
  -H "Authorization: $IRONCHIP_API_KEY"

Errores

Todas las respuestas de error comparten el formato descrito en Respuestas de error. Incluye el traceability_id al abrir un ticket.

Bibliotecas

Hay bibliotecas oficiales que facilitan la integración con la API de Ironchip. Envuelven la API y se encargan de la autenticación transparente, de las peticiones a todos los endpoints disponibles y del tratamiento de errores HTTP. Pide a soporte la del lenguaje de tu backend.

¿Te ha resultado útil esta página?