Tipos de ítem personalizados

Los tipos de ítem personalizados permiten que tu cuenta defina sus propios tipos de documento, cada uno con procesos configurables de clasificación, validación y extracción. Trébol gestiona el ciclo de vida completo a través del endpoint /v2/custom-item-types.

Cuándo usarlos

Usa tipos de ítem personalizados cuando necesites:

Procesar un tipo de ítem que Trébol no soporta de forma estándar.
Definir reglas de clasificación, validación o extracción específicas para tu negocio.
Controlar el esquema de salida (JSON) de la extracción.

Esta funcionalidad complementa las extracciones personalizadas. Las extracciones personalizadas aplican sobre tipos ya soportados; los tipos de ítem personalizados crean un tipo nuevo desde cero.

Conceptos clave

Tipo y procesos

Un tipo de ítem personalizado (custom_item_type) agrupa uno o más procesos. Cada proceso define una tarea que Trébol ejecuta sobre el documento:

Proceso	Descripción	Cardinalidad
`classification`	Describe el documento para que Trébol lo identifique al clasificar.	Exactamente 1 por tipo
`validation`	Define una regla de validación. Cada regla tiene su propio `process_reference`.	Hasta 20 por tipo
`extraction`	Define campos a extraer y produce un `json_schema` de salida.	Hasta 5 por tipo

Al crear un tipo, el proceso de clasificación se crea automáticamente de forma atómica. Solo puede editarse mediante PATCH; no puede añadirse de nuevo ni eliminarse.

Identificadores

Cada tipo y cada proceso exponen dos identificadores:

id — generado por Trébol, inmutable. Úsalo en las rutas de la API (ej. cit_abc123, ccp_def456).
name (solo en tipos) — identificador que defines tú (no una etiqueta legible; para eso está friendly_name). Debe empezar con el prefijo cit_ y no puede contener espacios (usa _ o - como separador). Único por cuenta entre tipos activos y archivados. Se usa como valor de type al enviar ítems en verificaciones.
process_reference (solo en procesos) — etiqueta elegida por ti, única dentro del mismo tipo. Editable vía PATCH. Identifica el resultado de ese proceso dentro del ítem procesado (ver Dónde salen los resultados).

Ciclo de vida

active — el tipo acepta documentos en verificaciones.
archived — el tipo está pausado. Sigue apareciendo en el listado y puede reactivarse en cualquier momento con PATCH status: "active". Verificaciones que lo referencien son rechazadas mientras esté archivado.
Eliminado (DELETE) — el tipo y todos sus procesos se borran de forma permanente e irreversible. Para pausar un tipo sin perderlo, archívalo en lugar de eliminarlo.

Mejora automática

Al crear o actualizar un proceso puedes incluir auto_improve (por defecto true). Cuando está activo, Trébol mejora automáticamente tus instrucciones con IA en segundo plano para todos los tipos de proceso. Para procesos de extracción, también genera un json_schema.

Extracción con `json_schema` propio

Si proporcionas un json_schema al crear o actualizar un proceso de extracción, auto_improve se establece automáticamente en false. Enviar auto_improve: true junto con json_schema devuelve error 400: cuando defines tu propio esquema, Trébol lo usa tal cual sin modificarlo. Esto aplica tanto en la creación (POST) como en la actualización (PATCH) del proceso.

Al crear un proceso de extracción tienes dos caminos:

Sin json_schema: auto_improve debe enviarse como true (o se omite y toma ese valor por defecto). Trébol genera el esquema automáticamente. auto_improve: false sin json_schema devuelve error 400.
Con json_schema: auto_improve se establece en false automáticamente. Enviar auto_improve: true devuelve error 400. Trébol usa tu esquema tal cual.

Autenticación

Todos los endpoints requieren tu API key en el header x-api-key.

Referencia de la API

Todos los endpoints, parámetros, ejemplos de request/response y códigos de error están documentados en la API Reference:

Tipos

Crear un tipo

POST /v2/custom-item-types

Listar tipos

GET /v2/custom-item-types

Obtener un tipo

GET /v2/custom-item-types/{id}

Actualizar un tipo

PATCH /v2/custom-item-types/{id}

Eliminar un tipo

