Documentación API

Documentación de Catálogos

Los catálogos permiten normalizar y enriquecer los datos extraídos de documentos mediante la búsqueda automática en maestros de datos privados. Puedes crear catálogos con información de proveedores, clientes, productos, etc., y el sistema buscará automáticamente coincidencias durante las extracciones.

¿Cómo funcionan los catálogos?

  1. Crear un catálogo: Sube un archivo CSV/XLSX con tus datos maestros
  2. Configurar campos de catálogo: En tu habilidad, marca campos para usar catálogos
  3. Extracciones automáticas: El sistema busca coincidencias y enriquece los datos

POST /v1/catalogs

Crea un nuevo catálogo desde un archivo CSV o XLSX para normalizar y enriquecer datos extraídos.

POST /v1/catalogs

Headers

Content-Type: multipart/form-data
x-api-key: TU_API_KEY

Form Data

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

Ejemplos de petición

curl -X POST "https://api-docmind.devol.es/v1/catalogs" \
  -H "x-api-key: TU_API_KEY" \
  -F "nombre=Catálogo de Proveedores" \
  -F "descripcion=Maestro con todos los proveedores de la empresa" \
  -F "file=@proveedores.csv"

Respuesta

{
  "message": "Catálogo creado exitosamente con datos importados",
  "catalog": {
    "id": "91a7be6e-aab6-4cbf-8898-384dcfb18aae",
    "nombre": "Catálogo de Prueba",
    "descripcion": "Catálogo creado para testing de la API",
    "fecha_creacion": "2025-06-25T09:20:08.040256+00:00",
    "cliente_id": "62242e32-ba8f-4b59-9c4b-7867fc51a5f6",
    "columnas": [
      {
        "id": "2a972fb9-8659-44ac-8d3f-67aa8ace7d9c",
        "nombre": "id_proveedor",
        "orden": 1,
        "tipo": "string"
      },
      {
        "id": "3dfbec16-823f-40ba-acb4-d48a75e65455",
        "nombre": "nombre_empresa",
        "orden": 2,
        "tipo": "string"
      }
    ]
  },
  "import_summary": {
    "total_rows": 4,
    "successful": 4,
    "failed": 0,
    "has_errors": false
  }
}

El catálogo se crea exitosamente con todas las columnas detectadas automáticamente desde el archivo. La respuesta incluye el catálogo completo con sus columnas y un resumen de la importación de datos.

GET /v1/catalogs

Obtiene todos los catálogos disponibles para tu organización.

GET /v1/catalogs

Headers

x-api-key: TU_API_KEY

Query Parameters

  • include_details: (opcional) Si es "true", incluye información detallada de columnas. Por defecto: false
  • client_id: (solo global_admin) ID del cliente del cual obtener los catálogos

Ejemplos de petición

curl -X GET "https://api-docmind.devol.es/v1/catalogs?include_details=true" \
  -H "x-api-key: TU_API_KEY"

Respuesta

{
  "message": "Catálogos obtenidos exitosamente",
  "catalogs": [
    {
      "id": "95f09806-dea9-45aa-8569-a9d9bc59f4fe",
      "nombre": "Proveedores Devol",
      "descripcion": "Este es un maestro con todos los proveedores de Devol",
      "stats": {
        "total_columns": 22,
        "total_records": 11
      },
      "columns": [
        {
          "id": "32ba9771-1bb7-4dd7-8000-8970435035ef",
          "nombre": "id_proveedor",
          "orden": 1,
          "tipo": "string"
        },
        {
          "id": "8a039cba-11e4-43b5-bc67-c61b3934003f",
          "nombre": "nombre_empresa",
          "orden": 2,
          "tipo": "string"
        }
      ]
    }
  ],
  "meta": {
    "total_catalogs": 1,
    "include_details": true
  }
}

Devuelve una lista de catálogos con información básica. Si include_details=true, incluye también la estructura de columnas de cada catálogo.

GET /v1/catalogs/{catalog_id}

Obtiene un catálogo específico por su ID con detalles completos incluyendo todas sus columnas.

GET /v1/catalogs/{catalog_id}

Headers

x-api-key: TU_API_KEY

Query Parameters

  • include_records_count: (opcional) Si es "false", no incluye el conteo de registros. Por defecto: true

Ejemplos de petición

curl -X GET "https://api-docmind.devol.es/v1/catalogs/91a7be6e-aab6-4cbf-8898-384dcfb18aae" \
  -H "x-api-key: TU_API_KEY"

