Tipos de ítem personalizados

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 firmado ante notario.",
    "friendly_name": "Contrato de arrendamiento"
  }'

const response = await fetch("https://api.gotrebol.com/v2/custom-item-types", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "cit_contrato_arrendamiento",
    user_input:
      "Este documento es un contrato de arrendamiento inmobiliario firmado ante notario.",
    friendly_name: "Contrato de arrendamiento",
  }),
});

import requests

response = requests.post(
    "https://api.gotrebol.com/v2/custom-item-types",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "name": "cit_contrato_arrendamiento",
        "user_input": "Este documento es un contrato de arrendamiento inmobiliario firmado ante notario.",
        "friendly_name": "Contrato de arrendamiento",
    },
)

{
  "success": true,
  "data": {
    "id": "cit_abc123",
    "name": "cit_contrato_arrendamiento",
    "friendly_name": "Contrato de arrendamiento",
    "status": "active",
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-01-15T10:00:00.000Z",
    "processes": [
      {
        "id": "ccp_def456",
        "process_reference": "cit_contrato_arrendamiento_classification",
        "process_type": "classification",
        "is_active": true,
        "failure_policy": null,
        "active_version_id": 42,
        "version_number": 1,
        "created_at": "2026-01-15T10:00:00.000Z",
        "updated_at": "2026-01-15T10:00:00.000Z"
      }
    ]
  }
}

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.

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.

Al crear un proceso de extracción no puedes enviar json_schema: en la creación el esquema lo genera la mejora automática, por eso auto_improve no se puede desactivar (auto_improve: false devuelve error 400). Si quieres definir o ajustar el esquema manualmente, hazlo después con un PATCH sobre el proceso (campo json_schema).

Autenticación

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

Crear un tipo

string

required

Identificador del tipo de documento que defines tú. Debe empezar con cit_ y no puede contener espacios (usa _ o - como separador; ej. "cit_contrato_arrendamiento"). Único por cuenta entre tipos activos y archivados.

string

required

Instrucciones para identificar este tipo de documento.

string

required

Nombre legible para interfaces. Entre 2 y 255 caracteres.

boolean

default:"true"

Cuando es false, Trébol usa tus instrucciones tal cual, sin mejora automática.

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 firmado ante notario.",
    "friendly_name": "Contrato de arrendamiento"
  }'

const response = await fetch("https://api.gotrebol.com/v2/custom-item-types", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "cit_contrato_arrendamiento",
    user_input:
      "Este documento es un contrato de arrendamiento inmobiliario firmado ante notario.",
    friendly_name: "Contrato de arrendamiento",
  }),
});

import requests

response = requests.post(
    "https://api.gotrebol.com/v2/custom-item-types",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "name": "cit_contrato_arrendamiento",
        "user_input": "Este documento es un contrato de arrendamiento inmobiliario firmado ante notario.",
        "friendly_name": "Contrato de arrendamiento",
    },
)

Respuesta (201)

boolean

required

Indica si la operación se completó correctamente.

object

required

Tipo de ítem personalizado creado.

Show Propiedades de data

string

Identificador único generado por Trébol (ej. cit_abc123).

string

Clave del tipo asignada en la creación.

string

Nombre legible para interfaces.

string

Estado del tipo: active o archived.

string

Fecha de creación en formato ISO 8601.

string

Fecha de última actualización en formato ISO 8601.

array

Procesos vinculados al tipo.

Show Propiedades del proceso

string

Identificador único del proceso (ej. ccp_def456).

string

Etiqueta del proceso asignada por el usuario.

string

Tipo de proceso: classification, validation o extraction.

boolean

Indica si el proceso está activo.

string | null

Política de fallo para validaciones. warning: el ítem se pausa hasta que se revise el resultado. hard_stop: si la regla no se cumple, el ítem se da por finalizado. null: el ítem continúa procesándose aunque la regla falle. Para clasificación y extracción siempre es null.

integer | null

ID de la versión activa del proceso.

integer

Número secuencial de la versión activa.

