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

# Tipos de Documentos y Consultas

> Lista de tipos de documentos y consultas soportados por Trébol

# Documentación de la API de Revisión de Documentos y Consultas de Onboarding

Trébol permite la creación y verificación de documentos y consultas para el proceso de onboarding de empresas y validación de documentos. A continuación se listan los tipos de documentos soportados, organizados por país y tipo, así como los ítems disponibles para consultas, widgets, integraciones y funcionalidades en beta.

**Importante:**\
Para la mayoría de los documentos, se recomienda crear los ítems utilizando el tipo `generic`. La plataforma Trebol clasificará automáticamente el documento al tipo específico correspondiente (por ejemplo, `ac_mx` o `csf_mx`). Adicionalmente, es posible especificar un tipo esperado mediante la opción `client_item_type` para mejorar la experiencia del cliente. Los ítems de tipo consulta no cambian su valor después de ser creados.

## Tipos de Documentos por País

### México

Para items de KYB en México, consulta [Items de documentos — KYB México](/docs/guia-devs/uso-kyb/mexico/items-documentos).

### Colombia

Para items de KYB en Colombia, consulta [Items de documentos — KYB Colombia](/docs/guia-devs/uso-kyb/colombia/items-documentos).

### Tipos técnicos del sistema

Estos tipos no son documentos por caso de uso — son estados o tipos especiales del sistema de Trébol.

| Ítem             | Descripción                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------- |
| `generic`        | Documento genérico. **Usar preferentemente al crear una verificación** para que Trébol clasifique. |
| `unknown`        | Documento desconocido o no procesable por Trébol.                                                  |
| `corrupted_file` | Documento dañado (no legible o corrupto).                                                          |

### Items por caso de uso

Los documentos aplicables a un caso de uso específico viven en la guía correspondiente en **Guías por caso de uso**:

* Documentos globales aplicables a KYB (`person_id`, `proof_address`, `bank_statement`, `trust_contract_fideicomiso_extractor`, `union_documents_extractor`, `financial_statements_any`): [KYB Todos los países](/docs/guia-devs/uso-kyb/todos-paises/items-documentos)
* Documentos específicos de KYB: ver guías de [México](/docs/guia-devs/uso-kyb/mexico/items-documentos), [Colombia](/docs/guia-devs/uso-kyb/colombia/items-documentos), [Estados Unidos](/docs/guia-devs/uso-kyb/eeuu/items-documentos)
* Documentos de Hipotecas: ver [Items de Hipotecas](/docs/guia-devs/uso-hipotecas/items)
* Documentos de Nómina: ver [Items de Nómina](/docs/guia-devs/uso-nomina/items)

## Ítems de Tipo Consulta

Los siguientes ítems están orientados a la **consulta** de información ante entidades o fuentes externas. Su valor no cambia una vez creados.

### México

Para consultas públicas de KYB en México (SIGER, SAT, CURP), consulta [Items de consultas públicas — KYB México](/docs/guia-devs/uso-kyb/mexico/items-consultas-publicas).

### Colombia

Para consultas públicas de KYB en Colombia (RUES, consulta de NIT en la DIAN, Cámara de Comercio), consulta [Items de consultas públicas — KYB Colombia](/docs/guia-devs/uso-kyb/colombia/items-consultas-publicas).

## Ítems de Widget

Estos ítems son parte del widget utilizado en el proceso de onboarding:

| Ítem    | Descripción                                                               |
| ------- | ------------------------------------------------------------------------- |
| `ubos`  | Formulario de declaración de propietarios reales (beneficiarios finales). |
| `forms` | Formularios de cuestionarios de onboarding.                               |

### Configuración de Ítems `forms`

Los ítems de tipo `forms` requieren una configuración específica:

**Propiedades requeridas:**

* `schema_id` (string): ID del esquema de formulario que debe corresponder a un esquema existente en la cuenta.

**Ejemplo de configuración:**

```json theme={"dark"}
{
  "type": "forms",
  "options": {
    "schema_id": "some-test-form-schema",
    "is_optional": true
  }
}
```

<Warning>
  **Importante:** El `schema_id` es obligatorio para ítems de tipo `forms`. Debe corresponder a un esquema de formulario válido creado previamente en tu cuenta.
</Warning>

## Ítems de Integraciones

Estos ítems corresponden a integraciones con otros sistemas o servicios:

| Ítem                   | Descripción                                        |
| ---------------------- | -------------------------------------------------- |
| `aml_validation`       | Consulta en listas de sanciones (OFAC, CNBV, etc). |
| `signatory_validation` | Validación biométrica de firmantes.                |

## Workflow de Clasificación de Documentos

Para la mayoría de los documentos, se recomienda crear los ítems utilizando el tipo `generic`. A continuación, Trebol clasificará automáticamente el documento al tipo específico correspondiente, como `ac_mx` para actas constitutivas en México o `csf_mx` para constancias de situación fiscal en México. Este flujo simplifica la integración y asegura una clasificación precisa sin intervención manual.

**Pasos del Workflow:**

1. **Creación del Ítem:**

   * Enviar el documento utilizando el tipo `generic`.

2. **Procesamiento por Trebol:**

   * Trebol analiza el documento y determina su tipo específico.

3. **Actualización del Ítem:**
   * El ítem inicialmente creado como `generic` se actualiza automáticamente al tipo correspondiente, como `ac_mx`, `csf_mx`, etc.
   * Si Trebol no puede clasificar el documento, el ítem se actualiza a `unknown` o `corrupted_file` según corresponda.

Para los ítems de tipo consulta, su valor permanece constante y no se modifican después de la creación.

## Ejemplos de Manejo de Errores

### Ejemplo: Documento Genérico que Termina siendo `unknown` o `corrupted_file`

Imaginemos que una empresa está realizando el onboarding y sube un documento, este documento es de tipo `generic`. Una vez enviado, Trebol procesa el documento para determinar su tipo específico.

* **Caso 1: Documento Termina siendo `unknown`**

  Después del procesamiento, Trebol no reconoce el tipo de documento proporcionado. En este caso, el ítem creado como `generic` se actualiza automáticamente a `unknown`.

  **Manejo del Error:**

  * La aplicación debe verificar el estado del ítem y detectar que su tipo es `unknown`.
  * Se puede notificar al usuario que el documento subido no fue reconocido.
  * Se puede solicitar al usuario que proporcione un nuevo documento o que intente con otro tipo de archivo compatible.

* **Caso 2: Documento Termina siendo `corrupted_file`**

  Si Trebol detecta que el archivo subido está dañado o no es legible, el ítem creado como `generic` se actualiza automáticamente a `corrupted_file`.

  **Manejo del Error:**

  * La aplicación debe identificar que el ítem tiene el tipo `corrupted_file`.
  * Informar al usuario que el archivo cargado está dañado o corrupto.
  * Solicitar al usuario que vuelva a subir el documento en un formato legible y sin errores.