DELETE /v2/custom-item-types/{id}

Procesos

Agregar un proceso

POST /v2/custom-item-types/{id}/processes

Obtener un proceso

GET /v2/custom-item-types/{id}/processes/{processId}

Actualizar un proceso

PATCH /v2/custom-item-types/{id}/processes/{processId}

Eliminar un proceso

DELETE /v2/custom-item-types/{id}/processes/{processId}

Procesamiento asíncrono

Cuando creas o actualizas un proceso con auto_improve = true, Trébol no bloquea la respuesta. En su lugar:

Respuesta inmediata

El endpoint devuelve 201 (creación) o 200 (actualización). La respuesta de escritura no incluye user_input ni json_schema.

Mejora en segundo plano

Trébol mejora tus instrucciones con IA para todos los tipos de proceso. Para procesos de extracción, también genera un json_schema.

Resultado disponible vía GET (extracción)

Para procesos de extracción, consulta el proceso con GET hasta que json_schema esté poblado. Para clasificación y validación, el proceso es funcional de inmediato con tus instrucciones originales.

Cómo saber cuándo terminó la mejora

El mecanismo varía según el tipo de proceso:

Tipo de proceso	Señal de finalización
Extracción	El GET del proceso devuelve `json_schema` poblado (no `null`). Espera a que esté disponible antes de enviar documentos.
Clasificación y validación	No hay señal pública de que la mejora terminó. Trébol usa tus instrucciones originales de inmediato y, cuando la mejora finaliza, cambia internamente a las instrucciones mejoradas.

Si proporcionas tu propio json_schema al crear o actualizar el proceso, no hay espera asíncrona: Trébol lo usa de inmediato y el proceso queda listo para recibir documentos. Solo necesitas esperar a que json_schema se pueble cuando dejas que la mejora automática lo genere (auto_improve: true sin json_schema).

Estructura del `json_schema`

El json_schema sigue el formato JSON Schema y define los campos que Trébol extrae del documento. La raíz debe ser un objeto ("type": "object") con properties y, opcionalmente, required.

Reglas

Raíz: siempre "type": "object".
Tipos permitidos: string, number, integer, boolean, array, object, null.
Campos obligatorios: lista las claves en required para que Trébol siempre intente extraerlas.
Campos anulables: usa "type": ["<tipo>", "null"] en campos donde el documento podría no contener la información. Trébol devuelve null en lugar de inventar un valor.
Descripciones: cada campo debe incluir description para que Trébol entienda qué buscar en el documento.

Ejemplo: esquema plano

Extrae datos básicos de un contrato con campos que pueden no estar presentes:

{
  "type": "object",
  "required": ["tenant_name", "monthly_rent"],
  "properties": {
    "tenant_name": {
      "type": "string",
      "description": "Nombre completo del arrendatario."
    },
    "monthly_rent": {
      "type": "number",
      "description": "Monto de la renta mensual en la moneda del contrato."
    },
    "start_date": {
      "type": ["string", "null"],
      "description": "Fecha de inicio del contrato en formato YYYY-MM-DD. Usa null si no se indica."
    },
    "contract_duration_months": {
      "type": ["integer", "null"],
      "description": "Duración del contrato en meses. Usa null si no se especifica."
    }
  }
}

Ejemplo: esquema con arrays y objetos anidados

Extrae una lista de personas con sus roles:

{
  "type": "object",
  "required": ["persons"],
  "properties": {
    "persons": {
      "type": "array",
      "description": "Lista de todas las personas mencionadas en el documento.",
      "items": {
        "type": "object",
        "required": ["name", "role"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Nombre completo de la persona mencionada en el documento."
          },
          "role": {
            "type": ["string", "null"],
            "description": "Rol, cargo o calidad con la que la persona aparece en el documento. Usa null si no se especifica."
          }
        }
      }
    }
  }
}

Ejemplo: esquema mixto con campos opcionales

Extrae información financiera donde algunos campos son opcionales:

{
  "type": "object",
  "required": ["company_name", "total_revenue"],
  "properties": {
    "company_name": {
      "type": "string",
      "description": "Razón social o nombre comercial de la empresa."
    },
    "total_revenue": {
      "type": "number",
      "description": "Ingreso total reportado en el documento."
    },
    "currency": {
      "type": ["string", "null"],
      "description": "Código de moneda ISO 4217 (ej. MXN, USD). Usa null si no se especifica."
    },
    "line_items": {
      "type": "array",
      "description": "Desglose de conceptos o partidas del documento.",
      "items": {
        "type": "object",
        "required": ["description", "amount"],
        "properties": {
          "description": {
            "type": "string",
            "description": "Descripción del concepto o partida."
          },
          "amount": {
            "type": "number",
            "description": "Monto del concepto."
          },
          "tax_included": {
            "type": ["boolean", "null"],
            "description": "Indica si el monto incluye impuestos. Usa null si no se especifica."
          }
        }
      }
    }
  }
}

El json_schema define la estructura que Trébol usa para la extracción. Un esquema incorrecto o con descripciones vagas produce resultados imprecisos. Incluye siempre descripciones claras que indiquen exactamente qué dato buscar en el documento.

Ejemplo: crear un proceso de extracción con `json_schema`

Este ejemplo crea un proceso de extracción proporcionando un json_schema que usa el esquema de personas con campos anulables. Como se envía json_schema, auto_improve se establece en false automáticamente.

curl -X POST https://api.gotrebol.com/v2/custom-item-types/cit_abc123/processes \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "process_type": "extraction",
    "process_reference": "extraer_personas",
    "user_input": "Extrae todas las personas mencionadas en el documento con su nombre completo y rol.",
    "json_schema": {
      "type": "object",
      "required": ["persons"],
      "properties": {
        "persons": {
          "type": "array",
          "description": "Lista de todas las personas mencionadas en el documento.",
          "items": {
            "type": "object",
            "required": ["name", "role"],
            "properties": {
              "name": {
                "type": "string",
                "description": "Nombre completo de la persona mencionada en el documento."
              },
              "role": {
                "type": ["string", "null"],
                "description": "Rol, cargo o calidad con la que la persona aparece en el documento. Usa null si no se especifica."
              }
            }
          }
        }
      }
    }
  }'

Usa "type": ["string", "null"] (o ["number", "null"], etc.) en los campos que podrían no encontrarse en el documento. Así Trébol devuelve null en lugar de inventar un valor cuando no hay coincidencia.

Interacción con verificaciones

Envío de ítems

Al enviar un ítem de verificación que referencia un tipo de ítem personalizado:

El name debe corresponder a un tipo existente en tu cuenta (activo o archivado).
El tipo debe tener status = 'active'.

Código	Causa	Acción
400	El `name` no corresponde a ningún tipo de la cuenta	Verifica que el tipo existe
422	El tipo tiene `status = 'archived'`	Reactiva el tipo con PATCH `status: "active"`

Dónde salen los resultados

Los resultados de un ítem de tipo personalizado viven en item_value.pipeline, dentro del ítem. Léelo con cualquiera de estos endpoints:

Obtener un item de verificación por ID — GET /verification-items/{id}
Obtener una verificación por su ID — GET /verifications/{verification-id}, con los ítems en items[]

item_value tiene esta forma:

{
  "current_stage": "extraction",
  "pipeline": {
    "validation": [
      {
        "process_reference": "validar_firmas",
        "executed": true,
        "execution_result": true,
        "value": {
          "identifier": "activeVersionId_87",
          "validation_result": true,
          "explanation": "El contrato está firmado por ambas partes."
        }
      }
    ],
    "extraction": [
      {
        "process_reference": "extraer_datos_contrato",
        "executed": true,
        "execution_result": "success",
        "value": {
          "landlord_name": "María López García",
          "monthly_rent": 15000
        }
      }
    ]
  }
}

array

Un elemento por proceso de extracción configurado en el tipo. Array vacío si el tipo no tiene extracciones.

Show campos de cada elemento

string

La etiqueta que le diste al proceso. Es lo que identifica cada resultado.

boolean

true cuando el proceso llegó a ejecutarse para este ítem.

string

success o error. Solo aparece cuando executed es true.

object | null

El JSON extraído. Sus claves son las properties del json_schema de la versión que se ejecutó. Es null cuando el proceso no se ejecutó o terminó en error.