string

Fecha de creación del proceso.

string

Fecha de última actualización del proceso.

{
  "success": true,
  "data": {
    "id": "cit_abc123",
    "name": "cit_contrato_arrendamiento",
    "friendly_name": "Contrato de arrendamiento",
    "status": "active",
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-01-15T10:00:00.000Z",
    "processes": [
      {
        "id": "ccp_def456",
        "process_reference": "cit_contrato_arrendamiento_classification",
        "process_type": "classification",
        "is_active": true,
        "failure_policy": null,
        "active_version_id": 42,
        "version_number": 1,
        "created_at": "2026-01-15T10:00:00.000Z",
        "updated_at": "2026-01-15T10:00:00.000Z"
      }
    ]
  }
}

Las respuestas de escritura (POST / PATCH) no incluyen user_input ni json_schema en los procesos. Usa GET para leer el contenido completo de cada proceso.

La respuesta incluye un proceso de clasificación que Trébol crea junto con el tipo. Su process_reference se genera automáticamente como <name>_classification (por eso no lo envías al crear): es estable y predecible. No cambia si más adelante renombras el tipo, y —como cualquier proceso— puedes renombrarlo con PATCH, aunque normalmente no hace falta.

Errores

Código	Condición
400	`name`, `user_input` o `friendly_name` faltante o inválido
400	`name` no empieza con `cit_` o contiene espacios
400	`friendly_name` fuera del rango de 2 a 255 caracteres
409	`name` ya existe en la cuenta (entre tipos activos y archivados)

Listar tipos

GET /v2/custom-item-types

Devuelve todos los tipos de tu cuenta (activos y archivados) con sus procesos. Ordenados por fecha de creación descendente. Tamaño de página fijo: 10.

string

Token de cursor para obtener la siguiente página. Devuelto en la respuesta cuando hay más resultados.

Respuesta (200)

boolean

required

Indica si la operación se completó correctamente.

array

required

Lista de tipos de ítem personalizados de la cuenta (activos y archivados).

Show Propiedades de cada tipo

string

Identificador único del tipo.

string

Clave del tipo.

string

Nombre legible para interfaces.

string

Estado del tipo: active o archived.

string

Fecha de creación en formato ISO 8601.

string

Fecha de última actualización en formato ISO 8601.

array

Procesos vinculados al tipo. En respuestas GET incluye user_input y json_schema.

Show Propiedades del proceso

string

Identificador único del proceso.

string

Etiqueta del proceso.

string

Tipo de proceso: classification, validation o extraction.

boolean

Indica si el proceso está activo.

string | null

integer | null

ID de la versión activa.

integer

Número secuencial de la versión activa.

string

Instrucciones del proceso (solo en respuestas GET).

object | null

Esquema JSON de salida para procesos de extracción (solo en respuestas GET).

string

Fecha de creación del proceso.

string

Fecha de última actualización del proceso.

string

Token de cursor para la siguiente página. Solo presente cuando hay más resultados.

{
  "success": true,
  "data": [
    {
      "id": "cit_abc123",
      "name": "cit_contrato_arrendamiento",
      "friendly_name": "Contrato de arrendamiento",
      "status": "active",
      "created_at": "...",
      "updated_at": "...",
      "processes": [
        {
          "id": "ccp_def456",
          "process_reference": "cit_contrato_arrendamiento_classification",
          "process_type": "classification",
          "is_active": true,
          "failure_policy": null,
          "active_version_id": 42,
          "version_number": 1,
          "user_input": "Este documento es un contrato de arrendamiento...",
          "json_schema": null,
          "created_at": "...",
          "updated_at": "..."
        }
      ]
    }
  ],
  "next": "eyJjcmVhdGVkQXQiOi..."
}

Las respuestas de lectura (GET) incluyen user_input y json_schema en cada proceso.

Obtener un tipo

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

Devuelve un tipo con todos sus procesos. Misma estructura que un elemento individual del listado. Los tipos archivados se devuelven normalmente.

