> ## Documentation Index
> Fetch the complete documentation index at: https://gotrebol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Extracciones personalizadas

> Define instrucciones propias para extraer datos de tipos de documento en tu cuenta, activa una versión y consume los resultados por API o en plantillas.

Las **extracciones personalizadas** permiten que tu cuenta configure, para un tipo de documento concreto, instrucciones y un esquema de salida (JSON) distintos de la extracción estándar.
Trébol ejecuta ese procesamiento cuando corresponde y guarda el resultado junto al ítem de verificación.

## Cuándo usarlas

Usa las extracciones personalizadas cuando **ya existe una extracción estándar para el tipo de documento, pero tu caso necesita extraer campos adicionales o distintos a los que Trébol entrega por defecto**.

<Note>
  Esta funcionalidad permite personalizar la extracción de tipos de documento ya soportados por Trébol. Si necesitas crear un tipo de documento completamente nuevo, consulta la guía de [tipos de ítem personalizados](/docs/producto/guias/tipos-de-item-personalizados).
</Note>

## Cómo acceder

Desde la aplicación web, abre **Configuración** en el menú lateral izquierdo y selecciona **Extracciones personalizadas**. Esta opción solo es visible para usuarios con los permisos correspondientes ("extracciones personalizadas") asignados por el administrador de la cuenta.

## Qué puedes hacer en la aplicación

1. **Crear un procesamiento** y asignarle un **nombre** (identificador editable) y un **tipo de documento** al que aplica (por ejemplo, constancia fiscal, acta, etc.).
2. **Escribir instrucciones** para el modelo: qué debe extraer y en qué formato.
3. **Guardar** y **mejorar el borrador** (refinamiento automático de las instrucciones) y **probar** con un documento de ejemplo (la prueba se ejecuta de forma asíncrona).
4. Cuando el resultado te convenza, **activar una versión** con **Usar esta versión** para que pase a ser la versión vigente para ese procesamiento.

### Versionado e historial

Cada guardado relevante genera **versiones** del procesamiento. Puedes revisar el historial, comparar borradores y, en cualquier momento, **activar** la versión que quieras usar en producción.
Solo una versión activa por procesamiento define el comportamiento para nuevos documentos.

<Info>
  Ten en cuenta que cada vez que modifiques o pruebes una versión activa se va a
  crear una nueva versión y vas a tener que elegir qué versión va a ser la que
  consideres como "activa".
</Info>

## Qué ocurre cuando hay una versión activa

Cuando:

* existe un procesamiento **activo** para un tipo de documento, y
* se cargan o reprocesan documentos de **ese tipo** en una verificación,

Trébol ejecuta el extractor de extracciones personalizadas y, si la extracción termina correctamente, el resultado queda **asociado al ítem (la fuente de datos dentro de la verificación)** correspondiente.

## Cómo consumir los resultados

### API

Los mismos datos que ves como fuentes en la verificación se exponen en la sección **`sources`** de los endpoints v2 de lectura por empresa o por verificación, por ejemplo [Obtener sección por etiqueta de empresa](https://docs.gotrebol.com/api-reference/leer-información-de-la-empresa/obtener-sección-por-etiqueta-de-empresa) y [Obtener sección por ID de verificación](https://docs.gotrebol.com/api-reference/leer-información-de-la-empresa/obtener-sección-por-id-de-verificación).

Cada objeto de fuente incluye una llave **`cp_<identificador_del_procesamiento>`** por cada extracción con resultado, donde el identificador es el nombre que definiste. El valor es el objeto JSON extraído según el esquema de la versión que produjo el resultado. El prefijo `cp_` existe para que un identificador que definas nunca choque con un campo extraído del documento. La referencia del modelo está en el esquema de la API bajo `V2CompanySource`.

Los mismos resultados aparecen dentro de **`item_value`**, con la misma llave `cp_<identificador_del_procesamiento>`, en los endpoints que devuelven ítems: [Obtener un ítem por ID](https://docs.gotrebol.com/api-reference) y la lectura de una verificación por ID.

<Warning>
  Antes, estos resultados venían agrupados en un objeto `custom_user_prompts` dentro de cada fuente. Ese campo ya no se devuelve: cada resultado es ahora una llave `cp_<identificador>` propia.
</Warning>

<Note>
  Las llaves `cp_<identificador>` son exclusivas de las extracciones personalizadas sobre tipos de documento estándar. Los [tipos de ítem personalizados](/docs/producto/guias/tipos-de-item-personalizados#donde-salen-los-resultados) no las usan: los resultados de sus procesos viven en `item_value.pipeline` del ítem.
</Note>

### Plantillas de documentos

Al exportar una verificación a una plantilla, el diccionario de variables incluye las fuentes y, con ellas, los resultados de cada procesamiento. Las variables planas siguen el patrón del diccionario de Trébol, por ejemplo:

* `{sources_0_cp_<tu_prompt_id>_<campo_del_esquema>}`

donde `<tu_prompt_id>` coincide con el identificador editable del procesamiento y `<campo_del_esquema>` con las claves del JSON definido en tu versión. Detalle en [Diccionario de variables de Trébol](/docs/plantillas/intro) (sección sobre extracciones personalizadas).

## Siguientes pasos

<CardGroup cols={2}>
  <Card title="Tipos de documentos" href="/docs/guia-devs/referencia/tipos-item">
    Lista completa de tipos de documento soportados por Trébol, sobre los que puedes aplicar extracciones personalizadas.
  </Card>

  <Card title="Respuestas por tipo de ítem" href="/docs/guia-devs/referencia/respuestas-por-tipo-de-item">
    Estructura estándar de respuesta por tipo. Útil para saber qué devuelve la extracción estándar antes de personalizar.
  </Card>

  <Card title="Divisor de documentos" href="/docs/producto/guias/doc-splitter">
    Cuando recibes un PDF con varios documentos, divídelo primero y aplica tus extracciones personalizadas sobre cada corte.
  </Card>

  <Card title="Plantillas" href="/docs/plantillas/intro">
    Diccionario de variables para consumir tus extracciones personalizadas en exports.
  </Card>
</CardGroup>