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"

Tipos de documentos compatibles

El modelo document clasifica los archivos cargados en 71 tipos mediante la verificación DOCUMENT_CLASSIFIER, organizados en 8 categorías:

Identidad (11 tipos)

Tipo	Descripción
`driver_license`	Licencia de conducir
`national_id`	Documento nacional de identidad
`municipal_id`	Documento de identidad municipal / del gobierno local
`passport`	Libreta de pasaporte
`passport_card`	Tarjeta de pasaporte (tamaño billetera)
`residence_card`	Tarjeta de permiso de residencia
`work_authorization`	Autorización / permiso de trabajo
`military_id`	Identificación militar
`professional_id`	Licencia / identificación profesional
`voter_registration_card`	Tarjeta de registro electoral
`social_security_card`	Tarjeta del Seguro Social

Financiero (19 tipos)

Tipo	Descripción
`bank_statement`	Estado de cuenta bancaria
`business_bank_statement`	Estado de cuenta bancaria empresarial
`check`	Cheque personal
`list_of_checks_cashed`	Lista de cheques cobrados
`check_register`	Registro de cheques
`investment_statement`	Estado de cuenta de inversión / corretaje
`retirement_account_statement`	Estado de cuenta de jubilación
`pension_statement`	Estado de pensión
`annuity_award_letter`	Carta de concesión de anualidad
`social_security_statement`	Estado del Seguro Social
`social_security_cola_notice`	Aviso COLA del Seguro Social
`disability_income_verification`	Verificación de ingresos por discapacidad
`credit_card_statement`	Estado de cuenta de tarjeta de crédito
`mortgage_statement`	Estado hipotecario
`auto_loan_statement`	Estado de préstamo de auto
`student_loan_statement`	Estado de préstamo estudiantil
`personal_loan_statement`	Estado de préstamo personal
`heloc_statement`	Estado de línea de crédito con garantía hipotecaria
`loan_statement`	Estado de préstamo (genérico)

Fiscal (9 tipos)

Tipo	Descripción
`form_1040`	Formulario 1040 del IRS (declaración personal de impuestos)
`form_1120`	Formulario 1120 del IRS (corporación C)
`form_1120s`	Formulario 1120S del IRS (corporación S)
`form_1065`	Formulario 1065 del IRS (sociedad)
`w2_form`	Declaración salarial y de impuestos W-2
`form_1099`	Formulario fiscal 1099
`schedule_c`	Anexo C del IRS (ingresos comerciales)
`schedule_e`	Anexo E del IRS (ingresos por alquiler)
`tax_return`	Declaración de impuestos (genérica)

Empleo (7 tipos)

Tipo	Descripción
`pay_stub`	Recibo de nómina / comprobante de ingresos
`employment_verification_letter`	Carta de verificación de empleo
`direct_deposit_verification`	Verificación de depósito directo
`unemployment_benefits_document`	Documento de prestaciones por desempleo
`military_les`	Estado de licencia e ingresos militares
`offer_letter`	Carta de oferta
`self_employment_ledger`	Libro contable de trabajo por cuenta propia

Propiedad (6 tipos)

Tipo	Descripción
`property_deed`	Escritura de propiedad
`property_tax_receipt`	Recibo de impuestos sobre la propiedad
`hoa_dues_statement`	Estado de cuotas de HOA / condominio
`lease_agreement`	Contrato de arrendamiento
`rental_receipt`	Recibo de alquiler
`title_insurance_policy`	Póliza de seguro de título

Seguros (6 tipos)

Tipo	Descripción
`homeowners_insurance_declarations_page`	Página de declaraciones del seguro de propietarios
`homeowners_insurance_binder`	Certificado provisional del seguro de propietarios
`flood_insurance_declarations_page`	Página de declaraciones del seguro contra inundaciones
`auto_insurance_declarations_page`	Página de declaraciones del seguro de auto
`insurance_card`	Tarjeta de seguro
`insurance_document`	Documento de póliza de seguro

Comercial (6 tipos)

Tipo	Descripción
`business_license`	Licencia comercial
`articles_of_incorporation`	Estatutos de constitución
`profit_and_loss_statement`	Estado de pérdidas y ganancias
`utility_bill`	Factura de servicios públicos (electricidad, agua, gas, etc.)
`phone_bill`	Factura telefónica
`petty_cash_receipt`	Recibo de caja chica

Legal (7 tipos)

Tipo	Descripción
`government_letter`	Carta gubernamental (IRS, DMV, SSA, etc.)
`vehicle_registration`	Registro del vehículo
`vehicle_title`	Título del vehículo
`court_order`	Orden judicial
`power_of_attorney`	Poder notarial
`death_certificate`	Certificado de defunción
`marriage_certificate`	Certificado de matrimonio

