Detecção de Fraude

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:

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

Tipos de documento compatíveis

O modelo document classifica os 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`	Documento de identidade nacional
`municipal_id`	Identificação municipal / local
`passport`	Passaporte
`passport_card`	Cartão de passaporte (tamanho carteira)
`residence_card`	Cartão de autorizaçã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

Financeiros (19 tipos)

Tipo	Descrição
`bank_statement`	Extrato bancário
`business_bank_statement`	Extrato bancário empresarial
`check`	Cheque individual
`list_of_checks_cashed`	Lista de cheques compensados
`check_register`	Registro de cheques
`investment_statement`	Extrato de investimentos
`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 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 veicular
`student_loan_statement`	Extrato de empréstimo estudantil
`personal_loan_statement`	Extrato de empréstimo pessoal
`heloc_statement`	Extrato de crédito com garantia imobiliária
`loan_statement`	Extrato de empréstimo (genérico)

Impostos (9 tipos)

Tipo	Descrição
`form_1040`	Formulário 1040 do IRS (declaração pessoal)
`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 (Sociedade)
`w2_form`	Formulário W-2 de salários e impostos
`form_1099`	Formulário fiscal 1099
`schedule_c`	Anexo C do IRS (renda de negócio)
`schedule_e`	Anexo E do IRS (renda de aluguel)
`tax_return`	Declaração de imposto de renda (genérica)

Emprego (7 tipos)

Tipo	Descrição
`pay_stub`	Holerite / contracheque
`employment_verification_letter`	Carta de verificação de emprego
`direct_deposit_verification`	Verificação de depósito direto
`unemployment_benefits_document`	Documento de benefícios por desemprego
`military_les`	Contracheque militar
`offer_letter`	Carta de oferta de emprego
`self_employment_ledger`	Livro caixa de trabalho autônomo

Propriedade (6 tipos)

Tipo	Descrição
`property_deed`	Escritura de imóvel
`property_tax_receipt`	Recibo de IPTU
`hoa_dues_statement`	Extrato de taxas de condomínio
`lease_agreement`	Contrato de locação
`rental_receipt`	Recibo de aluguel
`title_insurance_policy`	Apólice de seguro de título

Seguros (6 tipos)

Tipo	Descrição
`homeowners_insurance_declarations_page`	Página de declarações de seguro residencial
`homeowners_insurance_binder`	Binder de seguro residencial
`flood_insurance_declarations_page`	Página de declarações de seguro de inundação
`auto_insurance_declarations_page`	Página de declarações de seguro automotivo
`insurance_card`	Carteirinha de seguro
`insurance_document`	Documento de apólice de seguro

Comerciais (6 tipos)

Tipo	Descrição
`business_license`	Alvará de funcionamento
`articles_of_incorporation`	Contrato social
`profit_and_loss_statement`	Demonstrativo de resultados
`utility_bill`	Conta de serviços (energia, água, gás, etc.)
`phone_bill`	Conta de telefone
`petty_cash_receipt`	Recibo de fundo fixo

Legais (7 tipos)

Tipo	Descrição
`government_letter`	Carta governamental (IRS, DMV, SSA, etc.)
`vehicle_registration`	Registro de veículo
`vehicle_title`	Certificado de registro veicular
`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 corresponderem a um tipo conhecido são classificados como other.

Analisando um arquivo

Envie um arquivo para detecção de fraude via 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	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

O tamanho máximo do arquivo é 50 MB. Arquivos que excederem esse limite serão rejeitados com um erro 413.

Estrutura de resposta

Uma resposta de detecção contém os seguintes 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"
      }
    ]
  }
}

Referência de campos

Campo	Tipo	Descrição
`detectionId`	integer	Identificador exclusivo 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 para a 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 dos achados da análise
`modelResults`	object	Contém o array `technicalChecks` com resultados detalhados das verificações
`tags`	object[]	Tags de metadados anexadas a esta detecção
`files`	object[]	Arquivos associados (upload original, heatmaps)

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 todas as etapas 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 todas as etapas de qualidade e foi totalmente analisado
`unverified`	A qualidade do documento é insuficiente — a imagem está borrada, os cantos foram cortados ou verificações semânticas de qualidade falharam
`rejected`	O tipo de documento não é compatível, o conteúdo de texto é insuficiente ou vários documentos foram enviados em um único arquivo

