> ## Documentation Index > Fetch the complete documentation index at: https://docs.deepxl.ai/llms.txt > Use this file to discover all available pages before exploring further. # Detección de fraude > Detecta la manipulación de documentos y contenido generado por IA 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: ```bash theme={null} 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`: ```bash theme={null} 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 que se va a analizar (máx. 50 MB) | | `tags` | string | No | Objeto JSON con pares clave-valor de metadatos | | `country` | string | No | Sugerencia de país opcional. Valores admitidos: `us`, `mx`, `br`. Los valores ausentes, vacíos o no válidos usan `us` de forma predeterminada. | | `document` | string | No | Anulación opcional del tipo de documento para el modelo de documento; por ejemplo, `bank_statement`, `business_bank_statement` o `financial/bank_statement`. Cuando se proporciona, se omite la clasificación. | 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: ```bash theme={null} 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: ```json theme={null} { "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. ```json theme={null} { "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: ```bash theme={null} 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: ```json theme={null} { "customerId": "9999", "customerName": "Acme Corp", "documentId": "DOC-2024-001", "companyName": "DeepXL", "companyId": "COMP-001" } ``` Filtra tu historial de detecciones por etiquetas: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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`