Data Extraction

O Building Block Data Extraction fornece funcionalidades para extração automatizada de dados de documentos usando Inteligência Artificial, com suporte a múltiplos provedores de LLM.

Visão Geral

O Data Extraction é um módulo tenant-scoped, ou seja, requer um token com organizationId. Ele é responsável por:

Provider Configs - Configuração de provedores de IA (OpenAI, Anthropic, Google Gemini)
Templates - Definição de campos esperados para cada tipo de documento
Field Mappings - Transformação e normalização de dados extraídos
Extractions - Execução de extrações e acompanhamento de status

Base URL

https://data-extraction.stg.catalisa.app

Recursos

Recurso	Descrição
Provider Configs	Configuração de provedores de IA
Templates	Definição de templates de extração
Field Mappings	Mapeamento e transformação de campos
Extractions	Execução e gerenciamento de extrações

Permissões

Permissão	Descrição
`DATA_EXTRACTION_CREATE`	Criar extrações
`DATA_EXTRACTION_READ`	Listar e visualizar extrações
`DATA_EXTRACTION_DELETE`	Excluir extrações
`DATA_EXTRACTION_ADMIN`	Gerenciar configurações de provedor e templates

Provedores Suportados

Provedor	Tipo	Modelos Principais	Status
OpenAI	`OPENAI`	GPT-4o, GPT-4 Turbo	Suportado
Anthropic	`ANTHROPIC`	Claude 3.5 Sonnet, Claude 3 Opus	Suportado
Google	`GOOGLE_GEMINI`	Gemini 1.5 Pro, Gemini 1.5 Flash	Suportado

Status da Extração

Status	Descrição
`PENDING`	Aguardando processamento
`PROCESSING`	Em processamento pelo provedor
`COMPLETED`	Extração concluída com sucesso
`FAILED`	Falha na extração

Tipos de Transformação

O Data Extraction suporta transformações automáticas dos dados extraídos:

Tipo	Descrição	Exemplo
`NONE`	Sem transformação	Valor mantido como extraído
`DATE_FORMAT`	Formatação de data	`DD/MM/YYYY` → `YYYY-MM-DD`
`CURRENCY_NORMALIZE`	Normalização de moeda	`R$ 1.234,56` → `1234.56`
`NUMBER_PARSE`	Parsing de número	`1.234,56` → `1234.56`
`STRING_TRIM`	Remoção de espaços	`" texto "` → `"texto"`
`REGEX_EXTRACT`	Extração por regex	Captura grupos específicos

Fluxo de Extração

O fluxo típico de extração de dados segue estas etapas:

Etapas

1. Configurar provedor (uma vez)

Criar uma configuração de provedor com credenciais
Testar a conexão
Definir como provedor padrão

2. Criar template de extração

Definir tipo de documento (RG, CNH, comprovante, etc.)
Especificar campos esperados com tipos
Opcionalmente, customizar o prompt de extração

3. Configurar mapeamentos (opcional)

Mapear campos extraídos para campos do sistema
Definir transformações (datas, moedas, etc.)
Configurar valores padrão

4. Executar extração

Enviar documento (via File Storage ou base64)
Especificar template a utilizar
Acompanhar status da extração

5. Obter resultados

Dados brutos extraídos (rawData)
Dados mapeados (mappedData)
Scores de confiança por campo

Eventos

O Data Extraction publica os seguintes eventos via Redis Pub/Sub, disponíveis para integração com o Webhooks Engine:

Evento	Descrição
`data-extraction.extraction.started`	Extração iniciada
`data-extraction.extraction.completed`	Extração concluída com sucesso
`data-extraction.extraction.failed`	Falha na extração
`data-extraction.extraction.retry`	Tentativa de reprocessamento

Payload dos Eventos

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "extractionId": "550e8400-e29b-41d4-a716-446655440001",
  "status": "COMPLETED",
  "fileId": "550e8400-e29b-41d4-a716-446655440002",
  "businessId": "loan-application-123",
  "metadata": {
    "documentType": "RG",
    "processingTimeMs": 2340
  }
}

Exemplo Rápido

Fluxo completo para extrair dados de um documento:

