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

En cada objeto de fuente, el campo **`custom_user_prompts`** (JSON) agrupa los resultados por **identificador del procesamiento** (el nombre que definiste). El valor es el objeto JSON extraído según el esquema de la versión activa. La referencia del modelo está en el esquema de la API bajo `V2CompanySource` / `custom_user_prompts`.

### Plantillas de documentos

Al exportar una verificación a una plantilla, el diccionario de variables incluye las fuentes y, de forma anidada, los contenidos de **`customUserPrompts`**. Las variables planas siguen el patrón del diccionario de Trébol, por ejemplo:

* `{sources_0_customUserPrompts_<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="Plantillas" href="/docs/plantillas/intro">
    Diccionario de variables para consumir tus extracciones personalizadas en exports.
  </Card>
</CardGroup>