Documentación API

Documentación de Habilidades

Las habilidades definen qué campos se extraerán de tus documentos. Cada habilidad tiene un slug único que usas al crear extracciones.

GET /v1/skills

Obtiene todas las habilidades de extracción disponibles para tu organización.

GET /v1/skills

Headers

x-api-key: TU_API_KEY

Ejemplos de petición

curl -X GET https://api-docmind.devol.es/v1/skills \
  -H "x-api-key: TU_API_KEY"

Respuesta exitosa

{
  "message": "Habilidades obtenidas exitosamente",
  "skills": [
    {
      "id": "44296bf3-61a7-4099-9cce-6027a445a517",
      "name": "Factura",
      "slug": "factura",
      "created_at": "Fri, 29 Nov 2024 15:52:11 GMT"
    },
    {
      "id": "0c08dcbf-d3aa-45c4-96a7-80a965f993ed",
      "name": "DNI",
      "slug": "dni",
      "created_at": "Wed, 27 Nov 2024 17:44:00 GMT"
    }
  ]
}

Devuelve una lista de habilidades disponibles en tu organización. Cada habilidad incluye un ID único, nombre, slug para usar en extracciones, y fecha de creación.

Respuestas de error

401 Unauthorized

API Key inválida o no proporcionada.

{"error": "API key inválida"}
500 Internal Server Error

Error interno del servidor.

{"error": "Error interno del servidor"}

POST /v1/skills

Crea una nueva habilidad de extracción para tu organización. Define qué campos se extraerán de los documentos.

POST /v1/skills

Headers

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

Body (JSON)

{
  "nombre": "Factura",
  "info_adicional": "Extraer datos principales de facturas comerciales",
  "campos": [
    {
      "nombre": "numero_factura",
      "tipo": "string",
      "descripcion": "Número de la factura"
    },
    {
      "nombre": "fecha_emision",
      "tipo": "date",
      "descripcion": "Fecha de emisión de la factura"
    },
    {
      "nombre": "monto_total",
      "tipo": "float",
      "descripcion": "Monto total de la factura"
    }
  ]
}
  • nombre: (obligatorio) Nombre de la habilidad.
  • info_adicional: (opcional) Descripción o contexto adicional para la IA.
  • campos: (obligatorio) Array de campos a extraer, cada uno con nombre, tipo y descripcion.

Ejemplos de petición

curl -X POST https://api-docmind.devol.es/v1/skills \
  -H "Content-Type: application/json" \
  -H "x-api-key: TU_API_KEY" \
  -d '{
    "nombre": "Factura",
    "info_adicional": "Extraer datos principales de facturas",
    "campos": [
      {"nombre": "numero_factura", "tipo": "string", "descripcion": "Número de la factura"},
      {"nombre": "fecha_emision", "tipo": "date", "descripcion": "Fecha de emisión"},
      {"nombre": "monto_total", "tipo": "float", "descripcion": "Monto total"}
    ]
  }'

Respuesta exitosa

{
  "message": "Habilidad creada exitosamente",
  "skill": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Factura",
    "slug": "factura",
    "created_at": "Mon, 10 Mar 2025 10:30:00 GMT"
  }
}

Devuelve la habilidad creada con su ID y slug generado automáticamente. El slug se genera a partir del nombre y se usa para referenciar la habilidad en extracciones.

Respuestas de error

400 Bad Request

Datos inválidos o campos faltantes.

{"error": "El nombre es obligatorio"}
401 Unauthorized

API Key inválida o no proporcionada.

{"error": "API key inválida"}
409 Conflict

Ya existe una habilidad con ese nombre.

{"error": "Ya existe una habilidad con el nombre Factura"}
500 Internal Server Error

Error interno del servidor.

{"error": "Error interno del servidor"}

Campos avanzados al crear una habilidad

POST /v1/skills acepta la misma definición completa que la pantalla de habilidades. Además de nombre, type y descripcion, cada campo admite:

ClaveAplica aPara qué sirve
isListcualquieraEl campo es una lista de elementos.
obligatoriocualquieraSi falta, la extracción se marca incompleta. Por defecto true.
subcamposobjectDefinición recursiva de los campos hijos.
generado_por_sistemacualquieraLo rellena el motor, no el modelo. Se excluye del prompt.
catalogocatalogCatálogo, columnas clave, columnas de salida y configuración de búsqueda.
agrupacioncatalogMatching agrupado: sumar por grupo y contrastar contra el maestro.

Columnas clave y su origen

Cada entrada de columnas_clave puede ser un nombre suelto o un objeto que declara de dónde sale el valor con el que se busca:

  • "origen_tipo": "pdf" — del documento (por defecto).
  • "origen_tipo": "campo" + origen_campo_id — de otro campo extraído.
  • "origen_tipo": "catalogo" + origen_campo_id y origen_columna_output — del resultado de otro campo catálogo ya resuelto (búsquedas encadenadas).

En configuracion se admite además valores_excluidos: una lista de valores que nunca deben casar (por ejemplo, el CIF de tu propia empresa, que aparece en todas las facturas que recibes).

Agrupación (matching agrupado)

Sirve para casos como «suma los importes por albarán y contrástalos con el maestro de recepciones». Dentro del bloque agrupacion los demás campos se referencian por nombre, no por ID: los campos se crean en la misma petición y sus identificadores todavía no existen cuando envías el JSON.

{
  "nombre": "linea_numlin_cat",
  "type": "catalog",
  "catalogo": {
    "catalogo_id": "UUID-DEL-CATALOGO-RECEPCIONES",
    "columnas_clave": [
      { "nombre": "proveedor", "origen_tipo": "catalogo",
        "origen_campo_id": "UUID-DEL-CAMPO-ID-PROVEEDOR",
        "origen_columna_output": "codigo" },
      { "nombre": "albaran", "origen_tipo": "campo",
        "origen_campo_id": "UUID-DEL-CAMPO-LINEA-ALBARAN" }
    ],
    "columnas_output": ["linea", "pedido", "importe"],
    "configuracion": {
      "tipo_busqueda": "exacta",
      "normalizaciones": { "mayusculas": true, "sin_espacios": true },
      "valores_excluidos": ["A20426078"]
    }
  },
  "agrupacion": {
    "campo_origen": "Albaranes",
    "catalogo_columna_suma": "importe",
    "tolerancia_suma": 0.01,
    "campo_verificacion": "Verificacion",
    "mapeos": [
      { "catalogo_columna": "linea", "campo_destino": "linea_numlin" }
    ]
  }
}

O bien indicas campo_origen (una lista que el modelo ya devuelve agrupada y sumada), o bien el par campo_agrupacion + campo_suma para que el motor agrupe. Sin ninguno de los dos la creación se rechaza con un 400.

© 2025 Devol. Todos los derechos reservados.