Extrações

Endpoints para executar extrações, listar histórico e acompanhar o progresso.

Extrações são o resultado da execução de um agente sobre um documento. O processo é assíncrono -- a extração é enfileirada e processada em background.

Todos os endpoints exigem autenticação e uma organização ativa.

Executar Extração

Envia um documento para ser processado por um agente. Retorna imediatamente com um código de rastreamento.

POST /agents/:code/execute
Content-Type: application/json

Parâmetros de Rota

Parâmetro	Tipo	Descrição
`code`	`string`	Código do agente (10 caracteres, gerado na criação)

Exemplo:

POST /agents/aB3cD4eF5g/execute

Body

Campo	Tipo	Obrigatório	Descrição
`content`	`string`	Sim	Conteúdo do arquivo em Base64
`mimeType`	`string`	Sim	Tipo MIME do arquivo
`fileName`	`string`	Não	Nome original do arquivo

Exemplo

{
  "content": "JVBERi0xLjQKJcOkw7zD...",
  "mimeType": "application/pdf",
  "fileName": "nota-fiscal-001.pdf"
}

Resposta `202`

{
  "trackingCode": "aB3cD4eF5gH7",
  "extractionId": "uuid-da-extracao",
  "status": "pending",
  "message": "Extração enfileirada com sucesso. Use o código de rastreamento para acompanhar o progresso."
}

Erros

Status	Descrição
`400`	Agente desativado ou sem campos configurados
`404`	Agente não encontrado
`500`	Falha ao enfileirar a extração

Validações

O agente deve estar ativo (isActive: true)
O agente deve ter pelo menos um campo configurado

Acompanhar Extração (Polling)

Verifica o status de uma extração usando o código de rastreamento. O frontend faz polling a cada 2 segundos neste endpoint.

GET /extractions/track/:trackingCode

Parâmetros de Rota

Parâmetro	Tipo	Descrição
`trackingCode`	`string`	Código de rastreamento retornado na execução

Resposta `200` (Pendente/Processando)

{
  "extraction": {
    "id": "uuid-da-extracao",
    "agentId": "uuid-do-agente",
    "userId": "uuid-do-usuario",
    "trackingCode": "aB3cD4eF5gH7",
    "inputFileName": "nota-fiscal-001.pdf",
    "inputType": "application/pdf",
    "resultJson": null,
    "confidenceJson": null,
    "status": "processing",
    "errorMessage": null,
    "totalTokens": null,
    "inputTokens": null,
    "outputTokens": null,
    "createdAt": "2025-01-15T10:00:00.000Z",
    "agent": { ... }
  },
  "data": null,
  "confidence": null
}

Resposta `200` (Concluída)

{
  "extraction": {
    "id": "uuid-da-extracao",
    "status": "success",
    "totalTokens": 1250,
    "inputTokens": 800,
    "outputTokens": 450,
    ...
  },
  "data": {
    "numero_nf": "NF-e 001234",
    "valor_total": 1530.50,
    "data_emissao": "2025-01-15",
    "cnpj_emitente": "12.345.678/0001-90"
  },
  "confidence": {
    "numero_nf": 0.95,
    "valor_total": 0.92,
    "data_emissao": 0.88,
    "cnpj_emitente": 0.90
  }
}

Resposta `200` (Erro)

{
  "extraction": {
    "status": "error",
    "errorMessage": "Falha ao processar o documento",
    ...
  },
  "data": null,
  "confidence": null
}

Listar Extrações

Retorna as últimas 100 extrações do usuário na organização ativa.

GET /extractions

Resposta `200`

{
  "extractions": [
    {
      "id": "uuid-da-extracao",
      "agentId": "uuid-do-agente",
      "userId": "uuid-do-usuario",
      "trackingCode": "aB3cD4eF5gH7",
      "inputFileName": "nota-fiscal-001.pdf",
      "inputType": "application/pdf",
      "resultJson": "{...}",
      "confidenceJson": "{...}",
      "status": "success",
      "errorMessage": null,
      "totalTokens": 1250,
      "inputTokens": 800,
      "outputTokens": 450,
      "createdAt": "2025-01-15T10:00:00.000Z",
      "agent": {
        "id": "uuid-do-agente",
        "name": "Extrator de Notas Fiscais",
        ...
      }
    }
  ]
}

Obter Extração por ID

Retorna uma extração específica pelo UUID.

GET /extractions/:id

Parâmetros de Rota

Parâmetro	Tipo	Descrição
`id`	`string`	UUID da extração

Resposta `200`

{
  "extraction": {
    "id": "uuid-da-extracao",
    "agentId": "uuid-do-agente",
    "userId": "uuid-do-usuario",
    "trackingCode": "aB3cD4eF5gH7",
    "inputFileName": "nota-fiscal-001.pdf",
    "inputType": "application/pdf",
    "resultJson": "{\"numero_nf\":\"NF-e 001234\"}",
    "confidenceJson": "{\"numero_nf\":0.95}",
    "status": "success",
    "errorMessage": null,
    "totalTokens": 1250,
    "inputTokens": 800,
    "outputTokens": 450,
    "createdAt": "2025-01-15T10:00:00.000Z",
    "agent": { ... }
  }
}

Resposta `404`

{
  "error": "Extração não encontrada"
}

Status de Extração

Status	Descrição
`pending`	Extração enfileirada, aguardando processamento
`processing`	Documento sendo analisado pela IA
`success`	Extração concluída com sucesso
`error`	Ocorreu um erro durante a extração

Dados de Confiança

Cada campo extraído possui uma pontuação de confiança entre 0 e 1:

Faixa	Significado
`0.90 - 1.00`	Alta confiança
`0.70 - 0.89`	Média confiança
`0.00 - 0.69`	Baixa confiança - requer revisão manual

Extrações

On this page