Código	Condición
404	Tipo no encontrado

Actualizar un tipo

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

Actualiza campos del tipo. Debes enviar al menos un campo.

string

Renombra el tipo. No puede contener espacios. Única por cuenta entre tipos activos y archivados.

string

Actualiza el nombre legible. Entre 2 y 255 caracteres.

string

Estado del tipo. Valores permitidos:

"archived": pausa el tipo. Sigue apareciendo en el listado y puede reactivarse en cualquier momento.
"active": reactiva un tipo archivado.

Para pausar un tipo temporalmente usa status: "archived" (es reversible). Para borrarlo de forma permanente, usa Eliminar un tipo.

# Archivar un tipo (pausarlo). Para reactivarlo, envía "active".
curl -X PATCH https://api.gotrebol.com/v2/custom-item-types/cit_abc123 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "archived" }'

const response = await fetch(
  "https://api.gotrebol.com/v2/custom-item-types/cit_abc123",
  {
    method: "PATCH",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    // Para reactivarlo: { status: "active" }
    body: JSON.stringify({ status: "archived" }),
  }
);

import requests

response = requests.patch(
    "https://api.gotrebol.com/v2/custom-item-types/cit_abc123",
    headers={"x-api-key": "YOUR_API_KEY"},
    # Para reactivarlo: {"status": "active"}
    json={"status": "archived"},
)

Respuesta (200)

Devuelve solo los campos del tipo, sin procesos.

boolean

required

Indica si la operación se completó correctamente.

object

required

Tipo actualizado (sin procesos).

Show Propiedades de data

string

Identificador único del tipo.

string

Clave del tipo.

string

Nombre legible para interfaces.

string

Estado actual: active o archived.

string

Fecha de creación en formato ISO 8601.

string

Fecha de última actualización en formato ISO 8601.

{
  "success": true,
  "data": {
    "id": "cit_abc123",
    "name": "cit_contrato_arrendamiento_v2",
    "friendly_name": "Contrato de arrendamiento",
    "status": "archived",
    "created_at": "...",
    "updated_at": "..."
  }
}

Errores

Código	Condición
400	Ningún campo proporcionado, valor inválido o `name` vacío
400	`status` con valor no permitido (solo `"active"` o `"archived"`)
400	`friendly_name` fuera del rango de 2 a 255 caracteres
404	Tipo no encontrado
409	`name` colisiona con otro tipo activo o archivado de la cuenta

Si los valores enviados ya coinciden con los actuales, el recurso no cambia y updated_at se mantiene.

Eliminar un tipo

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

Elimina el tipo de forma permanente e irreversible, junto con todos sus procesos.

Esta operación no se puede deshacer. Para pausar un tipo sin perderlo (y poder reactivarlo después), archívalo con PATCH status: "archived" en lugar de eliminarlo.

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

const response = await fetch(
  "https://api.gotrebol.com/v2/custom-item-types/cit_abc123",
  {
    method: "DELETE",
    headers: { "x-api-key": "YOUR_API_KEY" },
  }
);

import requests

response = requests.delete(
    "https://api.gotrebol.com/v2/custom-item-types/cit_abc123",
    headers={"x-api-key": "YOUR_API_KEY"},
)

Respuesta (200)

boolean

required

Indica si la operación se completó correctamente.

object

required

Contiene el identificador del tipo eliminado.

Show Propiedades de data

string

Identificador único del tipo eliminado.

{
  "success": true,
  "data": { "id": "cit_abc123" }
}

Código	Condición
401	No autorizado. API key inválida o faltante
404	Tipo no encontrado o ya eliminado

Agregar un proceso

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

Agrega un proceso de validación o extracción a un tipo existente. Hasta 5 procesos de extracción y 20 de validación por tipo.

string

required

"validation" o "extraction".

string

required

Etiqueta del proceso. Única dentro del mismo tipo.

string

required

Instrucciones escritas por ti para este proceso.

boolean

