Saltar al contenido principal
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

  1. 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.
  2. Publica una versión. Las structures usan un flujo de borrador/publicación. Edita el borrador y publica cuando estés listo.
  3. Crea un deployment que apunte a esa versión de la structure.
  4. 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 documentoQue cuenta como 1 página
PDF1 página del PDF = 1 página
Imagen1 imagen = 1 página
TextoCada 200 palabras = 1 página (mínimo 1)
Hoja de cálculoCada 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:
TipoDescripciónEjemplo de salida
textUn valor de texto. Soporta validación por regex y valores permitidos (enum)."FAC-2024-001"
numberUn valor numérico. Soporta precisión decimal y redondeo.1250.00
booleanUn valor verdadero/falso.true
list_textUna lista de textos.["EUR", "USD"]
list_numberUna lista de números.[10.0, 20.5]
objectUn objeto anidado con sus propios subcampos.{"calle": "...", "ciudad": "..."}
list_objectUna 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:
TipoDescripción
groupAgrupa 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.
structureReferencia la definición versionada de otra structure. Sus campos se aplanan en la salida padre.
validationUna 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"
}
EstadoSignificado
completedTodos los campos extraídos y validados correctamente.
completed_with_errorsLa extracción funcionó, pero algunos campos fallaron la validación. Hay datos parciales disponibles.
failedEl 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.

​
Siguientes pasos

Deployments

Conecta tu structure a un deployment para acceder vía API.

Entries

Entiende cómo se almacenan los resultados y como corregirlos.