Ejecutar extracción

POST /v1/extractions/run

Ejecuta una extracción en un documento PDF. El documento se procesa utilizando la plantilla especificada, y los datos extraídos se devuelven como JSON estructurado que coincide con las definiciones de campos de la plantilla.

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í
`Content-Type`	`application/json`	Sí

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`async`	`string`	No	Establece a `"true"` para devolver inmediatamente con un estado `processing` en lugar de esperar a que se complete. El comportamiento predeterminado (omitido o `"false"`) es sincrónico.

Cuerpo

Campo	Tipo	Requerido	Descripción
`templateId`	`string`	Sí	El ID de la plantilla de extracción a utilizar.
`fileName`	`string`	Sí	Nombre original del archivo del documento.
`pdfBase64`	`string`	Sí	Contenido del archivo PDF codificado en base64.
`mimeType`	`string`	Sí	Tipo MIME del archivo. Valores aceptados: `application/pdf`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`.
`runId`	`string`	No	Identificador opcional para agrupar extracciones relacionadas en una ejecución por lotes.

Ejemplos de código

curlTypeScriptPython

bash

curl -X POST https://api.docmap.io/v1/extractions/run \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "fileName": "invoice-2024-001.pdf",
    "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YW...",
    "mimeType": "application/pdf"
  }'

typescript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch('https://api.docmap.io/v1/extractions/run', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 'tmpl_8f3a2b1c4d5e6f7g',
    fileName: 'invoice-2024-001.pdf',
    pdfBase64: pdfBuffer.toString('base64'),
    mimeType: 'application/pdf',
  }),
})

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

python

import requests
import base64

api_key = "dm_live_abc123def456ghi789jkl012mno345"

with open("invoice-2024-001.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://api.docmap.io/v1/extractions/run",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "templateId": "tmpl_8f3a2b1c4d5e6f7g",
        "fileName": "invoice-2024-001.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

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

Respuesta

Estado: 200 OK

El cuerpo de la respuesta está envuelto en un objeto data.

Campos

Campo	Tipo	Descripción
`id`	`string`	ID único de extracción (con prefijo `extract_`).
`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. `"processing"` cuando se usa el modo asíncrono, `"completed"` en caso de éxito, `"failed"` en caso de error.
`extractedData`	`object` \| `null`	Datos extraídos que coinciden con los campos de la plantilla. `null` si la extracción falló.
`error`	`string` \| `null`	Mensaje de error que describe la falla. `null` si la extracción fue exitosa.
`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ó en la solicitud.
`processingTimeMs`	`number` \| `null`	Duración total del procesamiento en milisegundos.
`createdAt`	`string`	Marca de tiempo ISO 8601 de cuándo se creó la extracción.

Ejemplo

json

{
  "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",
      "invoice_date": "2024-11-15",
      "total_amount": 1250.00,
      "currency": "USD",
      "line_items": [
        {
          "description": "Widget A",
          "quantity": 10,
          "unit_price": 125.00
        }
      ]
    },
    "error": null,
    "variables": [
      {
        "name": "vendor_name",
        "type": "string",
        "description": "Name of the vendor or supplier"
      },
      {
        "name": "total_amount",
        "type": "number",
        "description": "Total invoice amount"
      }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": 3842,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

Modo asíncrono

Por defecto, la API espera a que la extracción finalice antes de responder (sincrónico). Para extracciones de larga duración, puedes usar el modo asíncrono para obtener una respuesta inmediata y consultar el resultado posteriormente.

Añade ?async=true a la URL para activar el modo asíncrono:

bash

curl -X POST "https://api.docmap.io/v1/extractions/run?async=true" \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "fileName": "invoice-2024-001.pdf",
    "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YW...",
    "mimeType": "application/pdf"
  }'

Respuesta: 202 Accepted

La respuesta tiene la misma estructura que una respuesta sincrónica, pero status será "processing", extractedData será null y processingTimeMs será null:

json

{
  "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": [...],
    "source": "api",
    "runId": null,
    "processingTimeMs": null,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

Usa el id devuelto para consultar el endpoint Obtener extracción hasta que status cambie a "completed" o "failed".

WARNING

Si una extracción permanece en estado "processing" durante más de 2 minutos, trátala como fallida. No hay un timeout automático -- en casos raros (por ejemplo, reinicio del servidor), un registro puede permanecer en "processing" indefinidamente.

Errores

Estado	Código	Descripción
`401`	`UNAUTHORIZED`	Clave API / token faltante, inválido o expirado.
`404`	`NOT_FOUND`	La plantilla especificada no se encontró o no pertenece a tu cuenta.
`429`	`USAGE_LIMIT_EXCEEDED`	Has alcanzado el límite mensual de extracciones de tu plan.
`500`	`INTERNAL_ERROR`	Ocurrió un error inesperado durante el procesamiento de la extracción.

Ejecutar extracción ​

Solicitud ​

Encabezados ​

Parámetros de consulta ​

Cuerpo ​

Ejemplos de código ​

Respuesta ​

Campos ​

Ejemplo ​

Modo asíncrono ​

Errores ​