Detección de fraude

La API de Detección de fraude utiliza IA forense para detectar documentos e imágenes manipulados, alterados y generados por IA en tiempo real.

Modelos disponibles

Modelo	Caso de uso	Tipos de archivo compatibles
`document`	Detecta documentos e identificaciones generados por IA o alterados (extractos bancarios, facturas, pasaportes, licencias de conducir)	jpg, jpeg, png, webp, pdf
`object`	Detecta imágenes generadas por IA o manipuladas (fotos, evidencia de reclamaciones, recibos)	jpg, jpeg, png, webp

Recupera la lista completa de modelos mediante programación:

curl https://api.deepxl.ai/v1/detection-models \
  -H "x-api-key: YOUR_API_KEY"

Análisis de un archivo

Envía un archivo para detección de fraude mediante POST /v1/detection:

curl -X POST https://api.deepxl.ai/v1/detection \
  -H "x-api-key: YOUR_API_KEY" \
  -F "model=document" \
  -F "file=@invoice.pdf" \
  -F 'tags={"customerId":"9999","documentId":"INV-001"}'

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`model`	string	Sí	`document` o `object`
`file`	file	Sí	El archivo a analizar (máx. 50 MB)
`tags`	string	No	Objeto JSON con pares clave-valor de metadatos

El tamaño máximo de archivo es 50 MB. Los archivos que superen este límite se rechazarán con un error 413.

Estructura de la respuesta

Una respuesta de detección contiene los siguientes campos:

{
  "result": {
    "detectionId": 42,
    "mediaType": "document",
    "fileType": "pdf",
    "fileName": "bank_statement.pdf",
    "fileSize": 245678,
    "timestamp": 1725795600,
    "timestampISO": "2024-09-08T10:00:00.000000",
    "model": "document",
    "modelVersion": "1.1.0",
    "likelihood": 85.2,
    "fraudSeverity": "high",
    "classification": "verified",
    "reasoning": [
      "Potential manipulation detected in text region",
      "Font inconsistencies found"
    ],
    "modelResults": {
      "technicalChecks": [
        {
          "type": "DOCUMENT_CLASSIFIER",
          "status": "PASS",
          "details": "Classified as bank statement",
          "likelihood": 0.02
        },
        {
          "type": "SEMANTIC_FRAUD",
          "status": "FAIL",
          "details": "Detected inconsistencies in text formatting",
          "likelihood": 0.85
        }
      ]
    },
    "tags": [
      { "name": "customerId", "value": "9999" },
      { "name": "documentId", "value": "INV-001" }
    ],
    "files": [
      {
        "category": "original_file",
        "fileName": "fd_42_bank_statement.pdf",
        "fileSize": 245678,
        "contentType": "application/pdf",
        "timestamp": 1725795600,
        "timestampISO": "2024-09-08T10:00:00.000000",
        "url": "https://api.deepxl.ai/v1/files/fd_42_bank_statement.pdf"
      },
      {
        "category": "heatmap",
        "fileName": "fd_42_heatmap_1.png",
        "fileSize": 45678,
        "contentType": "image/png",
        "timestamp": 1725795600,
        "timestampISO": "2024-09-08T10:00:00.000000",
        "url": "https://api.deepxl.ai/v1/files/fd_42_heatmap_1.png"
      }
    ]
  }
}

Referencia de campos

Campo	Tipo	Descripción
`detectionId`	integer	Identificador único del registro de detección
`mediaType`	string	Categoría de tipo de medio (`image` o `document`)
`fileType`	string	Extensión del archivo (`jpeg`, `png`, `pdf`, `webp`)
`fileName`	string	Nombre original del archivo cargado
`fileSize`	integer	Tamaño del archivo en bytes
`timestamp`	integer	Marca de tiempo Unix del análisis
`timestampISO`	string	Marca de tiempo ISO 8601 del análisis
`model`	string	Modelo usado (`document` o `object`)
`modelVersion`	string	Versión del modelo usado para el análisis
`likelihood`	float	Probabilidad de fraude como porcentaje (0–100)
`fraudSeverity`	string	Nivel de severidad: `low`, `medium` o `high`
`classification`	string	Evaluación de calidad: `verified`, `unverified` o `rejected`
`reasoning`	string[]	Explicaciones en lenguaje natural de los hallazgos del análisis
`modelResults`	object	Contiene el arreglo `technicalChecks` con resultados detallados de comprobaciones
`tags`	object[]	Etiquetas de metadatos adjuntas a esta detección
`files`	object[]	Archivos asociados (carga original, mapas de calor)

