Documentación API

Extracciones (API Interna)

Gestión completa de extracciones desde la interfaz web. Estos endpoints usan autenticación JWT.

GET /api/extractions/

Lista extracciones del cliente con paginación y filtros avanzados.

GET /api/extractions/

Headers

Authorization: Bearer JWT_TOKEN

Query Parameters

  • page: (opcional) Número de página. Por defecto: 1
  • per_page: (opcional) Resultados por página. Por defecto: 20
  • status: (opcional) Filtrar por estado: en_cola, procesando, completado, incompleto, error
  • habilidad_id: (opcional) Filtrar por ID de habilidad
  • search: (opcional) Buscar por nombre de archivo
  • start_date: (opcional) Fecha inicio YYYY-MM-DD
  • end_date: (opcional) Fecha fin YYYY-MM-DD

Ejemplos

curl -X GET "https://api-docmind.devol.es/api/extractions/?page=1&per_page=20&status=completado" \
  -H "Authorization: Bearer JWT_TOKEN"

Respuesta

{
  "extractions": [{"id": "uuid", "origin_name": "doc.pdf", "status": "completado", "extraction_date": "..."}],
  "pagination": {"total": 150, "page": 1, "per_page": 20, "total_pages": 8}
}

Lista paginada de extracciones con metadatos de paginación.

Errores

401Unauthorized

Token inválido.

{"msg": "Token inválido"}

GET /api/extractions/{extraction_id}

Obtiene los datos básicos de una extracción.

GET /api/extractions/{extraction_id}

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

curl -X GET https://api-docmind.devol.es/api/extractions/UUID \
  -H "Authorization: Bearer JWT_TOKEN"

Respuesta

{"id": "uuid", "origin_name": "doc.pdf", "status": "completado", "fields": [...]}

Datos de la extracción con sus campos.

Errores

404Not Found

Extracción no encontrada.

{"error": "Extracción no encontrada"}

GET /api/extractions/{extraction_id}/detailed

Obtiene la extracción con datos detallados: coordenadas OCR, texto completo y campos con word_ids.

GET /api/extractions/{extraction_id}/detailed

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

curl -X GET https://api-docmind.devol.es/api/extractions/UUID/detailed \
  -H "Authorization: Bearer JWT_TOKEN"

Respuesta

{"id": "uuid", "fields": [...], "words": {"1": [{"id": "w1", "word": "Factura", "x0": 100, "y0": 50}]}, "full_text": "...", "num_pages": 2}

Extracción con coordenadas OCR para visualizar en el visor de documentos.

Errores

404Not Found

Extracción no encontrada.

{"error": "Extracción no encontrada"}

GET /api/extractions/{extraction_id}/temporary-url

Genera una URL temporal para acceder al documento original almacenado en Azure Blob Storage.

GET /api/extractions/{extraction_id}/temporary-url

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

curl -X GET https://api-docmind.devol.es/api/extractions/UUID/temporary-url \
  -H "Authorization: Bearer JWT_TOKEN"

Respuesta

{"url": "https://storage.blob.core.windows.net/...?sv=...&se=...", "expires_in": 3600}

URL temporal con SAS token de Azure, válida por 1 hora.

Errores

404Not Found

Extracción o documento no encontrado.

{"error": "Documento no encontrado en almacenamiento"}
500Internal Server Error

Error al generar URL.

{"error": "Error al acceder al almacenamiento"}

POST /api/extractions/{habilidad_slug}/create

Crea una nueva extracción desde la interfaz web (con JWT). Acepta archivo en Base64.

POST /api/extractions/{habilidad_slug}/create

Headers

Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Body (JSON)

{
  "file_name": "documento.pdf",
  "file_base64": "BASE64_ENCODED",
  "model": "gpt-4o-mini",
  "extraction_mode": "ocr_pdf"
}
  • file_name: (obligatorio) Nombre del archivo.
  • file_base64: (obligatorio) Archivo codificado en Base64.
  • model: (opcional) Modelo de IA. Por defecto: gpt-4o-mini.
  • extraction_mode: (opcional) Modo de extracción.

Ejemplos

curl -X POST https://api-docmind.devol.es/api/extractions/factura/create \
  -H "Content-Type: application/json" -H "Authorization: Bearer JWT_TOKEN" \
  -d '{"file_name": "doc.pdf", "file_base64": "...", "model": "gpt-4o-mini"}'

Respuesta

{"extraction_id": "uuid-new", "message": "Extracción creada y en cola"}

La extracción se crea y se pone en cola de procesamiento.

Errores

400Bad Request

Datos faltantes o archivo inválido.

{"error": "file_base64 es obligatorio"}
402Payment Required

Cuota de extracciones agotada.

{"error": "Cuota de extracciones agotada"}
404Not Found

Habilidad no encontrada.

{"error": "Habilidad no encontrada"}

POST /api/extractions/descartar/{extraction_id}

Descarta una extracción (la marca como descartada sin eliminarla).

POST /api/extractions/descartar/{extraction_id}

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

curl -X POST https://api-docmind.devol.es/api/extractions/descartar/UUID \
  -H "Authorization: Bearer JWT_TOKEN"

Respuesta

{"message": "Extracción descartada exitosamente"}

La extracción se marca como descartada.

Errores

404Not Found

Extracción no encontrada.

{"error": "Extracción no encontrada"}

GET /api/extractions/{extraction_id}/download

Descarga los datos extraídos en formato JSON o CSV.

GET /api/extractions/{extraction_id}/download

Headers

Authorization: Bearer JWT_TOKEN

Query Parameters

  • format: (opcional) Formato de descarga: "json" o "csv". Por defecto: "json"

Ejemplos

curl -X GET "https://api-docmind.devol.es/api/extractions/UUID/download?format=csv" \
  -H "Authorization: Bearer JWT_TOKEN" --output datos.csv

Archivo descargado en el formato solicitado con Content-Disposition: attachment.

Errores

404Not Found

Extracción no encontrada.

{"error": "Extracción no encontrada"}

POST /api/extractions/archivar/{extraction_id}

Archiva una extracción para ocultarla de las vistas principales.

POST /api/extractions/archivar/{extraction_id}

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

curl -X POST https://api-docmind.devol.es/api/extractions/archivar/UUID \
  -H "Authorization: Bearer JWT_TOKEN"

Respuesta

{"message": "Extracción archivada exitosamente"}

La extracción se archiva y no aparece en listados normales.

Errores

404Not Found

Extracción no encontrada.

{"error": "Extracción no encontrada"}

© 2025 Devol. Todos los derechos reservados.