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"

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","documentId":"INV-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": "documentId", "value": "INV-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"
}

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

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

​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

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