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 y obtenga el resultado de la extracción en una sola petición. El servidor procesa el documento y devuelve el resultado directamente. Si el procesamiento tarda más que el tiempo de espera del servidor, recibirá una respuesta 202 con un ID de extracción para realizar el sondeo.
/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, WebP, TIFF) |
| schema_id | String | No | ID del esquema para controlar qué campos se extraen |
Ejemplo
curl -X POST https://api-parse.conversiontools.io/v1/extract \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@invoice.pdf"Respuesta (200)
{
"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 - el procesamiento tarda más)
Si el documento tarda más en procesarse, el servidor devuelve un 202 con un ID de extracción. Sondee GET /v1/extractions/:id para obtener el resultado.
{
"success": true,
"id": "ext_789...",
"status": "processing"
}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, WebP, TIFF) |
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 |
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..."}'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
}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
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
}429 Rate Limited
{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "Monthly page limit exceeded",
"limit": 100,
"used": 100
}
}