Structures

Una structure es un esquema que define que datos quieres extraer de un documento. Defines los campos — nombre, tipo, descripción — y Matil lee el documento y los rellena. Las structures son la base de todo en Matil. Cada deployment apunta a una structure.

Cómo funciona

Define una structure en el Dashboard de Matil. Por ejemplo, una structure de factura puede tener campos como numero_factura, fecha_factura, total y lineas.
Publica una versión. Las structures usan un flujo de borrador/publicación. Edita el borrador y publica cuando estés listo.
Crea un deployment que apunte a esa versión de la structure.
Envía documentos a través de la API. Matil extrae los datos y devuelve JSON estructurado.

Ejemplo

Si tu structure define campos para una factura, los data extraídos en la respuesta se ven así:

{
  "numero_factura": "FAC-2024-001",
  "fecha_factura": "2024-01-15",
  "moneda": "EUR",
  "lineas": [
    {
      "descripcion": "Servicios de consultoría",
      "cantidad": 10,
      "precio_unitario": 125.00,
      "total_linea": 1250.00
    }
  ],
  "subtotal": 1250.00,
  "importe_impuesto": 262.50,
  "total": 1512.50
}

Precios y páginas

Las estructuras personalizadas se facturan a 0,10 € por página. Lo que cuenta como “pagina” depende del tipo de documento:

Tipo de documento	Que cuenta como 1 página
PDF	1 página del PDF = 1 página
Imagen	1 imagen = 1 página
Texto	Cada 200 palabras = 1 página (mínimo 1)
Hoja de cálculo	Cada 1.500 celdas = 1 página (mínimo 1)

Por ejemplo, un PDF de 3 páginas cuesta 0,03 €. Una hoja de cálculo con 4.500 celdas cuenta como 3 páginas (0,03 €). Las estructuras del marketplace tienen su propio precio fijo por página, que se muestra en la página de cada estructura en el Marketplace.

Tipos de campo

Campos de datos

Estos son los campos que producen valores en la salida:

Tipo	Descripción	Ejemplo de salida
`text`	Un valor de texto. Soporta validación por regex y valores permitidos (enum).	`"FAC-2024-001"`
`number`	Un valor numérico. Soporta precisión decimal y redondeo.	`1250.00`
`boolean`	Un valor verdadero/falso.	`true`
`list_text`	Una lista de textos.	`["EUR", "USD"]`
`list_number`	Una lista de números.	`[10.0, 20.5]`
`object`	Un objeto anidado con sus propios subcampos.	`{"calle": "...", "ciudad": "..."}`
`list_object`	Una tabla — una lista de filas, cada una con las mismas columnas.	`[{"descripcion": "...", "cantidad": 10}]`

Campos estructurales

Estos organizan la extracción pero no producen claves en la salida:

Tipo	Descripción
`group`	Agrupa campos en una unidad de ejecución. Permite extracción en paralelo, ejecución condicional e instrucciones contextuales. Los campos hijos se aplanan al namespace padre en la salida.
`structure`	Referencia la definición versionada de otra structure. Sus campos se aplanan en la salida padre.
`validation`	Una regla inline que verifica los datos extraídos y puede disparar correcciones automáticas o reintentos del LLM.

Groups

Los groups permiten organizar campos en unidades de extracción separadas que pueden ejecutarse en paralelo, mejorando el rendimiento para structures complejas. Una structure con groups:

{
  "fields": [
    {
      "type": "group",
      "name": "cabecera",
      "fields": [
        { "type": "text", "name": "numero_factura", "description": "..." },
        { "type": "text", "name": "moneda", "description": "..." }
      ]
    },
    {
      "type": "group",
      "name": "lineas_detalle",
      "instruction": "Extrae las líneas de detalle. La moneda es {/moneda}.",
      "fields": [
        { "type": "list_object", "name": "lineas", "description": "...", "columns": [...] }
      ]
    }
  ]
}

Produce una salida plana — los nombres de grupo no aparecen:

{
  "numero_factura": "FAC-001",
  "moneda": "EUR",
  "lineas": [...]
}

Los groups también pueden ser condicionales (se omiten si una expresión evalua a false) y pueden incluir instrucciones con placeholders {/path} que referencian datos de otros groups.

Campos computados

Cualquier campo puede marcarse como is_computed: true. En lugar de ser extraído por el LLM, su valor se calcula a partir de una expresión después de la extracción. Útil para valores derivados como totales de línea.

Validaciones

Las structures pueden incluir reglas de validación que verifican los datos extraídos. Cuando una validación falla, puede disparar correcciones programáticas (por ejemplo, recalcular un campo) o pedir al LLM que re-extraiga campos específicos. Cuando un campo no pasa la validación, la respuesta tiene status completed_with_errors e incluye un array de errors:

{
  "errors": [
    {
      "path": "/total",
      "message": "Required field missing",
      "code": "REQUIRED_FIELD"
    }
  ],
  "status": "completed_with_errors"
}

Estado	Significado
`completed`	Todos los campos extraídos y validados correctamente.
`completed_with_errors`	La extracción funcionó, pero algunos campos fallaron la validación. Hay datos parciales disponibles.
`failed`	El procesamiento no pudo completarse.

Versionado

Las structures usan un flujo de borrador/publicación:

Borrador (Draft) — Tu copia de trabajo. Edita libremente sin afectar al procesamiento en producción.
Versión publicada — Una instantánea a la que los deployments pueden apuntar. Una vez publicada, la versión es inmutable.

Puedes publicar tantas versiones como quieras. Cada deployment elige cuál usar, así que puedes probar una nueva versión en un deployment de staging antes de pasarla a producción.

Primeros pasos

Conceptos

Cómo funciona

Ejemplo

Precios y páginas

Tipos de campo

Campos de datos

Campos estructurales

Groups

Campos computados

Validaciones

Versionado

Siguientes pasos

Deployments

Entries

​Cómo funciona

​Ejemplo

​Precios y páginas

​Tipos de campo

​Campos de datos

​Campos estructurales

​Groups

​Campos computados

​Validaciones

​Versionado

​Siguientes pasos

Deployments

Entries

Cómo funciona

Ejemplo

Precios y páginas

Tipos de campo

Campos de datos

Campos estructurales

Groups

Campos computados

Validaciones

Versionado

Siguientes pasos