Documentación API

Catálogos (API Interna)

CRUD completo de catálogos con gestión de columnas, registros, importación masiva y vinculación con campos de habilidades.

GET /api/catalogos/

Lista todos los catálogos del cliente con estadísticas.

GET /api/catalogos/

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

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

Respuesta

{"catalogos": [{"id": "uuid", "nombre": "Proveedores", "descripcion": "...", "total_registros": 150, "total_columnas": 10}]}

Lista de catálogos con sus estadísticas básicas.

Errores

401Unauthorized

Token inválido.

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

GET /api/catalogos/{id}

Obtiene un catálogo con sus columnas y estadísticas.

GET /api/catalogos/{id}

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

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

Respuesta

{"catalogo": {"id": "uuid", "nombre": "Proveedores", "columnas": [{"id": "col-1", "nombre": "nombre", "tipo": "string"}], "total_registros": 150}}

Catálogo completo con estructura de columnas.

Errores

404Not Found

Catálogo no encontrado.

{"error": "Catálogo no encontrado"}

POST /api/catalogos/

Crea un nuevo catálogo desde un archivo CSV o XLSX.

POST /api/catalogos/

Headers

Content-Type: multipart/form-data
Authorization: Bearer JWT_TOKEN

Form Data

  • nombre*: Nombre del catálogo
  • descripcion: Descripción
  • file*: Archivo CSV o XLSX

Ejemplos

curl -X POST https://api-docmind.devol.es/api/catalogos/ \
  -H "Authorization: Bearer JWT_TOKEN" \
  -F "nombre=Proveedores" -F "file=@proveedores.csv"

Respuesta

{"message": "Catálogo creado", "catalogo": {"id": "uuid", "nombre": "Proveedores"}, "import_summary": {"total": 100, "successful": 100, "failed": 0}}

Catálogo creado con resumen de la importación.

Errores

400Bad Request

Archivo faltante o formato inválido.

{"error": "Se requiere un archivo CSV o XLSX"}

PUT /api/catalogos/{id}

Actualiza un catálogo reemplazando sus datos con un nuevo archivo.

PUT /api/catalogos/{id}

Headers

Content-Type: multipart/form-data
Authorization: Bearer JWT_TOKEN

Form Data

  • nombre: Nuevo nombre
  • descripcion: Nueva descripción
  • file*: Archivo CSV o XLSX con nuevos datos

Ejemplos

curl -X PUT https://api-docmind.devol.es/api/catalogos/UUID \
  -H "Authorization: Bearer JWT_TOKEN" \
  -F "nombre=Proveedores v2" -F "file=@nuevos_datos.csv"

Respuesta

{"message": "Catálogo actualizado", "summary": {"records": {"deleted": 100, "imported": 120}}}

Datos reemplazados completamente.

Errores

404Not Found

Catálogo no encontrado.

{"error": "Catálogo no encontrado"}

DELETE /api/catalogos/{id}

Elimina un catálogo y todos sus registros.

DELETE /api/catalogos/{id}

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

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

Respuesta

{"message": "Catálogo eliminado exitosamente"}

El catálogo y todos sus datos se eliminan permanentemente.

Errores

404Not Found

Catálogo no encontrado.

{"error": "Catálogo no encontrado"}

GET /api/catalogos/{id}/columnas

Obtiene las columnas de un catálogo.

GET /api/catalogos/{id}/columnas

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

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

Respuesta

{"columnas": [{"id": "col-1", "nombre": "nombre", "tipo": "string", "orden": 1}]}

Lista de columnas ordenadas por posición.

Errores

404Not Found

Catálogo no encontrado.

{"error": "Catálogo no encontrado"}

GET /api/catalogos/{id}/registros

Lista registros de un catálogo con paginación.

GET /api/catalogos/{id}/registros

Headers

Authorization: Bearer JWT_TOKEN

Query Parameters

  • page: (opcional) Página. Por defecto: 1
  • per_page: (opcional) Registros por página. Por defecto: 50
  • search: (opcional) Buscar en todos los campos

Ejemplos

curl -X GET "https://api-docmind.devol.es/api/catalogos/UUID/registros?page=1&per_page=50" \
  -H "Authorization: Bearer JWT_TOKEN"

Respuesta

{"registros": [{"id": "rec-1", "valores": {"nombre": "ACME Corp"}}], "pagination": {"total": 150, "page": 1}}

Registros paginados con sus valores.

Errores

404Not Found

Catálogo no encontrado.

{"error": "Catálogo no encontrado"}

POST /api/catalogos/{id}/registros