Fundamentação

O array reasoning contém explicações em linguagem natural dos achados da análise. Cada entrada descreve uma observação ou conclusão específica 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, do tipo de arquivo e do 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 para 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`	Possível 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 etapas de qualidade determina o 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 objetos

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 ficará vazio para o modelo de objetos. Quando geração por IA ou manipulação é detectada, um heatmap é incluído no array files destacando as regiões suspeitas.

Heatmaps

Tanto os modelos document quanto object podem gerar imagens de heatmap que destacam visualmente as regiões afetadas. Heatmaps facilitam ver exatamente onde adulteração ou geração por IA foi detectada.

Como os heatmaps funcionam

Heatmaps são imagens PNG sobrepostas ao documento ou imagem original
Modelo de documento: para PDFs com múltiplas páginas, cada página recebe seu próprio heatmap (fd_{id}_heatmap_1.png, fd_{id}_heatmap_2.png etc.)
Modelo de objetos: um único heatmap é gerado por imagem (fd_{id}_heatmap_1.png)
Heatmaps só são gerados quando manipulação ou geração por IA é detectada
Eles aparecem no array files com category: "heatmap"

Recuperando heatmaps

URLs de heatmap são incluídas na resposta de detecção em 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"
    }
  ]
}

Baixe um heatmap usando o endpoint de recuperação de arquivos:

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 / token Bearer ausente ou inválido
`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:

{
  "customerId": "9999",
  "customerName": "Acme Corp",
  "documentId": "DOC-2024-001",
  "companyName": "DeepXL",
  "companyId": "COMP-001"
}

Filtre seu histórico de detecções por tags:

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:

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

Começando

Guias

SDK

Detecção de Fraude

Modelos disponíveis

Tipos de documento compatíveis

Identidade (11 tipos)

Financeiros (19 tipos)

Impostos (9 tipos)

Emprego (7 tipos)

Propriedade (6 tipos)

Seguros (6 tipos)

Comerciais (6 tipos)

Legais (7 tipos)

Analisando um arquivo

Parâmetros

Estrutura de resposta

Referência de campos

Entendendo os resultados

Pontuação de probabilidade

Classificação

Fundamentação

Verificações técnicas

Valores de status

Modelo de documento

Modelo de objetos

Heatmaps

Como os heatmaps funcionam

Recuperando heatmaps

Categorias de arquivo

Códigos de erro

Tags e filtragem

Navegando no histórico

Parâmetros de consulta

Opções de ordenação

Começando

Guias

SDK

​Modelos disponíveis

​Tipos de documento compatíveis

​Identidade (11 tipos)

​Financeiros (19 tipos)

​Impostos (9 tipos)

​Emprego (7 tipos)

​Propriedade (6 tipos)

​Seguros (6 tipos)

​Comerciais (6 tipos)

​Legais (7 tipos)

​Analisando um arquivo

​Parâmetros

​Estrutura de resposta

​Referência de campos

​Entendendo os resultados

​Pontuação de probabilidade

​Classificação

​Fundamentação

​Verificações técnicas

​Valores de status

​Modelo de documento

​Modelo de objetos

​Heatmaps

​Como os heatmaps funcionam

​Recuperando heatmaps

​Categorias de arquivo

​Códigos de erro

​Tags e filtragem

​Navegando no histórico

​Parâmetros de consulta

​Opções de ordenação

Modelos disponíveis

Tipos de documento compatíveis

Identidade (11 tipos)

Financeiros (19 tipos)

Impostos (9 tipos)

Emprego (7 tipos)

Propriedade (6 tipos)

Seguros (6 tipos)

Comerciais (6 tipos)

Legais (7 tipos)

Analisando um arquivo

Parâmetros

Estrutura de resposta

Referência de campos

Entendendo os resultados

Pontuação de probabilidade

Classificação

Fundamentação

Verificações técnicas

Valores de status

Modelo de documento

Modelo de objetos

Heatmaps

Como os heatmaps funcionam

Recuperando heatmaps

Categorias de arquivo

Códigos de erro

Tags e filtragem

Navegando no histórico

Parâmetros de consulta

Opções de ordenação