// 1. Configurar provedor (apenas uma vez)
const configResponse = await fetch('https://data-extraction.stg.catalisa.app/api/v1/data-extraction/provider-configs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'extraction-provider-config',
      attributes: {
        name: 'OpenAI Produção',
        providerType: 'OPENAI',
        credentials: {
          apiKey: 'sk-...',
        },
        isDefault: true,
        isActive: true,
        settings: {
          model: 'gpt-4o',
          maxTokens: 4096,
        },
      },
    },
  }),
});

const { data: config } = await configResponse.json();

// 2. Criar template para RG
const templateResponse = await fetch('https://data-extraction.stg.catalisa.app/api/v1/data-extraction/templates', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'extraction-template',
      attributes: {
        name: 'RG - Registro Geral',
        documentType: 'RG',
        expectedFields: [
          { name: 'nome', type: 'string', required: true },
          { name: 'rg', type: 'string', required: true },
          { name: 'cpf', type: 'string', required: false },
          { name: 'dataNascimento', type: 'date', required: true },
          { name: 'filiacao', type: 'string', required: false },
          { name: 'naturalidade', type: 'string', required: false },
        ],
        isActive: true,
      },
    },
  }),
});

const { data: template } = await templateResponse.json();

// 3. Executar extração
const extractionResponse = await fetch('https://data-extraction.stg.catalisa.app/api/v1/data-extraction/extractions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'extraction',
      attributes: {
        fileId: 'file-storage-uuid', // ID do arquivo no File Storage
        templateId: template.id,
        businessId: 'loan-application-123',
        metadata: {
          applicantId: 'applicant-456',
        },
      },
    },
  }),
});

const { data: extraction } = await extractionResponse.json();
console.log(`Extração criada: ${extraction.id}`);
console.log(`Status: ${extraction.attributes.status}`);

// 4. Aguardar processamento e obter resultado
// (o status muda de PENDING → PROCESSING → COMPLETED)

const resultResponse = await fetch(`https://data-extraction.stg.catalisa.app/api/v1/data-extraction/extractions/${extraction.id}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data: result } = await resultResponse.json();

if (result.attributes.status === 'COMPLETED') {
  console.log('Dados extraídos:', result.attributes.rawData);
  console.log('Dados mapeados:', result.attributes.mappedData);
  console.log('Confiança:', result.attributes.confidenceScores);
  console.log(`Tempo de processamento: ${result.attributes.processingTimeMs}ms`);
  console.log(`Tokens utilizados: ${result.attributes.tokensUsed}`);
}

Integração com File Storage

O Data Extraction se integra com o File Storage para obter os documentos a serem processados:

// 1. Upload do documento no File Storage
const uploadResponse = await fetch('https://storage.stg.catalisa.app/api/v1/files', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'file',
      attributes: {
        name: 'documento-rg.jpg',
        contentType: 'image/jpeg',
        content: base64Content,
      },
    },
  }),
});

const { data: file } = await uploadResponse.json();

// 2. Usar o fileId na extração
const extractionResponse = await fetch('https://data-extraction.stg.catalisa.app/api/v1/data-extraction/extractions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'extraction',
      attributes: {
        fileId: file.id,
        templateId: 'template-uuid',
      },
    },
  }),
});

Boas Práticas

Qualidade da Imagem

Resolução mínima recomendada: 300 DPI
Formatos suportados: JPEG, PNG, PDF
Evite imagens borradas, cortadas ou com baixo contraste

Templates

Crie templates específicos para cada tipo de documento
Use descrições claras nos campos esperados
Defina campos obrigatórios vs opcionais adequadamente

Mapeamentos

Use transformações para normalizar dados (datas, moedas)
Configure valores padrão para campos opcionais
Defina prioridade para mapeamentos conflitantes

Confiança

Scores acima de 0.9: Alta confiança, uso automático
Scores entre 0.7-0.9: Média confiança, revisar se crítico
Scores abaixo de 0.7: Baixa confiança, revisão manual recomendada

Visão Geral​

Base URL​

Recursos​

Permissões​

Provedores Suportados​

Status da Extração​

Tipos de Transformação​

Fluxo de Extração​

Etapas​

Eventos​

Payload dos Eventos​

Exemplo Rápido​

Integração com File Storage​

Boas Práticas​

Qualidade da Imagem​

Templates​

Mapeamentos​

Confiança​