Ítems globales

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.

“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, como person_id y bank_statement, tienen su propia referencia.

Tipos globales disponibles

Actualmente, el catálogo incluye un tipo global.

cit_holding_shareholder_structure

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.

curl "https://api.gotrebol.com/v2/custom-item-types?limit=100" \
  -H "x-api-key: YOUR_API_KEY"

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

string

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

string

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

boolean

true para los tipos compartidos que Trébol mantiene.

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.

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

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

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.

string

required

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

string

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

string

Contraseña del PDF, cuando la requiere. Consulta PDF protegido con contraseña.

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.

Contrato de resultados

Consulta los resultados en item_value.pipeline, los estados de cada proceso y las limitaciones de la salida pública.

Webhooks

Recibe los eventos de procesamiento y consulta el ítem cuando termine.

Errores

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.

Intro al API de Trébol

Guías por caso de uso

Ítems globales

Tipos globales disponibles

cit_holding_shareholder_structure

Consultar el catálogo vigente

Enviar documentos

Leer los resultados

Contrato de resultados

Webhooks

Errores

Limitaciones comunes

​Tipos globales disponibles

cit_holding_shareholder_structure

​Consultar el catálogo vigente

​Enviar documentos

​Leer los resultados

Contrato de resultados

Webhooks

Errores

​Limitaciones comunes

Tipos globales disponibles

Consultar el catálogo vigente

Enviar documentos

Leer los resultados

Limitaciones comunes