array

Un elemento por regla de validación configurada en el tipo. Array vacío si el tipo no tiene validaciones.

Show campos de cada elemento

string

La etiqueta que le diste a la regla.

boolean

true cuando la regla llegó a evaluarse para este ítem.

boolean

true si la regla se cumplió, false si no. Solo aparece cuando executed es true.

object | null

Detalle de la evaluación: identifier, validation_result, explanation y, según la regla, variable_name, variable_value, reference_value y applied_rule. Es null cuando la regla no se evaluó o la llamada falló.

string

Etapa del pipeline interno en la que quedó el ítem. Es informativa y su lista de valores no es estable. Para saber si el ítem terminó, usa item_status junto con item_error.

Los tipos de ítem personalizados no usan llaves cp_<...>. Ese prefijo es exclusivo de las extracciones personalizadas, que aplican sobre tipos de documento estándar. Un ítem cit_* sí aparece en la sección sources de los endpoints v2, pero solo con sus campos comunes (id, type, item_status, …): esa sección no expone su item_value. Sus resultados se leen únicamente desde el ítem.

Trébol elimina de cada value de extracción, en todos los niveles, las claves que empiezan por paragraphs_ o parrafos_. Son trazas internas de citas y no forman parte de tu esquema.

Ejemplo completo

Este ejemplo crea un tipo de ítem personalizado para contratos de arrendamiento, le agrega una extracción y luego envía un documento para procesar.

Crear el tipo

curl -X POST https://api.gotrebol.com/v2/custom-item-types \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cit_contrato_arrendamiento",
    "user_input": "Este documento es un contrato de arrendamiento inmobiliario.",
    "friendly_name": "Contrato de arrendamiento"
  }'

Agregar un proceso de extracción

Usa el id del tipo devuelto en el paso 1 (aquí cit_abc123). Tienes dos opciones:

Con auto_improve (sin json_schema)
Con json_schema propio

curl -X POST https://api.gotrebol.com/v2/custom-item-types/cit_abc123/processes \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "process_type": "extraction",
    "process_reference": "extraer_datos_contrato",
    "user_input": "Extrae: nombre del arrendador, nombre del arrendatario, monto de renta mensual, fecha de inicio y duración del contrato.",
    "auto_improve": true
  }'

Trébol genera el json_schema automáticamente. Necesitas esperar a que esté listo (paso 3).

curl -X POST https://api.gotrebol.com/v2/custom-item-types/cit_abc123/processes \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "process_type": "extraction",
    "process_reference": "extraer_datos_contrato",
    "user_input": "Extrae: nombre del arrendador, nombre del arrendatario, monto de renta mensual, fecha de inicio y duración del contrato.",
    "json_schema": {
      "type": "object",
      "required": ["landlord_name", "tenant_name", "monthly_rent"],
      "properties": {
        "landlord_name": {
          "type": "string",
          "description": "Nombre completo del arrendador."
        },
        "tenant_name": {
          "type": "string",
          "description": "Nombre completo del arrendatario."
        },
        "monthly_rent": {
          "type": "number",
          "description": "Monto de la renta mensual."
        },
        "start_date": {
          "type": ["string", "null"],
          "description": "Fecha de inicio del contrato en formato YYYY-MM-DD. Usa null si no se indica."
        },
        "contract_duration": {
          "type": ["string", "null"],
          "description": "Duración del contrato (ej. 12 meses). Usa null si no se especifica."
        }
      }
    }
  }'

El proceso queda listo de inmediato. Puedes saltar el paso 3 y enviar documentos directamente.

La respuesta incluye el id del proceso creado (por ejemplo, ccp_ghi789). Lo necesitas en el siguiente paso.

Esperar la mejora automática (solo si no enviaste json_schema)

Si creaste el proceso con auto_improve: true (sin json_schema), consulta el proceso con GET hasta que json_schema esté poblado. Si proporcionaste tu propio json_schema, salta este paso.

curl https://api.gotrebol.com/v2/custom-item-types/cit_abc123/processes/ccp_ghi789 \
  -H "x-api-key: YOUR_API_KEY"

Enviar un documento para procesar

Crea una verificación usando el name del tipo como type del ítem.