Respuesta

{
  "message": "Catálogo obtenido exitosamente",
  "catalog": {
    "id": "91a7be6e-aab6-4cbf-8898-384dcfb18aae",
    "nombre": "Catálogo de Prueba",
    "descripcion": "Catálogo creado para testing de la API",
    "stats": {
      "total_columns": 10,
      "total_records": 4
    },
    "columns": [
      {
        "id": "2a972fb9-8659-44ac-8d3f-67aa8ace7d9c",
        "nombre": "id_proveedor",
        "orden": 1,
        "tipo": "string"
      },
      {
        "id": "3dfbec16-823f-40ba-acb4-d48a75e65455",
        "nombre": "nombre_empresa",
        "orden": 2,
        "tipo": "string"
      }
    ]
  }
}

Devuelve la información completa del catálogo incluyendo todas sus columnas ordenadas por posición.

PUT /v1/catalogs/{catalog_id}

Actualiza un catálogo existente reemplazando su contenido con un archivo CSV o XLSX. ELIMINA todos los registros existentes y los reemplaza con los datos del archivo.

PUT /v1/catalogs/{catalog_id}

Headers

Content-Type: multipart/form-data
x-api-key: TU_API_KEY

Form Data

  • file *: Archivo CSV o XLSX con los nuevos datos
  • nombre : Nuevo nombre para el catálogo
  • descripcion : Nueva descripción para el catálogo

Ejemplos de petición

curl -X PUT "https://api-docmind.devol.es/v1/catalogs/91a7be6e-aab6-4cbf-8898-384dcfb18aae" \
  -H "x-api-key: TU_API_KEY" \
  -F "nombre=Catálogo Actualizado" \
  -F "descripcion=Catálogo con datos actualizados" \
  -F "file=@proveedores_actualizados.csv"

Respuesta

{
  "message": "Catálogo actualizado exitosamente",
  "catalog": {
    "id": "91a7be6e-aab6-4cbf-8898-384dcfb18aae",
    "nombre": "Catálogo de Prueba Actualizado",
    "descripcion": "Catálogo creado para testing de la API",
    "last_modification": "2025-06-25T09:32:57.065231+00:00"
  },
  "summary": {
    "columns": {
      "added": 1,
      "modified": 0,
      "missing_in_file": 0
    },
    "records": {
      "deleted": 4,
      "imported": 3,
      "failed": 0
    },
    "metadata_updated": {
      "name": true,
      "description": false
    }
  }
}

La actualización elimina todos los registros existentes y los reemplaza con los del archivo. Añade nuevas columnas si las encuentra, pero mantiene las columnas existentes. El resumen muestra todos los cambios realizados.

GET /v1/catalogs/{catalog_id}/columns

Obtiene todas las columnas de un catálogo ordenadas por posición.

GET /v1/catalogs/{catalog_id}/columns

Headers

x-api-key: TU_API_KEY

Ejemplos de petición

curl -X GET "https://api-docmind.devol.es/v1/catalogs/91a7be6e-aab6-4cbf-8898-384dcfb18aae/columns" \
  -H "x-api-key: TU_API_KEY"

Respuesta

{
  "message": "Columnas obtenidas exitosamente",
  "columns": [
    {
      "id": "2a972fb9-8659-44ac-8d3f-67aa8ace7d9c",
      "nombre": "id_proveedor",
      "orden": 1,
      "tipo": "string"
    },
    {
      "id": "3dfbec16-823f-40ba-acb4-d48a75e65455",
      "nombre": "nombre_empresa",
      "orden": 2,
      "tipo": "string"
    }
  ],
  "meta": {
    "total_columns": 10,
    "catalog_id": "91a7be6e-aab6-4cbf-8898-384dcfb18aae"
  }
}

Devuelve todas las columnas del catálogo con su información de tipo y orden.

GET /v1/catalogs/{catalog_id}/records

Obtiene los registros de un catálogo con paginación optimizada.

GET /v1/catalogs/{catalog_id}/records

Headers

x-api-key: TU_API_KEY

Query Parameters

  • page: (opcional) Número de página. Por defecto: 1
  • per_page: (opcional) Registros por página (máximo 1000). Por defecto: 50
  • all: (opcional) Si es "true", devuelve todos los registros sin paginación

Ejemplos de petición

