Listar extracciones

GET /v1/extractions

Lista los registros de extracción del usuario autenticado. Los resultados se devuelven en orden cronológico inverso (los más recientes primero). Soporta paginación basada en cursor y filtrado por plantilla, ejecución por lotes o rango de fechas.

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 consulta

Parámetro	Tipo	Requerido	Descripción
`templateId`	`string`	No	Filtrar resultados a extracciones de una plantilla específica.
`runId`	`string`	No	Filtrar resultados a extracciones de una ejecución por lotes específica. Devuelve todos los resultados coincidentes (ignora `limit`/`cursor`).
`limit`	`number`	No	Número máximo de resultados a devolver. Predeterminado: `50`, máximo: `100`.
`cursor`	`string`	No	Cursor de paginación. Pasa el valor `createdAt` del último elemento de la página anterior para obtener la siguiente página.
`dateFrom`	`string`	No	Filtrar extracciones creadas en o después de esta fecha (`YYYY-MM-DD`).
`dateTo`	`string`	No	Filtrar extracciones creadas en o antes de esta fecha (`YYYY-MM-DD`).

Paginación

La respuesta incluye un booleano hasMore. Cuando es true, pasa el valor createdAt del último elemento como parámetro cursor para obtener la siguiente página.

Al filtrar por runId, todas las extracciones coincidentes se devuelven en una sola respuesta (no se necesita paginación ya que las ejecuciones por lotes suelen ser pequeñas).

Ejemplos de código

curlTypeScriptPython

bash

# List all extractions (default limit of 50)
curl https://api.docmap.io/v1/extractions \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

# Filter by template and limit results
curl "https://api.docmap.io/v1/extractions?templateId=48291&limit=10" \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

# Filter by batch run ID
curl "https://api.docmap.io/v1/extractions?runId=b4704c6e-8917-4671-8c92-178aec3eba92" \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

# Filter by date range
curl "https://api.docmap.io/v1/extractions?dateFrom=2025-01-01&dateTo=2025-01-31" \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

# Paginate through results
curl "https://api.docmap.io/v1/extractions?limit=10&cursor=2025-01-15T09:30:00.000Z" \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

typescript

const apiKey = process.env.DOCMAP_API_KEY

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

const { data, hasMore } = await response.json()
console.log(`Found ${data.length} extractions, hasMore: ${hasMore}`)

// Paginate through all results
let cursor: string | undefined
const allExtractions = []

do {
  const url = new URL('https://api.docmap.io/v1/extractions')
  url.searchParams.set('limit', '50')
  if (cursor) url.searchParams.set('cursor', cursor)

  const res = await fetch(url, {
    headers: { 'Authorization': `Bearer ${apiKey}` },
  })
  const page = await res.json()

  allExtractions.push(...page.data)
  cursor = page.hasMore ? page.data.at(-1)?.createdAt : undefined
} while (cursor)

console.log(`Total: ${allExtractions.length} extractions`)

// Filter by template
const filtered = await fetch(
  'https://api.docmap.io/v1/extractions?templateId=48291&limit=10',
  { headers: { 'Authorization': `Bearer ${apiKey}` } },
)

const { data: filteredData } = await filtered.json()

python

import requests

api_key = "dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"
headers = {"Authorization": f"Bearer {api_key}"}

# List all extractions
response = requests.get(
    "https://api.docmap.io/v1/extractions",
    headers=headers,
)
result = response.json()
print(f"Found {len(result['data'])} extractions, hasMore: {result['hasMore']}")

# Paginate through all results
all_extractions = []
cursor = None

while True:
    params = {"limit": 50}
    if cursor:
        params["cursor"] = cursor

    response = requests.get(
        "https://api.docmap.io/v1/extractions",
        headers=headers,
        params=params,
    )
    page = response.json()

    all_extractions.extend(page["data"])

    if not page["hasMore"]:
        break
    cursor = page["data"][-1]["createdAt"]

print(f"Total: {len(all_extractions)} extractions")

# Filter by date range
response = requests.get(
    "https://api.docmap.io/v1/extractions",
    headers=headers,
    params={"dateFrom": "2025-01-01", "dateTo": "2025-01-31"},
)

Respuesta

Estado: 200 OK

El cuerpo de la respuesta contiene un array data de registros de extracción y un booleano hasMore que indica si existen páginas adicionales.

Campos de nivel superior

Campo	Tipo	Descripción
`data`	`ExtractionRecord[]`	Array de registros de extracción.
`hasMore`	`boolean`	`true` si hay más resultados más allá de la página actual. `false` al filtrar por `runId` (todos los resultados se devuelven).

Campos del registro de extracción

Cada registro de extracción en el array contiene los mismos campos que la respuesta de Ejecutar extracción:

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"` si aún se está procesando, `"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ó.
`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-KmL9nOpQrStUvWxYz",
      "userId": "L5kM9nRpQ7vX3yZ1wD4eF6gHjA2",
      "templateId": "48291",
      "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": "2025-01-20T14:30:00.000Z"
    },
    {
      "id": "extract-Rj4Y8mBpCdEfGhIk",
      "userId": "L5kM9nRpQ7vX3yZ1wD4eF6gHjA2",
      "templateId": "48291",
      "templateName": "Invoice Template",
      "fileName": "invoice-2024-002.pdf",
      "status": "completed",
      "extractedData": {
        "vendor_name": "Global Supplies Ltd",
        "invoice_number": "INV-2024-002",
        "total_amount": 875.50
      },
      "error": null,
      "variables": [
        {
          "name": "vendor_name",
          "type": "string",
          "description": "Name of the vendor or supplier"
        }
      ],
      "source": "dashboard",
      "runId": null,
      "processingTimeMs": 2916,
      "createdAt": "2025-01-19T09:15:00.000Z"
    }
  ],
  "hasMore": true
}

Errores

Estado	Código	Descripción
`401`	`UNAUTHORIZED`	Clave API / token faltante, inválido o expirado.

Listar extracciones ​

Solicitud ​

Encabezados ​

Parámetros de consulta ​

Ejemplos de código ​

Respuesta ​

Campos de nivel superior ​

Campos del registro de extracción ​

Ejemplo ​

Errores ​