curl -X POST https://api.gotrebol.com/verifications \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "mx",
    "tag": "empresa-ejemplo-001",
    "items": [
      {
        "type": "cit_contrato_arrendamiento",
        "options": {
          "file_url": "https://ejemplo.com/contrato.pdf"
        }
      }
    ]
  }'

Consultar los resultados

Una vez que la verificación termine de procesarse (puedes saberlo vía webhook), lee el ítem con GET /verification-items/{id}. Los resultados están en item_value.pipeline.extraction: un elemento por proceso de extracción, identificado por su process_reference.

Resultado con auto_improve
Resultado con json_schema propio

{
  "item_type": "cit_contrato_arrendamiento",
  "item_status": "complete",
  "item_value": {
    "current_stage": "extraction",
    "pipeline": {
      "validation": [],
      "extraction": [
        {
          "process_reference": "extraer_datos_contrato",
          "executed": true,
          "execution_result": "success",
          "value": {
            "nombre_arrendador": "María López García",
            "nombre_arrendatario": "Carlos Ramírez Soto",
            "renta_mensual": 15000,
            "fecha_inicio": "2026-02-01",
            "duracion_contrato": "12 meses"
          }
        }
      ]
    }
  }
}

Las claves de value las define el json_schema que Trébol generó automáticamente en el paso 3.

{
  "item_type": "cit_contrato_arrendamiento",
  "item_status": "complete",
  "item_value": {
    "current_stage": "extraction",
    "pipeline": {
      "validation": [],
      "extraction": [
        {
          "process_reference": "extraer_datos_contrato",
          "executed": true,
          "execution_result": "success",
          "value": {
            "landlord_name": "María López García",
            "tenant_name": "Carlos Ramírez Soto",
            "monthly_rent": 15000,
            "start_date": "2026-02-01",
            "contract_duration": "12 meses"
          }
        }
      ]
    }
  }
}

Las claves de value coinciden exactamente con las properties del json_schema que definiste en el paso 2.

El contrato completo, campo por campo, está en Dónde salen los resultados.

Siguientes pasos

Extracciones personalizadas

Personaliza la extracción para tipos de documento que Trébol ya soporta.

Divisor de documentos

Divide un PDF con varios documentos y usa tus tipos personalizados (cit_*) como destino de cada corte.

Reglas de validación

Reglas predefinidas y personalizadas para validar documentos.

Tipos de documentos

Lista completa de tipos de documento soportados.

Webhooks

Recibe notificaciones cuando una verificación termine de procesarse.

​Cuándo usarlos

​Conceptos clave

​Tipo y procesos

​Identificadores

​Ciclo de vida

​Mejora automática

​Extracción con json_schema propio

​Autenticación

​Referencia de la API

​Tipos

Crear un tipo

Listar tipos

Obtener un tipo

Actualizar un tipo

Eliminar un tipo

​Procesos

Agregar un proceso

Obtener un proceso

Actualizar un proceso

Eliminar un proceso

​Procesamiento asíncrono

​Cómo saber cuándo terminó la mejora

​Estructura del json_schema

​Reglas

​Ejemplo: esquema plano

​Ejemplo: esquema con arrays y objetos anidados

​Ejemplo: esquema mixto con campos opcionales

​Ejemplo: crear un proceso de extracción con json_schema

​Interacción con verificaciones

​Envío de ítems

​Dónde salen los resultados

​Ejemplo completo

​Siguientes pasos

Extracciones personalizadas

Divisor de documentos

Reglas de validación

Tipos de documentos

Webhooks

Cuándo usarlos

Conceptos clave

Tipo y procesos

Identificadores

Ciclo de vida

Mejora automática

Extracción con `json_schema` propio

Autenticación

Referencia de la API

Tipos

Procesos

Procesamiento asíncrono

Cómo saber cuándo terminó la mejora

Estructura del `json_schema`

Reglas

Ejemplo: esquema plano

Ejemplo: esquema con arrays y objetos anidados

Ejemplo: esquema mixto con campos opcionales

Ejemplo: crear un proceso de extracción con `json_schema`

Interacción con verificaciones

Envío de ítems

Dónde salen los resultados

Ejemplo completo

Siguientes pasos