Para procesos de extracción, debe enviarse como true (enviar false devuelve error 400: en la creación el json_schema lo genera la mejora automática y no se acepta enviarlo en esta petición; para definirlo manualmente, usa un PATCH posterior). Para procesos de validación, es opcional (por defecto true).

string | null

Solo para validación. "warning": el ítem se pausa hasta que se revise el resultado. "hard_stop": si la regla no se cumple, el ítem se da por finalizado. null: el ítem continúa procesándose aunque la regla falle. Se rechaza si se envía en otro tipo de proceso.

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_montos",
    "user_input": "Extrae todos los montos monetarios del contrato, incluyendo renta mensual y depósito.",
    "auto_improve": true
  }'

const response = await fetch(
  "https://api.gotrebol.com/v2/custom-item-types/cit_abc123/processes",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      process_type: "extraction",
      process_reference: "extraer_montos",
      user_input:
        "Extrae todos los montos monetarios del contrato, incluyendo renta mensual y depósito.",
      auto_improve: true,
    }),
  }
);

import requests

response = requests.post(
    "https://api.gotrebol.com/v2/custom-item-types/cit_abc123/processes",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "process_type": "extraction",
        "process_reference": "extraer_montos",
        "user_input": "Extrae todos los montos monetarios del contrato, incluyendo renta mensual y depósito.",
        "auto_improve": True,
    },
)

Respuesta (201)

boolean

required

Indica si la operación se completó correctamente.

object

required

Proceso creado.

Show Propiedades de data

string

Identificador único del proceso (ej. ccp_ghi789).

string

Etiqueta del proceso.

string

Tipo de proceso: classification, validation o extraction.

boolean

Indica si el proceso está activo.

string | null

integer | null

ID de la versión activa del proceso.

integer

Número secuencial de la versión activa.

string

Fecha de creación del proceso.

string

Fecha de última actualización del proceso.

{
  "success": true,
  "data": {
    "id": "ccp_ghi789",
    "process_reference": "extraer_montos",
    "process_type": "extraction",
    "is_active": true,
    "failure_policy": null,
    "active_version_id": 99,
    "version_number": 1,
    "created_at": "...",
    "updated_at": "..."
  }
}

Errores

Código	Condición
400	Campos requeridos faltantes o inválidos
400	`auto_improve: false` en un proceso de extracción
400	`failure_policy` enviado en un proceso que no es de validación
404	Tipo padre no encontrado o eliminado
409	`process_reference` ya existe en este tipo
409	`user_input` idéntico ya en uso en otro proceso del mismo tipo
409	Se alcanzó el límite de procesos (5 de extracción o 20 de validación)

Ejemplo: proceso de validación con `failure_policy`

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": "validation",
    "process_reference": "validar_firmas",
    "user_input": "Verifica que el contrato contenga las firmas de ambas partes y del notario público.",
    "failure_policy": "hard_stop"
  }'

Ejemplo de respuesta de error

Cuando ocurre un conflicto (por ejemplo, process_reference duplicado), la respuesta sigue esta estructura:

{
  "success": false,
  "message": "process with identifier 'validar_firmas' already exists.",
  "code": "DUPLICATE_RESOURCE",
  "timestamp": "2026-01-15T10:00:00.000Z"
}

Obtener un proceso

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

Devuelve un proceso con su versión activa, incluyendo user_input y json_schema.

Respuesta (200)

boolean

required

Indica si la operación se completó correctamente.

object

required

Proceso con su versión activa.

Show Propiedades de data

string

Identificador único del proceso.

string

Etiqueta del proceso.

string

Tipo de proceso: classification, validation o extraction.

boolean

Indica si el proceso está activo.

string | null

integer | null

ID de la versión activa.

integer

Número secuencial de la versión activa.

string

Instrucciones escritas por el usuario para este proceso.

object | null

Esquema JSON de salida. Solo presente en procesos de extracción.

Show Propiedades del json_schema

string

Tipo raíz del esquema (generalmente object).

object

Campos definidos en el esquema con su tipo y descripción.

array