Comprender los resultados

Puntuación de probabilidad

El campo likelihood es una puntuación de 0–100% que indica la probabilidad de fraude o manipulación:

Rango	Severidad	Interpretación
0–29%	`low`	No hay indicadores significativos de manipulación
30–69%	`medium`	Se detectaron algunos indicadores de manipulación
70–100%	`high`	Se detectaron indicadores sólidos de fraude

Clasificación

El campo classification indica la evaluación de calidad del documento — si el documento superó todas las compuertas de calidad y pudo analizarse correctamente. Esto es independiente del resultado de fraude (likelihood / fraudSeverity).

Clasificación	Significado
`verified`	La calidad del documento es buena — superó todas las compuertas de calidad y se analizó por completo
`unverified`	La calidad del documento es insuficiente — la imagen está borrosa, las esquinas están recortadas o fallaron comprobaciones de calidad semántica
`rejected`	El tipo de documento no es compatible, el contenido de texto es insuficiente o se enviaron varios documentos en un solo archivo

Razonamiento

El arreglo reasoning contiene explicaciones en lenguaje natural de los hallazgos del análisis. Cada entrada describe una observación o conclusión específica del análisis forense.

Comprobaciones técnicas

El arreglo modelResults.technicalChecks contiene las comprobaciones forenses individuales realizadas sobre el archivo. El número y el tipo de comprobaciones varía según el modelo, el tipo de archivo y el contenido del documento. Cada objeto de comprobación incluye:

Campo	Tipo	Descripción
`type`	string	Identificador de la comprobación
`status`	string	`PASS`, `FAIL`, `WARNING` o `NOT_PRESENT`
`details`	string	Explicación legible para humanos del resultado de la comprobación
`likelihood`	float	Puntuación de confianza para esta comprobación específica (0.0–1.0)

Valores de estado

Estado	Significado
`PASS`	Comprobación aprobada — no se encontraron problemas
`FAIL`	Comprobación fallida — se detectó un problema
`WARNING`	Preocupación potencial — no es concluyente, pero vale la pena señalarlo
`NOT_PRESENT`	No se pudo realizar la comprobación — los datos requeridos no estaban disponibles en el archivo

Modelo de documentos

El modelo document ejecuta una canalización de varias etapas. Primero, una serie de compuertas de calidad determinan classification (si el documento puede analizarse correctamente). Luego, comprobaciones de fraude en paralelo analizan el documento en busca de manipulación y determinan la puntuación likelihood. Pueden ejecutarse comprobaciones adicionales según el tipo de archivo y la categoría del documento.

Modelo de objetos

El modelo object devuelve resultados de detección de fraude mediante los campos de nivel superior likelihood, fraudSeverity e reasoning. El arreglo technicalChecks estará vacío para el modelo de objetos. Cuando se detecta generación por IA o manipulación, se incluye un mapa de calor en el arreglo files que resalta las regiones sospechosas.

Mapas de calor

Tanto el modelo document como el modelo object pueden generar imágenes de mapa de calor que resaltan visualmente las regiones afectadas. Los mapas de calor facilitan ver exactamente dónde se detectó manipulación o generación por IA.

Cómo funcionan los mapas de calor

Los mapas de calor son imágenes PNG superpuestas sobre el documento o la imagen originales
Modelo de documentos: para PDFs de varias páginas, cada página obtiene su propio mapa de calor (fd_{id}_heatmap_1.png, fd_{id}_heatmap_2.png, etc.)
Modelo de objetos: se genera un solo mapa de calor por imagen (fd_{id}_heatmap_1.png)
Los mapas de calor solo se generan cuando se detecta manipulación o generación por IA
Aparecen en el arreglo files con category: "heatmap"

Recuperar mapas de calor

Las URL de mapas de calor se incluyen en la respuesta de detección bajo files:

{
  "files": [
    {
      "category": "original_file",
      "fileName": "fd_42_bank_statement.pdf",
      "url": "https://api.deepxl.ai/v1/files/fd_42_bank_statement.pdf"
    },
    {
      "category": "heatmap",
      "fileName": "fd_42_heatmap_1.png",
      "url": "https://api.deepxl.ai/v1/files/fd_42_heatmap_1.png"
    },
    {
      "category": "heatmap",
      "fileName": "fd_42_heatmap_2.png",
      "url": "https://api.deepxl.ai/v1/files/fd_42_heatmap_2.png"
    }
  ]
}

Descarga un mapa de calor usando el endpoint de recuperación de archivos:

