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 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:

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:

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:

{
  "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.

{
  "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 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:

{
  "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 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 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

Documentation Index

​Modelos disponíveis

​Tipos de documentos compatíveis

​Identidade (11 tipos)

​Financeiro (19 tipos)

​Fiscal (9 tipos)

​Emprego (7 tipos)

​Propriedade (6 tipos)

​Seguro (6 tipos)

​Comercial (6 tipos)

​Jurídico (7 tipos)

​Analisando um arquivo

​Parâmetros

​Comportamento da dica de país

​Estrutura da resposta

​Referência dos campos

​Entendendo os resultados

​Pontuação de probabilidade

​Classificação

​Raciocínio

​Verificações técnicas

​Valores de status

​Modelo de documento

​Modelo de objeto

​Categorias de arquivo

​Códigos de erro

​Tags e filtragem

​Navegando no histórico

​Parâmetros de consulta

​Opções de ordenação

​Parâmetros de consulta

​Opções de ordenação

Modelos disponíveis

Tipos de documentos compatíveis

Identidade (11 tipos)

Financeiro (19 tipos)

Fiscal (9 tipos)

Emprego (7 tipos)

Propriedade (6 tipos)

Seguro (6 tipos)

Comercial (6 tipos)

Jurídico (7 tipos)

Analisando um arquivo

Parâmetros

Comportamento da dica de país

Estrutura da resposta

Referência dos campos

Entendendo os resultados

Pontuação de probabilidade

Classificação

Raciocínio

Verificações técnicas

Valores de status

Modelo de documento

Modelo de objeto

Categorias de arquivo

Códigos de erro

Tags e filtragem

Navegando no histórico

Parâmetros de consulta

Opções de ordenação

Parâmetros de consulta

Opções de ordenação