Documentación API

Habilidades (API Interna)

Gestión completa de habilidades de extracción incluyendo CRUD, reordenamiento de campos y sistema de aprendizaje.

Secciones

CRUD de Habilidades

GET /api/habilidad/

Lista todas las habilidades del cliente actual.

GET /api/habilidad/

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

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

Respuesta

{
  "habilidades": [
    {
      "id": "uuid-hab-1",
      "nombre": "Factura",
      "slug": "factura",
      "info_adicional": "Extraer datos de facturas",
      "campos": [...],
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Lista de habilidades con sus campos configurados.

Errores

401Unauthorized

Token inválido.

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

GET /api/habilidad/{id}

Obtiene una habilidad específica con todos sus campos y configuración.

GET /api/habilidad/{id}

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

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

Respuesta

{
  "id": "uuid-hab-1",
  "nombre": "Factura",
  "slug": "factura",
  "info_adicional": "Extraer datos de facturas",
  "campos": [
    {"id": "campo-1", "nombre": "numero_factura", "tipo": "string", "orden": 1, "descripcion": "Número de factura"},
    {"id": "campo-2", "nombre": "fecha", "tipo": "date", "orden": 2, "descripcion": "Fecha de emisión"}
  ]
}

Habilidad completa con todos sus campos ordenados.

Errores

404Not Found

Habilidad no encontrada.

{"error": "Habilidad no encontrada"}

POST /api/habilidad/

Crea una nueva habilidad de extracción.

POST /api/habilidad/

Headers

Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Body (JSON)

{
  "nombre": "Factura",
  "info_adicional": "Extraer datos principales de facturas",
  "campos": [
    {"nombre": "numero_factura", "tipo": "string", "descripcion": "Número de factura"},
    {"nombre": "monto_total", "tipo": "float", "descripcion": "Monto total"}
  ]
}
  • nombre: (obligatorio) Nombre de la habilidad.
  • info_adicional: (opcional) Contexto adicional para la IA.
  • campos: (obligatorio) Lista de campos con nombre, tipo y descripcion.

Ejemplos

curl -X POST https://api-docmind.devol.es/api/habilidad/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer JWT_TOKEN" \
  -d '{"nombre": "Factura", "campos": [{"nombre": "total", "tipo": "float", "descripcion": "Total"}]}'

Respuesta

{"message": "Habilidad creada exitosamente", "habilidad": {"id": "uuid-new", "nombre": "Factura", "slug": "factura"}}

Habilidad creada con su ID y slug generado.

Errores

400Bad Request

Datos inválidos o faltantes.

{"error": "El nombre es obligatorio"}
409Conflict

Ya existe una habilidad con ese nombre.

{"error": "Ya existe una habilidad con ese nombre"}

PUT /api/habilidad/{id}

Actualiza una habilidad existente (nombre, info adicional, campos).

PUT /api/habilidad/{id}

Headers

Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Body (JSON)

{
  "nombre": "Factura Actualizada",
  "info_adicional": "Nuevo contexto",
  "campos": [...]
}
  • nombre: (opcional) Nuevo nombre.
  • info_adicional: (opcional) Nueva información adicional.
  • campos: (opcional) Lista actualizada de campos.

Ejemplos

curl -X PUT https://api-docmind.devol.es/api/habilidad/UUID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer JWT_TOKEN" \
  -d '{"nombre": "Factura v2", "info_adicional": "Versión actualizada"}'

Respuesta

{"message": "Habilidad actualizada exitosamente"}

Confirmación de la actualización.

Errores

404Not Found

Habilidad no encontrada.

{"error": "Habilidad no encontrada"}
400Bad Request

Datos inválidos.

{"error": "Datos inválidos"}

DELETE /api/habilidad/{id}

Elimina una habilidad y todos sus campos asociados.

DELETE /api/habilidad/{id}

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

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

Respuesta

{"message": "Habilidad eliminada exitosamente"}

La habilidad y sus campos se eliminan permanentemente.

Errores

404Not Found

Habilidad no encontrada.

{"error": "Habilidad no encontrada"}

GET /api/habilidad/{id}/prompt-preview

Obtiene una vista previa del prompt que se envía a la IA para esta habilidad.

GET /api/habilidad/{id}/prompt-preview

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

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

Respuesta

{"prompt": "Extrae los siguientes campos del documento...\n- numero_factura (string): ..."}

El prompt completo que se generaría al ejecutar una extracción.

Errores

404Not Found

Habilidad no encontrada.

{"error": "Habilidad no encontrada"}

Reordenamiento de campos

PUT /api/habilidad/{id}/reorder

Reordena los campos de una habilidad.

PUT /api/habilidad/{id}/reorder

Headers

Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Body (JSON)

{
  "orden": ["campo-uuid-2", "campo-uuid-1", "campo-uuid-3"]
}
  • orden: (obligatorio) Lista ordenada de IDs de campos.

Ejemplos

curl -X PUT https://api-docmind.devol.es/api/habilidad/UUID/reorder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer JWT_TOKEN" \
  -d '{"orden": ["campo-2", "campo-1", "campo-3"]}'

Respuesta

{"message": "Campos reordenados exitosamente"}

Los campos se reordenan según la lista proporcionada.

Errores

400Bad Request

Lista de IDs inválida.

{"error": "IDs de campos inválidos"}

PUT /api/habilidad/{id}/campos/{campo_id}/subcampos/reorder

Reordena los subcampos de un campo tipo objeto.

PUT /api/habilidad/{id}/campos/{campo_id}/subcampos/reorder

Headers

Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Body (JSON)

{"orden": ["sub-uuid-2", "sub-uuid-1"]}
  • orden: (obligatorio) Lista ordenada de IDs de subcampos.

Ejemplos

curl -X PUT https://api-docmind.devol.es/api/habilidad/UUID/campos/CAMPO_ID/subcampos/reorder \
  -H "Content-Type: application/json" -H "Authorization: Bearer JWT_TOKEN" \
  -d '{"orden": ["sub-2", "sub-1"]}'

Respuesta

{"message": "Subcampos reordenados exitosamente"}

Subcampos reordenados.

Errores

400Bad Request

Lista de IDs inválida.

{"error": "IDs inválidos"}

Sistema de Aprendizaje

El sistema de aprendizaje permite mejorar las habilidades de extracción de forma iterativa usando feedback humano.

POST /api/habilidad/{id}/aprendizaje/iniciar

Inicia una sesión de aprendizaje para mejorar la extracción con un documento de ejemplo.

POST /api/habilidad/{id}/aprendizaje/iniciar

Headers

Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Body (JSON)

{
  "extraction_id": "uuid-extraction",
  "model": "gpt-4o"
}
  • extraction_id: (obligatorio) ID de la extracción de ejemplo.
  • model: (opcional) Modelo de IA a usar.

Ejemplos

curl -X POST https://api-docmind.devol.es/api/habilidad/UUID/aprendizaje/iniciar \
  -H "Content-Type: application/json" -H "Authorization: Bearer JWT_TOKEN" \
  -d '{"extraction_id": "uuid-extraction"}'

Respuesta

{"message": "Sesión de aprendizaje iniciada", "sesion_id": "uuid-sesion", "preview": {...}}

Sesión creada con preview de los resultados de la extracción.

Errores

400Bad Request

Falta extraction_id.

{"error": "extraction_id es obligatorio"}
404Not Found

Extracción o habilidad no encontrada.

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

Ya existe una sesión activa.

{"error": "Ya existe una sesión de aprendizaje activa"}

GET /api/habilidad/{id}/aprendizaje/activa

Obtiene la sesión de aprendizaje activa de una habilidad.

GET /api/habilidad/{id}/aprendizaje/activa

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

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

Respuesta

{"sesion": {"id": "uuid-sesion", "status": "activa", "created_at": "...", "preview": {...}}}

Sesión activa con su estado y preview actual.

Errores

404Not Found

No hay sesión activa.

{"error": "No hay sesión de aprendizaje activa"}

GET /api/habilidad/{id}/aprendizaje/{sesion_id}

Consulta los detalles de una sesión de aprendizaje específica.

GET /api/habilidad/{id}/aprendizaje/{sesion_id}

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

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

Respuesta

{"sesion": {"id": "uuid-sesion", "status": "activa", "feedback_history": [], "preview": {...}}}

Detalles completos de la sesión incluyendo historial de feedback.

Errores

404Not Found

Sesión no encontrada.

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

DELETE /api/habilidad/{id}/aprendizaje/{sesion_id}

Descarta una sesión de aprendizaje sin aplicar cambios.

DELETE /api/habilidad/{id}/aprendizaje/{sesion_id}

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

curl -X DELETE https://api-docmind.devol.es/api/habilidad/UUID/aprendizaje/SESION_ID \
  -H "Authorization: Bearer JWT_TOKEN"

Respuesta

{"message": "Sesión de aprendizaje descartada"}

La sesión se elimina sin aplicar cambios a la habilidad.

Errores

404Not Found

Sesión no encontrada.

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

POST /api/habilidad/{id}/aprendizaje/{sesion_id}/feedback

Envía feedback sobre los resultados de la extracción de prueba para mejorar el prompt.

POST /api/habilidad/{id}/aprendizaje/{sesion_id}/feedback

Headers

Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Body (JSON)

{
  "feedback": "El campo numero_factura no extrajo correctamente. Debería ser FAC-001.",
  "campos_corregidos": {"numero_factura": "FAC-001"}
}
  • feedback: (obligatorio) Texto con las correcciones.
  • campos_corregidos: (opcional) Campos con valores correctos.

Ejemplos

curl -X POST https://api-docmind.devol.es/api/habilidad/UUID/aprendizaje/SESION_ID/feedback \
  -H "Content-Type: application/json" -H "Authorization: Bearer JWT_TOKEN" \
  -d '{"feedback": "Corregir campo total", "campos_corregidos": {"total": "1500"}}'

Respuesta

{"message": "Feedback recibido", "new_preview": {...}}

El sistema re-procesa con el feedback y devuelve un nuevo preview.

Errores

400Bad Request

Feedback vacío.

{"error": "El feedback es obligatorio"}
404Not Found

Sesión no encontrada.

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

POST /api/habilidad/{id}/aprendizaje/{sesion_id}/re-extraer

Re-ejecuta la extracción con el prompt mejorado para verificar los resultados.

POST /api/habilidad/{id}/aprendizaje/{sesion_id}/re-extraer

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

curl -X POST https://api-docmind.devol.es/api/habilidad/UUID/aprendizaje/SESION_ID/re-extraer \
  -H "Authorization: Bearer JWT_TOKEN"

Respuesta

{"message": "Re-extracción completada", "preview": {...}}

Nuevo preview con los resultados de la re-extracción.

Errores

404Not Found

Sesión no encontrada.

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

POST /api/habilidad/{id}/aprendizaje/{sesion_id}/aprobar

Aprueba los resultados del aprendizaje y aplica los cambios al prompt de la habilidad.

POST /api/habilidad/{id}/aprendizaje/{sesion_id}/aprobar

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

curl -X POST https://api-docmind.devol.es/api/habilidad/UUID/aprendizaje/SESION_ID/aprobar \
  -H "Authorization: Bearer JWT_TOKEN"

Respuesta

{"message": "Aprendizaje aprobado y aplicado exitosamente"}

Los cambios del prompt se guardan permanentemente en la habilidad.

Errores

404Not Found

Sesión no encontrada.

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

GET /api/habilidad/{id}/entrenamientos

Obtiene el historial de entrenamientos (aprendizajes) de una habilidad.

GET /api/habilidad/{id}/entrenamientos

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

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

Respuesta

{
  "entrenamientos": [
    {"id": "uuid", "fecha": "2025-01-15T10:00:00Z", "status": "aprobado", "feedback_count": 3}
  ]
}

Lista de entrenamientos con su estado y cantidad de feedback.

Errores

404Not Found

Habilidad no encontrada.

{"error": "Habilidad no encontrada"}

© 2025 Devol. Todos los derechos reservados.