Obtener extracción

GET /v1/extractions/{id}

Recupera un registro de extracción individual por ID. Este endpoint se utiliza principalmente para consultar el resultado de una extracción asíncrona.

Pruébalo

Prueba este endpoint de forma interactiva en la Swagger UI.

Autorización requerida

Incluye tu clave API en el encabezado Authorization.

Solicitud

Encabezados

Encabezado	Valor	Requerido
Authorization	Bearer <token>	Sí

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
id	string	Sí	El ID de extracción devuelto por el endpoint Ejecutar extracción.

Ejemplos de código

curl

curl https://api.docmap.io/v1/extractions/extract_9k2m4n6p8q0r1s3t \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345"

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch(
  'https://api.docmap.io/v1/extractions/extract_9k2m4n6p8q0r1s3t',
  { headers: { 'Authorization': `Bearer ${apiKey}` } },
)

const { data } = await response.json()
console.log(data.status, data.extractedData)

Python

import requests

api_key = "dm_live_abc123def456ghi789jkl012mno345"

response = requests.get(
    "https://api.docmap.io/v1/extractions/extract_9k2m4n6p8q0r1s3t",
    headers={"Authorization": f"Bearer {api_key}"},
)

data = response.json()["data"]
print(data["status"], data["extractedData"])

Respuesta

Estado: 200 OK

El cuerpo de la respuesta está envuelto en un objeto data que contiene un solo registro de extracción.

Campos

Cada campo es el mismo que en la respuesta de Ejecutar extracción.

Campo	Tipo	Descripción
id	string	ID único de extracción.
userId	string	ID del usuario propietario de esta extracción.
templateId	string	ID de la plantilla utilizada para la extracción.
templateName	string	Nombre visible de la plantilla utilizada.
fileName	string	Nombre original del archivo del documento subido.
status	"processing" | "completed" | "failed"	Estado actual de la extracción.
extractedData	object | null	Datos extraídos que coinciden con los campos de la plantilla. null mientras se procesa o si falló.
error	string | null	Mensaje de error si falló. null en caso contrario.
variables	Variable[]	Array de definiciones de variables de la plantilla utilizadas durante la extracción.
source	"dashboard" | "api"	Cómo se activó la extracción.
runId	string | null	ID de ejecución por lotes, si se proporcionó.
processingTimeMs	number | null	Duración total del procesamiento en milisegundos. null mientras aún se procesa.
createdAt	string	Marca de tiempo ISO 8601 de cuándo se creó la extracción.

Ejemplo (completada)

{
  "data": {
    "id": "extract_9k2m4n6p8q0r1s3t",
    "userId": "uid_a1b2c3d4e5f6",
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "templateName": "Invoice Template",
    "fileName": "invoice-2024-001.pdf",
    "status": "completed",
    "extractedData": {
      "vendor_name": "Acme Corp",
      "invoice_number": "INV-2024-001",
      "total_amount": 1250.00
    },
    "error": null,
    "variables": [
      {
        "name": "vendor_name",
        "type": "string",
        "description": "Name of the vendor or supplier"
      }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": 3842,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

Ejemplo (en proceso)

{
  "data": {
    "id": "extract_9k2m4n6p8q0r1s3t",
    "userId": "uid_a1b2c3d4e5f6",
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "templateName": "Invoice Template",
    "fileName": "invoice-2024-001.pdf",
    "status": "processing",
    "extractedData": null,
    "error": null,
    "variables": [
      {
        "name": "vendor_name",
        "type": "string",
        "description": "Name of the vendor or supplier"
      }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": null,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

Patrón de consulta periódica

Cuando uses extracciones asíncronas, consulta este endpoint hasta que el estado ya no sea "processing":

TypeScript

async function pollExtraction(extractionId: string, apiKey: string) {
  const maxAttempts = 30
  const intervalMs = 2000

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.docmap.io/v1/extractions/${extractionId}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } },
    )

    const { data } = await response.json()

    if (data.status !== 'processing') {
      return data
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs))
  }

  throw new Error('Extraction timed out')
}

Python

import time
import requests

def poll_extraction(extraction_id: str, api_key: str):
    max_attempts = 30
    interval_s = 2

    for _ in range(max_attempts):
        response = requests.get(
            f"https://api.docmap.io/v1/extractions/{extraction_id}",
            headers={"Authorization": f"Bearer {api_key}"},
        )

        data = response.json()["data"]

        if data["status"] != "processing":
            return data

        time.sleep(interval_s)

    raise TimeoutError("Extraction timed out")

TIP

Se recomienda un intervalo de consulta de 2 segundos. La mayoría de las extracciones se completan en 5--30 segundos.

Errores

Estado	Código	Descripción
401	UNAUTHORIZED	Clave API / token faltante, inválido o expirado.
403	FORBIDDEN	La extracción pertenece a un usuario diferente.
404	NOT_FOUND	No existe ninguna extracción con el ID especificado.