curl https://api.deepxl.ai/v1/files/fd_42_heatmap_1.png \
  -H "x-api-key: YOUR_API_KEY" \
  --output heatmap_page1.png

Categorías de archivos

Categoría	Descripción
`original_file`	El archivo que subiste originalmente
`heatmap`	Mapa de calor generado que resalta las regiones de manipulación detectadas

Códigos de error

Estado	Error	Descripción
`400`	Solicitud incorrecta	Nombre de modelo inválido, parámetro de ordenación inválido, JSON malformado en las etiquetas o parámetros de consulta inválidos
`401`	No autorizado	Clave de API / token Bearer faltante o inválido
`404`	No encontrado	No se encontró el registro de detección
`413`	Carga útil demasiado grande	El archivo supera el tamaño máximo de 50 MB
`415`	Tipo de medio no compatible	El tipo de archivo no es compatible con el modelo seleccionado
`500`	Error interno del servidor	Error inesperado del servidor — contacta con soporte si persiste
`502`	Puerta de enlace incorrecta	El servicio de análisis ascendente no está disponible temporalmente — reintenta después de un breve retraso

Etiquetas y filtrado

Pasa un objeto JSON en el parámetro tags para adjuntar metadatos a tu análisis:

{
  "customerId": "9999",
  "customerName": "Acme Corp",
  "documentId": "DOC-2024-001"
}

Filtra tu historial de detecciones por etiquetas:

curl "https://api.deepxl.ai/v1/detection?tagFilter=customerId=9999" \
  -H "x-api-key: YOUR_API_KEY"

Navegar el historial

Recupera resultados paginados de detección con ordenación y filtrado:

curl "https://api.deepxl.ai/v1/detection?limit=25&offset=0&sortBy=createdOn&direction=desc" \
  -H "x-api-key: YOUR_API_KEY"

Parámetros de consulta

Parámetro	Tipo	Descripción
`limit`	integer	Número de resultados por página (predeterminado: 25)
`offset`	integer	Número de resultados a omitir
`sortBy`	string	Campo por el que ordenar (ver opciones abajo)
`direction`	string	`asc` o `desc`
`minLikelihood`	float	Filtro de probabilidad mínima (0–100)
`maxLikelihood`	float	Filtro de probabilidad máxima (0–100)
`fraudSeverity`	string	Filtrar por severidad: `low`, `medium` o `high`
`classification`	string	Filtrar por clasificación: `verified`, `unverified` o `rejected`
`tagFilter`	string	Filtrar por etiqueta (formato: `key=value`)
`minTimestamp`	integer	Marca de tiempo Unix mínima
`maxTimestamp`	integer	Marca de tiempo Unix máxima

Opciones de ordenación

fraudDetectionId, fileName, fileSize, fileType, model, likelihood, createdOn

Primeros pasos

Guías

SDK

Detección de fraude

Modelos disponibles

Análisis de un archivo

Parámetros

Estructura de la respuesta

Referencia de campos

Comprender los resultados

Puntuación de probabilidad

Clasificación

Razonamiento

Comprobaciones técnicas

Valores de estado

Modelo de documentos

Modelo de objetos

Mapas de calor

Cómo funcionan los mapas de calor

Recuperar mapas de calor

Categorías de archivos

Códigos de error

Etiquetas y filtrado

Navegar el historial

Parámetros de consulta

Opciones de ordenación

Primeros pasos

Guías

SDK

​Modelos disponibles

​Análisis de un archivo

​Parámetros

​Estructura de la respuesta

​Referencia de campos

​Comprender los resultados

​Puntuación de probabilidad

​Clasificación

​Razonamiento

​Comprobaciones técnicas

​Valores de estado

​Modelo de documentos

​Modelo de objetos

​Mapas de calor

​Cómo funcionan los mapas de calor

​Recuperar mapas de calor

​Categorías de archivos

​Códigos de error

​Etiquetas y filtrado

​Navegar el historial

​Parámetros de consulta

​Opciones de ordenación

Modelos disponibles

Análisis de un archivo

Parámetros

Estructura de la respuesta

Referencia de campos

Comprender los resultados

Puntuación de probabilidad

Clasificación

Razonamiento

Comprobaciones técnicas

Valores de estado

Modelo de documentos

Modelo de objetos

Mapas de calor

Cómo funcionan los mapas de calor

Recuperar mapas de calor

Categorías de archivos

Códigos de error

Etiquetas y filtrado

Navegar el historial

Parámetros de consulta

Opciones de ordenación