Agrega un nuevo registro al catálogo.

POST /api/catalogos/{id}/registros

Headers

Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Body (JSON)

{"valores": {"nombre": "Nueva Empresa", "nif": "B12345678"}}
  • valores: (obligatorio) Objeto con los valores para cada columna.

Ejemplos

curl -X POST https://api-docmind.devol.es/api/catalogos/UUID/registros \
  -H "Content-Type: application/json" -H "Authorization: Bearer JWT_TOKEN" \
  -d '{"valores": {"nombre": "Nueva Empresa", "nif": "B12345678"}}'

Respuesta

{"message": "Registro creado", "registro": {"id": "rec-new", "valores": {"nombre": "Nueva Empresa"}}}

Registro creado con sus valores.

Errores

400Bad Request

Valores faltantes o inválidos.

{"error": "Valores requeridos faltantes"}

PUT /api/catalogos/{id}/registros/{registro_id}

Actualiza un registro existente del catálogo.

PUT /api/catalogos/{id}/registros/{registro_id}

Headers

Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Body (JSON)

{"valores": {"nombre": "Empresa Actualizada"}}
  • valores: (obligatorio) Valores a actualizar.

Ejemplos

curl -X PUT https://api-docmind.devol.es/api/catalogos/UUID/registros/REC_ID \
  -H "Content-Type: application/json" -H "Authorization: Bearer JWT_TOKEN" \
  -d '{"valores": {"nombre": "Empresa Actualizada"}}'

Respuesta

{"message": "Registro actualizado exitosamente"}

Confirmación de la actualización.

Errores

404Not Found

Registro no encontrado.

{"error": "Registro no encontrado"}

DELETE /api/catalogos/{id}/registros/{registro_id}

Elimina un registro del catálogo.

DELETE /api/catalogos/{id}/registros/{registro_id}

Headers

Authorization: Bearer JWT_TOKEN

Ejemplos

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

Respuesta

{"message": "Registro eliminado exitosamente"}

El registro se elimina permanentemente.

Errores

404Not Found

Registro no encontrado.

{"error": "Registro no encontrado"}

POST /api/catalogos/{id}/import

Importa registros masivamente desde un archivo CSV/XLSX sin reemplazar los existentes.

POST /api/catalogos/{id}/import

Headers

Content-Type: multipart/form-data
Authorization: Bearer JWT_TOKEN

Form Data

  • file*: Archivo CSV o XLSX con registros a importar

Ejemplos

curl -X POST https://api-docmind.devol.es/api/catalogos/UUID/import \
  -H "Authorization: Bearer JWT_TOKEN" -F "file=@nuevos_registros.csv"

Respuesta

{"message": "Importación completada", "summary": {"total": 50, "successful": 48, "failed": 2}}

Resumen de la importación con conteo de éxitos y fallos.

Errores

400Bad Request

Archivo inválido.

{"error": "Formato de archivo no soportado"}

POST /api/catalogos/{id}/vincular-campo

Vincula un catálogo a un campo de una habilidad para matching automático.

POST /api/catalogos/{id}/vincular-campo

Headers

Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Body (JSON)

{
  "campo_id": "campo-uuid",
  "columnas_busqueda": ["nombre_empresa"],
  "columnas_salida": ["nombre_empresa", "nif", "direccion"],
  "metodo_busqueda": "exacta",
  "threshold": 0.8
}
  • campo_id: (obligatorio) ID del campo de la habilidad.
  • columnas_busqueda: (obligatorio) Columnas para buscar coincidencias.
  • columnas_salida: (obligatorio) Columnas a incluir en el resultado.
  • metodo_busqueda: (opcional) "exacta" o "aproximada". Por defecto: "exacta".
  • threshold: (opcional) Umbral de similitud para búsqueda aproximada (0.0-1.0).

Ejemplos

curl -X POST https://api-docmind.devol.es/api/catalogos/UUID/vincular-campo \
  -H "Content-Type: application/json" -H "Authorization: Bearer JWT_TOKEN" \
  -d '{"campo_id": "campo-uuid", "columnas_busqueda": ["nombre"], "columnas_salida": ["nombre", "nif"]}'

Respuesta

{"message": "Campo vinculado exitosamente al catálogo"}

El campo queda configurado para buscar en este catálogo durante las extracciones.

Errores

400Bad Request

Columnas inválidas.

{"error": "Columna nombre_xxx no existe en el catálogo"}
404Not Found

Catálogo o campo no encontrado.

{"error": "Catálogo no encontrado"}

© 2025 Devol. Todos los derechos reservados.