Extractions

Execute e gerencie extrações de dados de documentos.

Endpoints

Método	Endpoint	Descrição
POST	/api/v1/data-extraction/extractions	Criar extração
GET	/api/v1/data-extraction/extractions	Listar extrações
GET	/api/v1/data-extraction/extractions/:id	Obter extração
POST	/api/v1/data-extraction/extractions/:id/retry	Reprocessar extração

Criar Extração

POST https://data-extraction.stg.catalisa.app/api/v1/data-extraction/extractions
Authorization: Bearer {token}
Content-Type: application/json

Request Body

{
  "data": {
    "type": "extraction",
    "attributes": {
      "fileId": "550e8400-e29b-41d4-a716-446655440000",
      "configId": "550e8400-e29b-41d4-a716-446655440001",
      "templateId": "550e8400-e29b-41d4-a716-446655440002",
      "businessId": "loan-application-123",
      "metadata": {
        "applicantId": "applicant-456",
        "step": "document-verification"
      }
    }
  }
}

Atributos

Campo	Tipo	Obrigatório	Descrição
fileId	string	Sim	ID do arquivo no File Storage
configId	string	Não	ID da configuração do provedor (usa default se omitido)
templateId	string	Não	ID do template de extração
businessId	string	Não	ID de negócio para correlação
metadata	object	Não	Metadados customizados

Response (201 Created)