Lista de campos obligatorios.

string

Fecha de creación del proceso.

string

Fecha de última actualización del proceso.

{
  "success": true,
  "data": {
    "id": "ccp_ghi789",
    "process_reference": "extraer_montos",
    "process_type": "extraction",
    "is_active": true,
    "failure_policy": null,
    "active_version_id": 99,
    "version_number": 1,
    "user_input": "Extrae todos los montos monetarios del contrato...",
    "json_schema": {
      "type": "object",
      "properties": {
        "renta_mensual": { "type": "number", "description": "Monto de la renta mensual" },
        "deposito": { "type": "number", "description": "Monto del depósito" }
      },
      "required": ["renta_mensual", "deposito"]
    },
    "created_at": "...",
    "updated_at": "..."
  }
}

Resolución

Para que el GET responda correctamente:

La clasificación existe y no está archivado.
El proceso existe y no está eliminado.
La versión activa del proceso tiene user_input no nulo.

Si alguna condición falla, Trébol devuelve 404.

Tipos archivados (status: "archived") devuelven 404 al consultar sus procesos, aunque el tipo en sí siga siendo consultable via GET /v2/custom-item-types/{id}.

Actualizar un proceso

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

Actualiza un proceso. Debes enviar al menos un campo. process_type y id no se pueden cambiar.

string

Renombra la etiqueta. Única dentro del mismo tipo.

boolean

Activa o pausa el proceso sin eliminarlo. El proceso de clasificación no se puede pausar.

string

Nuevas instrucciones. Si el texto difiere del valor activo, se crea una nueva versión del proceso que pasa a ser la activa.

object

Solo para procesos de extracción. Define el esquema JSON de salida. Enviarlo crea una nueva versión del proceso. Enviarlo en un proceso que no es de extracción devuelve 400.

boolean

default:"true"

Solo aplica cuando cambias user_input. Si es false, Trébol no ejecuta mejora automática y conserva tus instrucciones tal cual.

string | null

curl -X PATCH https://api.gotrebol.com/v2/custom-item-types/cit_abc123/processes/ccp_ghi789 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "Extrae todos los montos monetarios del contrato: renta mensual, depósito, penalización por mora y total anual.",
    "auto_improve": true
  }'

const response = await fetch(
  "https://api.gotrebol.com/v2/custom-item-types/cit_abc123/processes/ccp_ghi789",
  {
    method: "PATCH",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      user_input:
        "Extrae todos los montos monetarios del contrato: renta mensual, depósito, penalización por mora y total anual.",
      auto_improve: true,
    }),
  }
);

import requests

response = requests.patch(
    "https://api.gotrebol.com/v2/custom-item-types/cit_abc123/processes/ccp_ghi789",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "user_input": "Extrae todos los montos monetarios del contrato: renta mensual, depósito, penalización por mora y total anual.",
        "auto_improve": True,
    },
)

El proceso de clasificación se edita igual que cualquier otro: obtén su id con Obtener un tipo (es el proceso con process_type: "classification") y haz PATCH sobre /processes/{processId} cambiando su user_input.

Versiones del proceso

Cuando el PATCH modifica user_input (y el texto difiere del valor activo), Trébol crea una nueva versión del proceso, que pasa a ser la activa. Si auto_improve es true y cambias user_input, Trébol lanza la mejora automática en segundo plano.

Errores

Código	Condición
400	`failure_policy` con valor no nulo en un proceso que no es de validación
400	`json_schema` enviado en un proceso que no es de extracción, o con formato inválido
404	Tipo padre o proceso no encontrado
409	`process_reference` colisiona con otro proceso del mismo tipo
409	`user_input` idéntico ya usado en otro proceso del mismo tipo
409	Se intentó pausar (`is_active: false`) el proceso de clasificación

Eliminar un proceso

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

Elimina permanentemente un proceso de validación o extracción. El proceso de clasificación no puede eliminarse; intentarlo devuelve error 409. Para cambiar sus instrucciones, usa PATCH sobre el proceso.