Los archivos que no coincidan con un tipo conocido se clasifican como other.

Análisis de un archivo

Envíe un archivo para la 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","customerName":"Acme Corp","documentId":"INV-001","companyName":"DeepXL","companyId":"COMP-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
`country`	string	No	Sugerencia opcional de país. Valores admitidos: `us`, `mx`, `br`. Los valores ausentes, vacíos o no válidos usan `us` de forma predeterminada.

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

Comportamiento de la sugerencia de país

Use el parámetro opcional country cuando quiera que la API enrute o anote la solicitud con una sugerencia de mercado explícita.

Valores admitidos: us, mx, br
La coincidencia no distingue entre mayúsculas y minúsculas
Se ignoran los espacios en blanco iniciales y finales
Los valores ausentes, vacíos o no válidos recurren a us

Esto es una sugerencia de solicitud, no una afirmación detectada sobre el país emisor. El servicio almacena el valor normalizado en los metadatos y lo devuelve en la respuesta cuando está disponible. Ejemplo:

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

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": "customerName", "value": "Acme Corp" },
      { "name": "documentId", "value": "INV-001" },
      { "name": "companyName", "value": "DeepXL" },
      { "name": "companyId", "value": "COMP-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 de 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 utilizado (`document` o `object`)
`modelVersion`	string	Versión del modelo utilizada para el análisis
`likelihood`	float	Probabilidad de fraude como porcentaje (0–100)
`fraudSeverity`	string	Nivel de gravedad: `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 las verificaciones
`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	Gravedad	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 fuertes indicadores de fraude

Clasificación

El campo classification indica la evaluación de calidad del documento: si el documento superó todas las puertas 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 puertas 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 las verificaciones 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.

Verificaciones técnicas

El arreglo modelResults.technicalChecks contiene las verificaciones forenses individuales realizadas en el archivo. El número y el tipo de verificaciones varían según el modelo, el tipo de archivo y el contenido del documento. Cada objeto de verificación incluye:

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

Valores de estado

Estado	Significado
`PASS`	Verificación superada: no se encontraron problemas
`FAIL`	Verificación fallida: se detectó un problema
`WARNING`	Posible preocupación: no es concluyente, pero vale la pena señalarla
`NOT_PRESENT`	No se pudo realizar la verificació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 puertas de calidad determina la classification (si el documento puede analizarse correctamente). Luego, las verificaciones paralelas de fraude analizan el documento en busca de manipulación y determinan la puntuación likelihood. Pueden ejecutarse verificaciones adicionales según el tipo de archivo y la categoría del documento.

Modelo de objetos

El modelo object devuelve los 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 o manipulación por IA, se incluye un mapa de calor en el arreglo files que resalta las regiones sospechosas.

{
  "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 faltante o inválida
`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",
  "companyName": "DeepXL",
  "companyId": "COMP-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 Recupere resultados de detección paginados 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 que se omiten
`sortBy`	string	Campo por el que se ordena (vea las opciones a continuación)
`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 gravedad: `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

Documentation Index

​Modelos disponibles

​Tipos de documentos compatibles

​Identidad (11 tipos)

​Financiero (19 tipos)

​Fiscal (9 tipos)

​Empleo (7 tipos)

​Propiedad (6 tipos)

​Seguros (6 tipos)

​Comercial (6 tipos)

​Legal (7 tipos)

​Análisis de un archivo

​Parámetros

​Comportamiento de la sugerencia de país

​Estructura de la respuesta

​Referencia de campos

​Comprender los resultados

​Puntuación de probabilidad

​Clasificación

​Razonamiento

​Verificaciones técnicas

​Valores de estado

​Modelo de documentos

​Modelo de objetos

​Categorías de archivos

​Códigos de error

​Etiquetas y filtrado

​Navegar el historial

​Parámetros de consulta

​Opciones de ordenación

​Parámetros de consulta

​Opciones de ordenación

Modelos disponibles

Tipos de documentos compatibles

Identidad (11 tipos)

Financiero (19 tipos)

Fiscal (9 tipos)

Empleo (7 tipos)

Propiedad (6 tipos)

Seguros (6 tipos)

Comercial (6 tipos)

Legal (7 tipos)

Análisis de un archivo

Parámetros

Comportamiento de la sugerencia de país

Estructura de la respuesta

Referencia de campos

Comprender los resultados

Puntuación de probabilidad

Clasificación

Razonamiento

Verificaciones técnicas

Valores de estado

Modelo de documentos

Modelo de objetos

Categorías de archivos

Códigos de error

Etiquetas y filtrado

Navegar el historial

Parámetros de consulta

Opciones de ordenación

Parámetros de consulta

Opciones de ordenación