{
  "data": {
    "type": "extraction",
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "links": {
      "self": "/api/v1/data-extraction/extractions/550e8400-e29b-41d4-a716-446655440003"
    },
    "attributes": {
      "status": "PENDING",
      "fileId": "550e8400-e29b-41d4-a716-446655440000",
      "configId": "550e8400-e29b-41d4-a716-446655440001",
      "templateId": "550e8400-e29b-41d4-a716-446655440002",
      "businessId": "loan-application-123",
      "metadata": {
        "applicantId": "applicant-456",
        "step": "document-verification"
      },
      "retryCount": 0,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

Ciclo de Vida da Extração

PENDING → PROCESSING → COMPLETED
                    ↘ FAILED → (retry) → PROCESSING

Status

Status	Descrição
PENDING	Criada, aguardando processamento
PROCESSING	Sendo processada pelo provedor de IA
COMPLETED	Concluída com sucesso
FAILED	Falhou (pode ser reprocessada)

Obter Extração

GET https://data-extraction.stg.catalisa.app/api/v1/data-extraction/extractions/:id
Authorization: Bearer {token}

Response (200 OK) - Concluída

{
  "data": {
    "type": "extraction",
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "attributes": {
      "status": "COMPLETED",
      "fileId": "550e8400-e29b-41d4-a716-446655440000",
      "configId": "550e8400-e29b-41d4-a716-446655440001",
      "templateId": "550e8400-e29b-41d4-a716-446655440002",
      "rawData": {
        "nome": "JOÃO DA SILVA",
        "rg": "12.345.678-9",
        "cpf": "123.456.789-00",
        "dataNascimento": "15/01/1990",
        "filiacao": "MARIA DA SILVA",
        "naturalidade": "SÃO PAULO - SP"
      },
      "mappedData": {
        "fullName": "JOÃO DA SILVA",
        "documentNumber": "12345678900",
        "birthDate": "1990-01-15"
      },
      "confidenceScores": {
        "nome": 0.98,
        "rg": 0.95,
        "cpf": 0.97,
        "dataNascimento": 0.92,
        "filiacao": 0.85,
        "naturalidade": 0.88
      },
      "processingTimeMs": 2340,
      "providerModel": "gpt-4o",
      "tokensUsed": 1250,
      "businessId": "loan-application-123",
      "retryCount": 0,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:05Z",
      "completedAt": "2024-01-15T10:30:05Z"
    }
  }
}

Response (200 OK) - Falha

{
  "data": {
    "type": "extraction",
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "attributes": {
      "status": "FAILED",
      "fileId": "550e8400-e29b-41d4-a716-446655440000",
      "errorMessage": "Unable to extract data: image quality too low",
      "retryCount": 1,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:10Z"
    }
  }
}

Listar Extrações

GET https://data-extraction.stg.catalisa.app/api/v1/data-extraction/extractions
Authorization: Bearer {token}

Query Parameters

Parâmetro	Tipo	Descrição
page[number]	integer	Número da página
page[size]	integer	Itens por página
filter[status]	enum	Filtrar por status
filter[businessId]	string	Filtrar por ID de negócio
filter[templateId]	string	Filtrar por template

Exemplo

GET https://data-extraction.stg.catalisa.app/api/v1/data-extraction/extractions?filter[status]=COMPLETED&filter[businessId]=loan-123

Response (200 OK)

{
  "links": {
    "self": "/api/v1/data-extraction/extractions?page[number]=1&page[size]=20"
  },
  "meta": {
    "totalItems": 50,
    "totalPages": 3,
    "currentPage": 1,
    "pageSize": 20
  },
  "data": [
    {
      "type": "extraction",
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "attributes": {
        "status": "COMPLETED",
        "fileId": "...",
        "businessId": "loan-123",
        "processingTimeMs": 2340,
        "createdAt": "2024-01-15T10:30:00Z",
        "completedAt": "2024-01-15T10:30:05Z"
      }
    }
  ]
}

Reprocessar Extração

Permite reprocessar uma extração que falhou.

POST https://data-extraction.stg.catalisa.app/api/v1/data-extraction/extractions/:id/retry
Authorization: Bearer {token}

Request Body (opcional)

{
  "data": {
    "type": "extraction-retry",
    "attributes": {
      "configId": "new-config-uuid"
    }
  }
}

Response (200 OK)

{
  "data": {
    "type": "extraction",
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "attributes": {
      "status": "PENDING",
      "retryCount": 2,
      "updatedAt": "2024-01-15T10:35:00Z"
    }
  }
}

Limite de Retries

Por padrão, uma extração pode ser reprocessada até 3 vezes. Após isso, é necessário criar uma nova extração.

Polling vs Webhooks

Polling

Para casos simples, você pode fazer polling do status:

async function waitForExtraction(extractionId, token, maxAttempts = 30) {
  const baseUrl = 'https://data-extraction.stg.catalisa.app';

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(`${baseUrl}/api/v1/data-extraction/extractions/${extractionId}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    });

    const { data } = await response.json();

    if (data.attributes.status === 'COMPLETED') {
      return data;
    }

    if (data.attributes.status === 'FAILED') {
      throw new Error(data.attributes.errorMessage);
    }

    // Aguarda 1 segundo antes da próxima tentativa
    await new Promise(resolve => setTimeout(resolve, 1000));
  }

  throw new Error('Timeout waiting for extraction');
}

Webhooks

Para produção, recomendamos usar o Webhooks Engine:

// Configurar webhook subscription
await fetch('https://webhooks.stg.catalisa.app/api/v1/webhooks/subscriptions', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    data: {
      type: 'webhook-subscription',
      attributes: {
        url: 'https://seu-servidor.com/webhooks/data-extraction',
        events: [
          'data-extraction.extraction.completed',
          'data-extraction.extraction.failed'
        ]
      }
    }
  })
});

// Seu endpoint receberá:
// POST /webhooks/data-extraction
// {
//   "event": "data-extraction.extraction.completed",
//   "data": {
//     "organizationId": "...",
//     "extractionId": "...",
//     "status": "COMPLETED",
//     "fileId": "...",
//     "businessId": "loan-application-123"
//   }
// }

Interpretando Confidence Scores

Os scores de confiança indicam a certeza do modelo sobre cada campo extraído:

Score	Interpretação	Ação Recomendada
0.95+	Muito alta	Uso automático
0.85-0.94	Alta	Uso automático, log para auditoria
0.70-0.84	Média	Revisão recomendada para campos críticos
0.50-0.69	Baixa	Revisão manual necessária
< 0.50	Muito baixa	Considerar reprocessar ou rejeitar

function shouldReview(extraction) {
  const criticalFields = ['cpf', 'rg', 'dataNascimento'];
  const scores = extraction.attributes.confidenceScores;

  for (const field of criticalFields) {
    if (scores[field] && scores[field] < 0.85) {
      return true;
    }
  }

  return false;
}

Erros Comuns

Código	Erro	Descrição
400	VALIDATION_ERROR	Dados inválidos no request
404	NOT_FOUND	Extração, arquivo ou configuração não encontrada
409	CONFLICT	Extração já está sendo processada
422	UNPROCESSABLE_ENTITY	Arquivo não suportado ou corrompido
503	SERVICE_UNAVAILABLE	Provedor de IA indisponível