Respuesta (200)

boolean

required

Indica si la operación se completó correctamente.

object

required

Contiene el identificador del proceso eliminado.

Show Propiedades de data

string

Identificador único del proceso eliminado.

{
  "success": true,
  "data": { "id": "ccp_ghi789" }
}

Código	Condición
404	Tipo padre no encontrado, o proceso no encontrado / ya eliminado
409	Intento de eliminar el proceso de clasificación

El proceso de clasificación no puede eliminarse. Usa PATCH para actualizar sus instrucciones.

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.

Normalmente el json_schema lo genera la mejora automática, pero también puedes definirlo tú con el campo json_schema en el PATCH del proceso (solo extracción). Otra opción para regenerarlo es cambiar el user_input con auto_improve: true para que Trébol produzca uno nuevo.

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"`

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).

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
  }'

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

Esperar la mejora automática

Como se trata de un proceso de extracción, consulta el proceso con GET usando el id del paso 2 hasta que json_schema esté poblado. Para clasificación y validación, Trébol usa tus instrucciones originales de inmediato y las reemplaza internamente por las mejoradas cuando la mejora termina.

# Sustituye ccp_ghi789 por el id devuelto en el paso 2
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), consulta los resultados de extracción con los endpoints v2 de lectura:

Obtener sección por etiqueta de empresa — GET /v2/companies/{etiqueta}/{section} con section=sources
Obtener sección por ID de verificación — GET /v2/verifications/{verification-id}/{entity} con entity=sources

Cada fuente incluye tus datos extraídos en el campo custom_user_prompts. Ese objeto usa el process_reference del proceso como clave. Ejemplo de fragmento en data.sources:

{
  "custom_user_prompts": {
    "extraer_datos_contrato": {
      "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"
    }
  }
}

La clave (extraer_datos_contrato) es el process_reference que asignaste al proceso de extracción en el paso 2. Como cada ítem de verificación pertenece a un solo tipo, las claves de custom_user_prompts de una fuente provienen siempre de ese único tipo; por eso basta con que el process_reference sea único dentro del tipo para que no haya colisiones.

Siguientes pasos

Extracciones personalizadas

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

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.

⌘I

​Cuándo usarlos

​Conceptos clave

​Tipo y procesos

​Identificadores

​Ciclo de vida

​Mejora automática

​Autenticación

​Crear un tipo

​Respuesta (201)

​Errores

​Listar tipos

​Respuesta (200)

​Obtener un tipo

​Actualizar un tipo

​Respuesta (200)

​Errores

​Eliminar un tipo

​Respuesta (200)

​Agregar un proceso

​Respuesta (201)

​Errores

​Ejemplo: proceso de validación con failure_policy

​Ejemplo de respuesta de error

​Obtener un proceso

​Respuesta (200)

​Resolución

​Actualizar un proceso

​Versiones del proceso

​Errores

​Eliminar un proceso

​Respuesta (200)

​Procesamiento asíncrono

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

​Interacción con verificaciones

​Envío de ítems

​Ejemplo completo

​Siguientes pasos

Extracciones personalizadas

Reglas de validación

Tipos de documentos

Webhooks

Cuándo usarlos

Conceptos clave

Tipo y procesos

Identificadores

Ciclo de vida

Mejora automática

Autenticación

Crear un tipo

Respuesta (201)

Errores

Listar tipos

Respuesta (200)

Obtener un tipo

Actualizar un tipo

Respuesta (200)

Errores

Eliminar un tipo

Respuesta (200)

Agregar un proceso

Respuesta (201)

Errores

Ejemplo: proceso de validación con `failure_policy`

Ejemplo de respuesta de error

Obtener un proceso

Respuesta (200)

Resolución

Actualizar un proceso

Versiones del proceso

Errores

Eliminar un proceso

Respuesta (200)

Procesamiento asíncrono

Cómo saber cuándo terminó la mejora

Interacción con verificaciones

Envío de ítems

Ejemplo completo

Siguientes pasos