> ## 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. # Detecção de Fraude > Detecte manipulação de documentos e conteúdo gerado por IA A API de Detecção de Fraude usa IA forense para detectar documentos e imagens manipulados, alterados e gerados por IA em tempo real. ## Modelos disponíveis | Modelo | Caso de uso | Tipos de arquivo compatíveis | | ---------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | `document` | Detecta documentos e IDs gerados por IA ou alterados (extratos bancários, faturas, passaportes, carteiras de motorista) | jpg, jpeg, png, webp, pdf | | `object` | Detecta imagens geradas por IA ou manipuladas (fotos, evidências de sinistro, comprovantes) | jpg, jpeg, png, webp | Recupere programaticamente a lista completa de modelos: ```bash theme={null} curl https://api.deepxl.ai/v1/detection-models \ -H "x-api-key: YOUR_API_KEY" ``` ## Tipos de documentos compatíveis A classe de modelo `document` classifica arquivos enviados em 71 tipos por meio da verificação `DOCUMENT_CLASSIFIER`, organizados em 8 categorias: ### Identidade (11 tipos) | Tipo | Descrição | | ------------------------- | ----------------------------------------- | | `driver_license` | Carteira de motorista | | `national_id` | Carteira de identidade nacional | | `municipal_id` | Documento de identidade municipal / local | | `passport` | Passaporte | | `passport_card` | Cartão de passaporte | | `residence_card` | Cartão de permissão de residência | | `work_authorization` | Autorização / permissão de trabalho | | `military_id` | Identificação militar | | `professional_id` | Licença / identificação profissional | | `voter_registration_card` | Título de eleitor | | `social_security_card` | Cartão do Seguro Social | ### Financeiro (19 tipos) | Tipo | Descrição | | -------------------------------- | ---------------------------------------------------- | | `bank_statement` | Extrato bancário | | `business_bank_statement` | Extrato de conta bancária empresarial | | `check` | Cheque individual | | `list_of_checks_cashed` | Lista de cheques compensados | | `check_register` | Registro de cheques | | `investment_statement` | Extrato de investimentos / corretora | | `retirement_account_statement` | Extrato de conta de aposentadoria | | `pension_statement` | Extrato de pensão | | `annuity_award_letter` | Carta de concessão de anuidade | | `social_security_statement` | Extrato do Seguro Social | | `social_security_cola_notice` | Aviso de COLA do Seguro Social | | `disability_income_verification` | Verificação de renda por invalidez | | `credit_card_statement` | Fatura de cartão de crédito | | `mortgage_statement` | Extrato de hipoteca | | `auto_loan_statement` | Extrato de financiamento de veículo | | `student_loan_statement` | Extrato de empréstimo estudantil | | `personal_loan_statement` | Extrato de empréstimo pessoal | | `heloc_statement` | Extrato de linha de crédito com garantia imobiliária | | `loan_statement` | Extrato de empréstimo (genérico) | ### Fiscal (9 tipos) | Tipo | Descrição | | ------------ | --------------------------------------------------------------------- | | `form_1040` | Formulário 1040 do IRS (declaração de imposto de renda pessoa física) | | `form_1120` | Formulário 1120 do IRS (C-Corporation) | | `form_1120s` | Formulário 1120S do IRS (S-Corporation) | | `form_1065` | Formulário 1065 do IRS (Partnership) | | `w2_form` | Declaração de salários e impostos W-2 | | `form_1099` | Formulário fiscal 1099 | | `schedule_c` | Schedule C do IRS (renda empresarial) | | `schedule_e` | Schedule E do IRS (renda de aluguel) | | `tax_return` | Declaração de imposto (genérica) | ### Emprego (7 tipos) | Tipo | Descrição | | -------------------------------- | ------------------------------------- | | `pay_stub` | Holerite / comprovante de rendimentos | | `employment_verification_letter` | Carta de verificação de emprego | | `direct_deposit_verification` | Verificação de depósito direto | | `unemployment_benefits_document` | Documento de benefício de desemprego | | `military_les` | Military Leave and Earnings Statement | | `offer_letter` | Carta de oferta | | `self_employment_ledger` | Registro de trabalho autônomo | ### Propriedade (6 tipos) | Tipo | Descrição | | ------------------------ | ------------------------------------ | | `property_deed` | Escritura de imóvel | | `property_tax_receipt` | Recibo de imposto sobre propriedade | | `hoa_dues_statement` | Extrato de taxas de HOA / condomínio | | `lease_agreement` | Contrato de locação | | `rental_receipt` | Recibo de aluguel | | `title_insurance_policy` | Apólice de seguro de título | ### Seguro (6 tipos) | Tipo | Descrição | | ---------------------------------------- | ------------------------------------------------ | | `homeowners_insurance_declarations_page` | Página de declarações do seguro residencial | | `homeowners_insurance_binder` | Binder do seguro residencial | | `flood_insurance_declarations_page` | Página de declarações do seguro contra enchentes | | `auto_insurance_declarations_page` | Página de declarações do seguro automotivo | | `insurance_card` | Cartão de seguro | | `insurance_document` | Documento da apólice de seguro | ### Comercial (6 tipos) | Tipo | Descrição | | --------------------------- | -------------------------------------------------- | | `business_license` | Licença comercial | | `articles_of_incorporation` | Contrato social / atos constitutivos | | `profit_and_loss_statement` | Demonstrativo de lucros e perdas | | `utility_bill` | Conta de serviço público (energia, água, gás etc.) | | `phone_bill` | Conta de telefone | | `petty_cash_receipt` | Recibo de caixa pequeno | ### Jurídico (7 tipos) | Tipo | Descrição | | ---------------------- | ---------------------------------------- | | `government_letter` | Carta governamental (IRS, DMV, SSA etc.) | | `vehicle_registration` | Registro de veículo | | `vehicle_title` | Título de veículo | | `court_order` | Ordem judicial | | `power_of_attorney` | Procuração | | `death_certificate` | Certidão de óbito | | `marriage_certificate` | Certidão de casamento | Arquivos que não correspondem a um tipo conhecido são classificados como `other`. ## Analisando um arquivo Envie um arquivo para detecção de fraude via `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 | Obrigatório | Descrição | | --------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------ | | `model` | string | Sim | `document` ou `object` | | `file` | file | Sim | O arquivo a ser analisado (máx. 50 MB) | | `tags` | string | Não | Objeto JSON com pares chave-valor de metadados | | `country` | string | Não | Dica opcional de país. Valores compatíveis: `us`, `mx`, `br`. Valores ausentes, vazios ou inválidos assumem, por padrão, `us`. | O tamanho máximo do arquivo é **50 MB**. Arquivos que excederem esse limite serão rejeitados com um erro `413`. ### Comportamento da dica de país Use o parâmetro opcional `country` quando quiser que a API encaminhe ou anote a requisição com uma dica explícita de mercado. * Valores compatíveis: `us`, `mx`, `br` * A correspondência não diferencia maiúsculas de minúsculas * Espaços em branco no início e no fim são ignorados * Valores ausentes, vazios ou inválidos retornam para `us` Esta é uma **dica de requisição**, não uma alegação detectada sobre o país emissor. O serviço armazena o valor normalizado nos metadados e o retorna na resposta quando disponível. Exemplo: ```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"}' ``` ## Estrutura da resposta Uma resposta de detecção contém os seguintes 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" } ] } } ``` ### Referência dos campos | Campo | Tipo | Descrição | | ---------------- | --------- | --------------------------------------------------------------------------- | | `detectionId` | integer | Identificador único do registro de detecção | | `mediaType` | string | Categoria do tipo de mídia (`image` ou `document`) | | `fileType` | string | Extensão do arquivo (`jpeg`, `png`, `pdf`, `webp`) | | `fileName` | string | Nome original do arquivo enviado | | `fileSize` | integer | Tamanho do arquivo em bytes | | `timestamp` | integer | Timestamp Unix da análise | | `timestampISO` | string | Timestamp ISO 8601 da análise | | `model` | string | Modelo usado (`document` ou `object`) | | `modelVersion` | string | Versão do modelo usada na análise | | `likelihood` | float | Probabilidade de fraude em porcentagem (0–100) | | `fraudSeverity` | string | Nível de severidade: `low`, `medium` ou `high` | | `classification` | string | Avaliação de qualidade: `verified`, `unverified` ou `rejected` | | `reasoning` | string\[] | Explicações em linguagem natural sobre os achados da análise | | `modelResults` | object | Contém o array `technicalChecks` com resultados detalhados das verificações | | `tags` | object\[] | Tags de metadados associadas a esta detecção | | `files` | object\[] | Arquivos associados (upload original, mapas de calor) | ## Entendendo os resultados ### Pontuação de probabilidade O campo `likelihood` é uma pontuação de 0–100% que indica a probabilidade de fraude ou manipulação: | Faixa | Severidade | Interpretação | | ------- | ---------- | --------------------------------------------- | | 0–29% | `low` | Nenhum indicador significativo de manipulação | | 30–69% | `medium` | Alguns indicadores de manipulação detectados | | 70–100% | `high` | Fortes indicadores de fraude detectados | ### Classificação O campo `classification` indica a **avaliação de qualidade** do documento — se o documento passou por todos os filtros de qualidade e pôde ser analisado corretamente. Isso é separado do resultado de fraude (`likelihood` / `fraudSeverity`). | Classificação | Significado | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `verified` | A qualidade do documento é boa — passou por todos os filtros de qualidade e foi totalmente analisado | | `unverified` | A qualidade do documento é insuficiente — a imagem está borrada, os cantos estão cortados ou as verificações semânticas de qualidade falharam | | `rejected` | O tipo de documento não é compatível, o conteúdo textual é insuficiente ou vários documentos foram enviados em um único arquivo | ### Raciocínio O array `reasoning` contém explicações em linguagem natural sobre os achados da análise. Cada entrada descreve uma observação específica ou conclusão da análise forense. ## Verificações técnicas O array `modelResults.technicalChecks` contém as verificações forenses individuais realizadas no arquivo. O número e o tipo de verificações variam dependendo do modelo, tipo de arquivo e conteúdo do documento. Cada objeto de verificação inclui: | Campo | Tipo | Descrição | | ------------ | ------ | ----------------------------------------------------------------- | | `type` | string | Identificador da verificação | | `status` | string | `PASS`, `FAIL`, `WARNING` ou `NOT_PRESENT` | | `details` | string | Explicação legível por humanos do resultado da verificação | | `likelihood` | float | Pontuação de confiança para esta verificação específica (0.0–1.0) | ### Valores de status | Status | Significado | | ------------- | ---------------------------------------------------------------------------------------------- | | `PASS` | Verificação aprovada — nenhum problema encontrado | | `FAIL` | Verificação reprovada — problema detectado | | `WARNING` | Potencial preocupação — não é conclusivo, mas vale observar | | `NOT_PRESENT` | A verificação não pôde ser realizada — os dados necessários não estavam disponíveis no arquivo | ### Modelo de documento O modelo `document` executa um pipeline de múltiplas etapas. Primeiro, uma série de **filtros de qualidade** determina a `classification` (se o documento pode ser analisado corretamente). Em seguida, **verificações paralelas de fraude** analisam o documento em busca de manipulação e determinam a pontuação `likelihood`. Verificações adicionais podem ser executadas dependendo do tipo de arquivo e da categoria do documento. ### Modelo de objeto O modelo `object` retorna resultados de detecção de fraude por meio dos campos de nível superior `likelihood`, `fraudSeverity` e `reasoning`. O array `technicalChecks` estará vazio para o modelo de objeto. Quando a geração ou manipulação por IA é detectada, um **mapa de calor** é incluído no array `files` destacando as regiões suspeitas. ```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" } ] } ``` Baixe um heatmap usando o endpoint de recuperação de arquivos: ```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 ``` ### Categorias de arquivo | Categoria | Descrição | | --------------- | ----------------------------------------------------------- | | `original_file` | O arquivo que você enviou originalmente | | `heatmap` | Heatmap gerado destacando regiões de manipulação detectadas | ## Códigos de erro | Status | Erro | Descrição | | ------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `400` | Solicitação inválida | Nome de modelo inválido, parâmetro de ordenação inválido, JSON malformado em tags ou parâmetros de consulta inválidos | | `401` | Não autorizado | Chave de API ausente ou inválida | | `404` | Não encontrado | Registro de detecção não encontrado | | `413` | Payload muito grande | O arquivo excede o tamanho máximo de 50 MB | | `415` | Tipo de mídia não suportado | O tipo de arquivo não é compatível com o modelo selecionado | | `500` | Erro interno do servidor | Erro inesperado do servidor — contate o suporte se persistir | | `502` | Gateway inválido | O serviço upstream de análise está temporariamente indisponível — tente novamente após um curto intervalo | ## Tags e filtragem Passe um objeto JSON no parâmetro `tags` para anexar metadados à sua análise: ```json theme={null} { "customerId": "9999", "customerName": "Acme Corp", "documentId": "DOC-2024-001", "companyName": "DeepXL", "companyId": "COMP-001" } ``` Filtre seu histórico de detecções por tags: ```bash theme={null} curl "https://api.deepxl.ai/v1/detection?tagFilter=customerId=9999" \ -H "x-api-key: YOUR_API_KEY" ``` ## Navegando no histórico Recupere resultados de detecção paginados com ordenação e filtragem: ```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 | Descrição | | ---------------- | ------- | ----------------------------------------------------------------- | | `limit` | integer | Número de resultados por página (padrão: 25) | | `offset` | integer | Número de resultados a pular | | `sortBy` | string | Campo para ordenar (veja as opções abaixo) | | `direction` | string | `asc` ou `desc` | | `minLikelihood` | float | Filtro de probabilidade mínima (0–100) | | `maxLikelihood` | float | Filtro de probabilidade máxima (0–100) | | `fraudSeverity` | string | Filtrar por severidade: `low`, `medium` ou `high` | | `classification` | string | Filtrar por classificação: `verified`, `unverified` ou `rejected` | | `tagFilter` | string | Filtrar por tag (formato: `key=value`) | | `minTimestamp` | integer | Timestamp Unix mínimo | | `maxTimestamp` | integer | Timestamp Unix máximo | ### Opções de ordenação `fraudDetectionId`, `fileName`, `fileSize`, `fileType`, `model`, `likelihood`, `createdOn` Recupere resultados de detecção paginados com ordenação e filtragem: ```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 | Descrição | | ---------------- | ------- | ----------------------------------------------------------------- | | `limit` | integer | Número de resultados por página (padrão: 25) | | `offset` | integer | Número de resultados a ignorar | | `sortBy` | string | Campo usado para ordenar (veja as opções abaixo) | | `direction` | string | `asc` ou `desc` | | `minLikelihood` | float | Filtro de probabilidade mínima (0–100) | | `maxLikelihood` | float | Filtro de probabilidade máxima (0–100) | | `fraudSeverity` | string | Filtrar por severidade: `low`, `medium` ou `high` | | `classification` | string | Filtrar por classificação: `verified`, `unverified` ou `rejected` | | `tagFilter` | string | Filtrar por tag (formato: `key=value`) | | `minTimestamp` | integer | Timestamp Unix mínimo | | `maxTimestamp` | integer | Timestamp Unix máximo | ### Opções de ordenação `fraudDetectionId`, `fileName`, `fileSize`, `fileType`, `model`, `likelihood`, `createdOn`