curl -X GET "https://api-docmind.devol.es/v1/catalogs/91a7be6e-aab6-4cbf-8898-384dcfb18aae/records?page=1&per_page=2" \
  -H "x-api-key: TU_API_KEY"

Respuesta

{
  "message": "Registros obtenidos exitosamente",
  "records": [
    {
      "id": "e173ccfd-3d47-4c4f-9061-6c9969981140",
      "valores": {
        "id_proveedor": "PROV001",
        "nombre_empresa": "Acme Corp",
        "contacto_principal": "Juan Pérez",
        "categoria": "Tecnología",
        "ciudad": "Madrid",
        "telefono": "+34 91 123 4567",
        "email": "juan@acme.com",
        "activo": true,
        "fecha_alta": "01/15/2023",
        "volumen_ventas": 150000
      }
    }
  ],
  "pagination": {
    "total": 4,
    "page": 1,
    "per_page": 2,
    "total_pages": 2,
    "has_next": true,
    "has_prev": false
  },
  "meta": {
    "catalog_id": "91a7be6e-aab6-4cbf-8898-384dcfb18aae"
  }
}

Devuelve los registros del catálogo con información de paginación. Cada registro incluye un ID único y un objeto "valores" con todos los datos.

POST /v1/catalogs/{catalog_id}/records/search

Busca registros en un catálogo basado en criterios específicos de columnas.

POST /v1/catalogs/{catalog_id}/records/search

Headers

Content-Type: application/json
x-api-key: TU_API_KEY

Body (JSON)

{
  "criteria": {
    "categoria": "Tecnología",
    "activo": true
  },
  "page": 1,
  "per_page": 50
}
  • criteria: Objeto con los criterios de búsqueda (nombre_columna: valor_a_buscar)
  • page: (opcional) Número de página. Por defecto: 1
  • per_page: (opcional) Registros por página (máximo 1000). Por defecto: 50

Ejemplos de petición

curl -X POST "https://api-docmind.devol.es/v1/catalogs/91a7be6e-aab6-4cbf-8898-384dcfb18aae/records/search" \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "criteria": {
      "categoria": "Tecnología",
      "activo": true
    },
    "page": 1,
    "per_page": 10
  }'

Respuesta

{
  "message": "Búsqueda completada exitosamente",
  "records": [
    {
      "id": "e173ccfd-3d47-4c4f-9061-6c9969981140",
      "valores": {
        "id_proveedor": "PROV001",
        "nombre_empresa": "Acme Corp",
        "categoria": "Tecnología",
        "activo": true
      }
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "per_page": 10,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  },
  "search": {
    "criteria": {
      "categoria": "Tecnología",
      "activo": true
    },
    "matches_found": 1
  },
  "meta": {
    "catalog_id": "91a7be6e-aab6-4cbf-8898-384dcfb18aae"
  }
}

Devuelve los registros que coinciden con los criterios especificados. La búsqueda es exacta para cada criterio y todos deben cumplirse (AND lógico).

Casos de Uso Comunes

1. Normalización de Proveedores

Crea un catálogo con información completa de proveedores y configura un campo de catálogo en tu habilidad. Cuando extraigas facturas, el sistema buscará automáticamente el proveedor y completará datos como contacto, teléfono y dirección.

2. Validación de Clientes

Mantén un catálogo actualizado de clientes activos. Durante la extracción de contratos o pedidos, verifica automáticamente que los clientes existen y obtén su información comercial.

3. Enriquecimiento de Productos

Almacena especificaciones técnicas, precios y categorías de productos. Al procesar órdenes de compra, completa automáticamente los detalles de cada producto.

Códigos de Error

  • 400 Bad Request: Error de validación del archivo o parámetros inválidos.
  • 401 Unauthorized: Falta o es inválido el x-api-key.
  • 403 Forbidden: Sin permisos para acceder o modificar el catálogo.
  • 404 Not Found: No se encontró el catálogo solicitado.
  • 500 Internal Server Error: Error interno (reintentar más tarde o contactar al soporte).

Limitaciones

  • Formatos soportados: CSV y XLSX únicamente
  • Tamaño máximo: 10MB por archivo
  • Registros por página: Máximo 1000 en consultas paginadas
  • Búsqueda: Los criterios son exactos (sensible a mayúsculas/minúsculas)
  • Actualización: Reemplaza completamente los datos existentes

© 2025 Devol. Todos los derechos reservados.