Referencia de la API
Parse ofrece dos formas de extraer datos de los documentos: un método síncrono de una sola llamada y un método asíncrono de tres pasos.
Todos los endpoints requieren un token Bearer en el header Authorization. Consulte Autenticación para saber cómo crear y usar su clave de API.
URL base: https://api-parse.conversiontools.io
Método 1: Llamada única (síncrono)
Suba un archivo e inicie la extracción en una sola petición. Por defecto, la llamada devuelve inmediatamente una respuesta 202 con un ID de extracción: sondee el resultado o use un webhook. Pase wait para mantener la petición abierta y recibir documentos pequeños directamente.
/v1/extract
Headers
| Header | Valor |
|---|---|
| Authorization | Bearer YOUR_API_KEY |
| Content-Type | multipart/form-data |
Parámetros (form-data)
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| file | File | Sí | El documento del que extraer datos (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF) |
| schema_id | String | No | ID del esquema para controlar qué campos se extraen |
| wait | Number | No | Segundos que la petición se mantiene abierta para devolver el resultado directamente si termina a tiempo (0 = devolver inmediatamente - el valor por defecto; máximo 120) |
| webhook_url | String | No | URL http(s) pública que se notifica cuando la extracción termina, para que no tenga que sondear |
| no_cache | Boolean | No | Póngalo a 1 para forzar una extracción nueva en lugar de reutilizar un resultado guardado de un documento idéntico |
Ejemplo
curl -X POST https://api-parse.conversiontools.io/v1/extract \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@invoice.pdf" \
-F "wait=60"Respuesta (200 - con wait, cuando el documento termina a tiempo)
{
"success": true,
"id": "ext_789...",
"filename": "invoice.pdf",
"status": "completed",
"data": {
"vendor_name": "Acme Corp",
"invoice_number": "INV-2024-001",
"date": "2024-01-15",
"total": 1650.00
},
"pages_used": 1
}Respuesta (202 - por defecto)
Por defecto, y siempre que el documento tarde más que la ventana de espera, el servidor devuelve un 202 con un ID de extracción. Sondee GET /v1/extractions/:id hasta que status sea completed o failed: bifurque siempre según status, nunca según el tiempo. O pase una URL de webhook para no tener que sondear.
{
"success": true,
"id": "ext_789...",
"status": "processing"
}# Poll until the extraction reaches a terminal status
while true; do
RESULT=$(curl -s https://api-parse.conversiontools.io/v1/extractions/EXTRACTION_ID \
-H "Authorization: Bearer YOUR_API_KEY")
STATUS=$(echo "$RESULT" | grep -o '"status": *"[a-z]*"')
case "$STATUS" in
*completed*|*failed*) break ;;
esac
sleep 2
done
echo "$RESULT"Método 2: Subida + Extracción (asíncrono)
Un flujo de tres pasos: suba primero el archivo, luego inicie una extracción y después sondee el resultado. Este método le da más control - puede reutilizar el mismo archivo subido para varias extracciones con esquemas diferentes.
/v1/upload
Suba un documento y reciba un file_id para la extracción.
Parámetros (form-data)
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| file | File | Sí | El documento que se va a subir (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF) |
Ejemplo
curl -X POST https://api-parse.conversiontools.io/v1/upload \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@invoice.pdf"Respuesta
{
"success": true,
"file_id": "abc123...",
"filename": "invoice.pdf",
"size": 52480
}/v1/extract
Inicie una extracción sobre un archivo subido usando su file_id. Si lo desea, indique un schema_id para controlar qué campos se extraen.
Headers
| Header | Valor |
|---|---|
| Authorization | Bearer YOUR_API_KEY |
| Content-Type | application/json |
Parámetros (cuerpo JSON)
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| file_id | String | Sí | El ID del archivo devuelto por el endpoint de subida |
| schema_id | String | No | ID del esquema para controlar qué campos se extraen |
| webhook_url | String | No | URL http(s) pública que se notifica cuando la extracción termina, para que no tenga que sondear |
| no_cache | Boolean | No | Póngalo a true para forzar una extracción nueva en lugar de reutilizar un resultado guardado de un documento idéntico |
Ejemplo
curl -X POST https://api-parse.conversiontools.io/v1/extract \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"file_id": "abc123...", "schema_id": "sch_456...", "webhook_url": "https://example.com/hooks/parse"}'Respuesta
{
"success": true,
"id": "ext_789...",
"status": "processing"
}/v1/extractions/:id
Recupere el resultado de una extracción. Sondee este endpoint hasta que status sea completed.
Ejemplo
curl https://api-parse.conversiontools.io/v1/extractions/ext_789... \
-H "Authorization: Bearer YOUR_API_KEY"Respuesta
{
"success": true,
"id": "ext_789...",
"filename": "invoice.pdf",
"status": "completed",
"data": {
"vendor_name": "Acme Corp",
"invoice_number": "INV-2024-001",
"date": "2024-01-15",
"items": [
{
"description": "Consulting Services",
"quantity": 10,
"unit_price": 150.00,
"amount": 1500.00
}
],
"subtotal": 1500.00,
"tax": 150.00,
"total": 1650.00,
"currency": "USD"
},
"pages_used": 1
}Webhooks
Pase una webhook_url y Parse enviará un POST a esa dirección en cuanto la extracción termine o falle, así nunca tendrá que sondear. La notificación contiene solo el ID de la extracción y el estado, nunca los datos extraídos; recupere el resultado a través de la API. La URL debe ser una dirección http o https pública; las direcciones privadas e internas se rechazan. La entrega se reintenta varias veces y nunca afecta a la extracción en sí.
Contenido de la notificación
{
"event": "extraction.completed",
"id": "ext_789...",
"status": "completed",
"pages_used": 2,
"error": null,
"created_at": "2026-07-26T10:00:00.000Z",
"completed_at": "2026-07-26T10:00:41.000Z"
}Extracciones repetidas
Si envía de nuevo el mismo documento con el mismo esquema, Parse devuelve inmediatamente el resultado guardado, sin contar contra sus páginas. Esas respuestas incluyen "cached": true. Si edita el esquema o pasa no_cache, se ejecuta una extracción nueva.
Exportar a CSV / Excel
Convierta el resultado de una extracción completada en una hoja de cálculo. Las exportaciones son gratuitas, repetibles y no consumen páginas. Los arrays anidados se desnormalizan: los campos de cabecera se repiten en cada fila, así que la salida está lista para tablas dinámicas e importaciones. Consejo: pase output_format (csv o xlsx) en la petición de extracción y la exportación se inicia automáticamente en cuanto la extracción se completa.
/v1/extractions/:id/export
Inicie la exportación. Idempotente por formato: las llamadas repetidas devuelven la conversión en curso o el estado del archivo terminado.
Ejemplo
curl -X POST https://api-parse.conversiontools.io/v1/extractions/ext_789.../export \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"format": "xlsx"}'Respuesta
{
"success": true,
"status": "processing",
"format": "xlsx",
"progress": 0
}/v1/extractions/:id/export?format=xlsx
Sondee la exportación. Mientras se convierte, la respuesta es JSON con status: "processing" y un porcentaje progress. Cuando esté listo, el cuerpo de la respuesta es el propio archivo (con Content-Disposition: attachment).
Ejemplo
curl -L -o invoice.xlsx \
"https://api-parse.conversiontools.io/v1/extractions/ext_789.../export?format=xlsx" \
-H "Authorization: Bearer YOUR_API_KEY"/v1/extractions/:id
Elimine una extracción y todos sus datos almacenados (el resultado y cualquier archivo de exportación). Los documentos de origen siempre se eliminan automáticamente en un plazo de 24 horas tras el procesamiento; los resultados extraídos se conservan hasta que los elimine - a través de este endpoint o desde el panel.
Ejemplo
curl -X DELETE https://api-parse.conversiontools.io/v1/extractions/ext_789... \
-H "Authorization: Bearer YOUR_API_KEY"Respuestas de error
401 Unauthorized
{
"error": "Invalid API key",
"param": "authorization"
}429 Rate Limited
{
"error": "Monthly page limit exceeded",
"code": "LIMIT_REACHED",
"message": "You've reached your monthly page limit (100 pages).",
"remedy": { "text": "View plans and upgrade", "path": "/pricing" }
}