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

# Ítems globales

> Descubre los tipos globales de Trébol, consulta sus procesos y usa la clasificación automática para procesar documentos.

Los ítems globales son tipos de documento que Trébol mantiene y comparte con todas las cuentas.
Su `name` empieza con `cit_` y el catálogo los identifica con `is_global: true`.
No necesitas crear una copia del tipo para que Trébol clasifique tus documentos.

> [!NOTE]
>
> “Global” describe la disponibilidad del tipo para las cuentas. Cada tipo reconoce documentos y datos específicos.
> Consulta sus requisitos antes de usarlo para un país o caso de uso.
> Los [documentos comunes a varios países](https://gotrebol.com/docs/guia-devs/uso-kyb/todos-paises/items-documentos.md), como `person_id` y `bank_statement`, tienen su propia referencia.

## Tipos globales disponibles

Actualmente, el catálogo incluye un tipo global.

> [card] [cit\_holding\_shareholder\_structure](https://gotrebol.com/docs/guia-devs/uso-kyb/todos-paises/estructura-accionaria-holding.md)
>
> Estructura accionaria de una empresa y sus holdings. Extrae un grafo de empresas y accionistas, y alimenta la conciliación de propietarios reales en `ubos`.

## Consultar el catálogo vigente

Usa `GET /v2/custom-item-types` con tu API key.
El listado combina tus tipos personalizados y los tipos globales activos.
Recorre todas las páginas siguiendo `next` y conserva los elementos con `is_global: true`.

Reemplaza `YOUR_API_KEY` por tu API key. El ejemplo de JavaScript recupera el catálogo completo.

```bash curl theme={"dark"}
curl "https://api.gotrebol.com/v2/custom-item-types?limit=100" \
  -H "x-api-key: YOUR_API_KEY"
```

```javascript JavaScript theme={"dark"}
const apiKey = "YOUR_API_KEY";
const globalTypes = [];
let next;

do {
  const url = new URL("https://api.gotrebol.com/v2/custom-item-types");
  url.searchParams.set("limit", "100");
  if (next) url.searchParams.set("next", next);

  const response = await fetch(url, { headers: { "x-api-key": apiKey } });
  if (!response.ok) throw new Error(`Error al consultar el catálogo: ${response.status}`);
  const page = await response.json();
  globalTypes.push(...page.data.filter((type) => type.is_global === true));
  next = page.next;
} while (next);

console.log(globalTypes);
```

**name** `string`

Nombre del tipo, por ejemplo `cit_holding_shareholder_structure`. Identifica el `item_type` final del documento.

**id** `string`

Identificador público del tipo. Úsalo en `GET /v2/custom-item-types/{id}` para consultar sus procesos completos.

**is\_global** `boolean`

`true` para los tipos compartidos que Trébol mantiene.

**processes** `array`

Procesos configurados, con `process_type`, `process_reference`, `is_active`, `user_input` y `json_schema`.
El esquema de cada extracción define sus campos de salida. Clasificación y validación devuelven `json_schema: null`.

> [!WARNING]
>
> Los tipos globales y sus procesos son de solo lectura. Intentar modificarlos o eliminarlos devuelve HTTP `403`.
> Para reglas o extracciones propias, crea un [tipo personalizado](https://gotrebol.com/docs/producto/guias/tipos-de-item-personalizados.md) con otro nombre.

## Enviar documentos

Envía un documento como `generic`. Trébol compara su contenido con las descripciones de clasificación disponibles, incluidos los tipos globales activos.
Si lo reconoce, el ítem cambia al `cit_*` correspondiente y ejecuta sus procesos configurados.

El siguiente ejemplo agrega un documento a una verificación existente.
Reemplaza `verification_id`, `YOUR_API_KEY` y la URL del archivo por tus valores.
La URL debe permitir descargar el archivo directamente.

```bash curl theme={"dark"}
curl -X PUT "https://api.gotrebol.com/verifications/verification_id/add-items" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "type": "generic",
      "options": {
        "file_url": "https://ejemplo.com/estructura-accionaria.pdf"
      }
    }]
  }'
```

```javascript JavaScript theme={"dark"}
const verificationId = "verification_id";
const response = await fetch(
  `https://api.gotrebol.com/verifications/${verificationId}/add-items`,
  {
    method: "PUT",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      items: [{
        type: "generic",
        options: { file_url: "https://ejemplo.com/estructura-accionaria.pdf" }
      }]
    })
  }
);
if (!response.ok) throw new Error(`Error al agregar el documento: ${response.status}`);
console.log(await response.json());
```

También puedes enviar el mismo objeto en `items[]` de `POST /verifications`.
Para subir el archivo sin alojarlo en una URL, sigue el flujo de [carga directa](https://gotrebol.com/docs/guia-devs/crear-verificaciones/via-api/carga-directa.md).

**items\[].type** `string` *required*

Usa `generic` para esta ruta de clasificación automática.

**items\[].options.file\_url** `string`

URL pública o firmada al documento descargable. Debe seguir vigente cuando Trébol procese el archivo.

**items\[].options.file\_password** `string`

Contraseña del PDF, cuando la requiere. Consulta [PDF protegido con contraseña](https://gotrebol.com/docs/guia-devs/crear-verificaciones/via-api/carga-directa.md#pdf-protegido-con-contrasena).

> [!WARNING]
>
> Actualmente, la API puede rechazar con HTTP `400` el envío explícito de un nombre global en `type` o `options.client_item_type`.
> Usa `generic` sin `client_item_type`. La clasificación depende del contenido y no garantiza un tipo concreto.
> Comprueba el `item_type` final antes de interpretar el resultado.

## Leer los resultados

Identifica el resultado por el `process_reference` que devuelve el catálogo.
Comprueba el `item_type` final y el éxito de la extracción antes de usar sus datos.

> [card] [Contrato de resultados](https://gotrebol.com/docs/producto/guias/tipos-de-item-personalizados.md#donde-salen-los-resultados)
>
> Consulta los resultados en `item_value.pipeline`, los estados de cada proceso y las limitaciones de la salida pública.

> [card] [Webhooks](https://gotrebol.com/docs/guia-devs/webhooks.md)
>
> Recibe los eventos de procesamiento y consulta el ítem cuando termine.

> [card] [Errores](https://gotrebol.com/docs/guia-devs/errores.md)
>
> Interpreta los códigos HTTP que devuelven el catálogo y el envío de documentos.

## Limitaciones comunes

* Un archivo ilegible, incompleto o que no corresponde a la descripción del tipo puede clasificarse de otra forma.
* Los datos extraídos dependen del documento. Un resultado no confirma por sí solo su autenticidad ni su vigencia.
* Los tipos y procesos globales pueden evolucionar. Consulta el catálogo y el esquema vigente antes de integrar un tipo nuevo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.