> ## 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. # Items del flujo > Tipos de items que puedes agregar al flujo: ubos, forms (UI del prospecto) y consultas a fuentes externas (auto-ejecutadas). Los **items del flujo** son los elementos que puedes agregar al array `flow_items.items` del `account-flow`. Se dividen en dos categorías: * **Items del widget** (`ubos`, `forms`): información que el widget captura del **prospecto** mediante UI. El usuario final interactúa con ellos. * **Consultas a fuentes externas** (`siger`, `rues`, `public_sat_signatures`, etc.): Trébol las ejecuta **automáticamente** al crear cada verificación con este flujo. No tienen UI — corren en segundo plano. Los **documentos** que el widget le solicita al prospecto son distintos: se configuran en el `record_validation_schema` del flujo (no son items). Ver [Crear el flujo](/docs/guia-devs/crear-verificaciones/via-widget/crear-flujo). *** ## `ubos` — beneficiarios finales Captura la declaración de beneficiarios finales (UBOs) de una empresa. El prospecto declara personas físicas con participación relevante y sus datos de identificación. Solo se puede agregar un `ubos` por flujo. **Cuándo usarlo:** onboarding de empresas que requiera cumplir con políticas de conocimiento del beneficiario final (KYB/AML). ### Opciones | Opción | Tipo | Descripción | | :-------------------------- | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ubos_data_extraction` | `boolean` | Extrae información automáticamente de los documentos cargados en esta sección. | | `ubos_form_schema` | `"mx_form"` \| `"co_form"` | Define el esquema de campos del formulario usando los esquemas por defecto. Si no se especifica, se infiere del país de la verificación. Usa `ubos_schema_id` para esquemas completamente personalizados. | | `ubos_schema_id` | `string` | ID de un esquema de formulario personalizado creado con el [endpoint de esquemas de formularios](https://docs.gotrebol.com/api-reference/gestión-de-esquemas-de-formularios/crear-nuevo-esquema-de-formulario). Cuando se especifica, el widget usa este esquema en lugar de los predeterminados (`mx_form` / `co_form`). El esquema debe existir en la cuenta. **Prioridad:** `ubos_schema_id` > `ubos_form_schema` > inferencia por país. | | `ubos_threshold` | `number` | Porcentaje mínimo de participación accionaria para declarar un UBO. **Por defecto:** 5% para Colombia, 25% para otros países. Por defecto este valor se recalcula recursivamente para empresas anidadas según el porcentaje de participación de cada accionista; ese comportamiento puede modificarse con `maintain_threshold_on_add`. | | `reported_levels_required` | `number` | Cantidad de niveles del árbol societario que el prospecto **debe completar** para que el ítem se considere `complete` automáticamente. El nivel raíz (accionistas directos de la empresa) es el `1`. Si no se especifica, se exige completar **todos los niveles** alcanzables según el threshold. | | `maintain_threshold_on_add` | `boolean` | Si es `true`, el threshold del nivel padre se hereda tal cual en cada nivel hijo, en lugar de recalcularse en función del porcentaje de participación del accionista intermedio. Útil cuando se requiere reportar UBOs reales en niveles profundos sin que el umbral se "diluya". **Por defecto:** `false`. | | `is_optional` | `boolean` | Si es `true`, el prospecto puede omitir esta sección. | **¿Cuándo usar `reported_levels_required` y `maintain_threshold_on_add`?** * Si tu negocio acepta que el prospecto **complete solo los primeros N niveles** del árbol societario (por ejemplo, accionistas directos y el siguiente nivel), usa `reported_levels_required: N`. Si el prospecto presiona "continuar sin completar" en niveles más profundos, el ítem se marca para revisión manual en lugar de cerrarse automáticamente. * Si tu negocio requiere reportar **todos los niveles con un threshold constante** (por ejemplo, 5% en cada nivel, sin diluirse con la participación del padre), combina `ubos_threshold` con `maintain_threshold_on_add: true` y omite `reported_levels_required` para forzar todo el árbol. * Si no envías ninguno de estos dos flags, el comportamiento es el histórico: el threshold se recalcula al descender y se exige que **todos** los niveles alcanzados por ese threshold queden completos. ### Esquemas de formulario El formulario que completa el prospecto para cada UBO puede configurarse de dos formas: 1. **Esquemas por defecto** (`ubos_form_schema`): usa `"mx_form"` o `"co_form"`. Si no se especifica ningún esquema, se infiere automáticamente del país de la verificación. 2. **Esquema personalizado** (`ubos_schema_id`): crea tu propio esquema con el [endpoint de esquemas de formularios](https://docs.gotrebol.com/api-reference/gestión-de-esquemas-de-formularios/crear-nuevo-esquema-de-formulario) y referéncialo por su `id_schema`. La estructura del `ui_schema_definition` para UBOs es la misma que usas para el [item `forms`](#forms). Consulta la sección de [tipos de campo disponibles](#tipos-de-campo) para ver todos los campos soportados. **Restricción:** los formularios de UBOs **no soportan el tipo `table`**. Si tu esquema incluye campos tipo `table`, serán ignorados. #### Campos estructurales obligatorios Todo esquema de UBOs — ya sea personalizado o por defecto — **debe incluir** los siguientes tres campos. Son necesarios para que el árbol de beneficiarios funcione correctamente (nombre visible, tipo de accionista, y porcentaje de participación): ```json Campos obligatorios en todo esquema de UBOs theme={"dark"} { "ui_order": ["name", "type", "share_percentage"], "name": { "ui_type": "text", "ui_label": "Nombre completo o razón social", "ui_required": true }, "type": { "ui_type": "select", "ui_label": "Tipo de accionista", "ui_required": true, "ui_items": ["Persona", "Empresa"] }, "share_percentage": { "ui_type": "number", "ui_label": "Porcentaje de participación", "ui_required": true } } ``` Si tu esquema personalizado omite `name`, `type` o `share_percentage`, el árbol de UBOs no podrá renderizarse correctamente. El campo `type` debe ser un `select` con al menos las opciones `"Persona"` y `"Empresa"` para que el widget distinga entre personas físicas y jurídicas y permita anidar accionistas en empresas. #### Esquemas por defecto Si no necesitas un formulario personalizado, puedes usar los esquemas que Trébol ofrece por defecto. Formulario para México. Campos según el tipo de accionista: * **Personas:** nombre, nacionalidad, porcentaje de participación, email, ocupación, teléfono y documento de identidad. * **Empresas:** nombre, nacionalidad, porcentaje de participación, régimen de capital y documentos opcionales (acta constitutiva, documento de accionistas). ```json theme={"dark"} { "ui_order": [ "name", "type", "nationality", "share_percentage", "email", "occupation", "phone", "id_file", "address_file", "business_type", "enterprise_file", "shareholders_file" ], "name": { "ui_type": "text", "ui_label": "Nombre completo o razón social", "ui_required": true }, "type": { "ui_type": "select", "ui_label": "Tipo", "ui_required": true, "ui_items": ["Persona", "Empresa"] }, "nationality": { "ui_type": "country", "ui_label": "Nacionalidad", "ui_required": true }, "share_percentage": { "ui_type": "number", "ui_label": "Porcentaje de acciones", "ui_required": true }, "email": { "ui_type": "email", "ui_label": "Correo electrónico", "ui_required": true, "depends_on": "type", "depends_on_value": ["Persona"] }, "occupation": { "ui_type": "text", "ui_label": "Ocupación, profesión o giro del negocio", "ui_required": true, "depends_on": "type", "depends_on_value": ["Persona"] }, "phone": { "ui_type": "number", "ui_label": "Número de teléfono", "ui_required": true, "depends_on": "type", "depends_on_value": ["Persona"] }, "id_file": { "ui_type": "file", "ui_label": "Carga el documento de identidad del accionista", "depends_on": "type", "depends_on_value": ["Persona"] }, "address_file": { "ui_type": "file", "ui_label": "Carga el comprobante de domicilio", "depends_on": "type", "depends_on_value": ["Persona"] }, "business_type": { "ui_type": "text", "ui_label": "Régimen de capital", "ui_required": true, "depends_on": "type", "depends_on_value": ["Empresa"] }, "enterprise_file": { "ui_type": "file", "ui_label": "Carga el documento que acredita la creación de la empresa", "depends_on": "type", "depends_on_value": ["Empresa"] }, "shareholders_file": { "ui_type": "file", "ui_label": "Carga el documento que acredita los accionistas de la empresa", "depends_on": "type", "depends_on_value": ["Empresa"] } } ``` Formulario para Colombia. Campos comunes a ambos tipos de accionista: nombre, nacionalidad, porcentaje de participación, tipo de documento, número de identificación, país de residencia, TIN (ID tributaria extranjera) y si es Persona Expuesta Políticamente (PEP). * **Solo Empresas:** campo adicional para indicar si cotiza en bolsa (`is_publicly_traded`). ```json theme={"dark"} { "ui_order": [ "name", "type", "nationality", "share_percentage", "id_type", "id_number", "residence", "tin", "is_pep", "is_publicly_traded" ], "name": { "ui_type": "text", "ui_label": "Nombre completo o razón social", "ui_required": true }, "type": { "ui_type": "select", "ui_label": "Tipo", "ui_required": true, "ui_items": ["Persona", "Empresa"] }, "nationality": { "ui_type": "country", "ui_label": "Nacionalidad", "ui_required": true }, "share_percentage": { "ui_type": "number", "ui_label": "Porcentaje de acciones", "ui_required": true }, "id_type": { "ui_type": "select", "ui_label": "Tipo de Documento", "ui_required": true, "ui_items": ["NIT", "TIN", "Cédula de ciudadanía", "Cédula de extranjería", "Pasaporte"] }, "id_number": { "ui_type": "text", "ui_label": "Número de identificación", "ui_required": true }, "residence": { "ui_type": "country", "ui_label": "País de residencia", "ui_required": true }, "tin": { "ui_type": "text", "ui_label": "ID tributaria en el extranjero (TIN)" }, "is_pep": { "ui_type": "checkbox", "ui_label": "¿Es Persona Expuesta Políticamente (PEP) o tiene vínculos con un PEP?" }, "is_publicly_traded": { "ui_type": "checkbox", "ui_label": "¿El accionista es una empresa cotizada en bolsa?", "depends_on": "type", "depends_on_value": ["Empresa"] } } ``` Los campos de **nacionalidad** y **país** usan el estándar ISO 3166-1 alpha-2 (249 países y territorios). Consulta la lista completa en [Países y nacionalidades](/docs/guia-devs/referencia/paises-nacionalidades). #### Crear un esquema personalizado Si los esquemas por defecto no cubren tus necesidades, puedes crear uno propio: 1. Diseña tu `ui_schema_definition` incluyendo siempre los [campos estructurales obligatorios](#campos-estructurales-obligatorios) (`name`, `type`, `share_percentage`). 2. Crea el esquema con el [endpoint de esquemas de formularios](https://docs.gotrebol.com/api-reference/gestión-de-esquemas-de-formularios/crear-nuevo-esquema-de-formulario). 3. Usa el `id_schema` resultante como valor de `ubos_schema_id` en las opciones del item `ubos`. ```json Ejemplo: crear un esquema personalizado para UBOs theme={"dark"} POST /v2/form-schemas { "name": "UBOs personalizado", "id_schema": "ubos-custom-001", "ui_schema_definition": { "ui_order": ["name", "type", "share_percentage", "nationality", "tax_id"], "name": { "ui_type": "text", "ui_label": "Nombre completo o razón social", "ui_required": true }, "type": { "ui_type": "select", "ui_label": "Tipo de accionista", "ui_required": true, "ui_items": ["Persona", "Empresa"] }, "share_percentage": { "ui_type": "number", "ui_label": "Porcentaje de participación", "ui_required": true }, "nationality": { "ui_type": "country", "ui_label": "Nacionalidad", "ui_required": true }, "tax_id": { "ui_type": "text", "ui_label": "Identificación tributaria" } } } ``` Luego referéncialo en el flujo: ```json theme={"dark"} { "type": "ubos", "options": { "ubos_schema_id": "ubos-custom-001", "ubos_threshold": 25 } } ``` ### Ejemplos de configuración Usar el esquema por defecto de México: ```json theme={"dark"} { "type": "ubos", "options": { "is_optional": true, "ubos_data_extraction": false, "ubos_form_schema": "mx_form", "ubos_threshold": 25 } } ``` Usar el esquema por defecto de Colombia (sin especificar `ubos_form_schema` — se infiere del país de la verificación si el país es `"co"`): ```json theme={"dark"} { "type": "ubos", "options": { "ubos_threshold": 5, "maintain_threshold_on_add": true } } ``` Solo los primeros 2 niveles obligatorios: ```json theme={"dark"} { "type": "ubos", "options": { "ubos_form_schema": "mx_form", "ubos_threshold": 25, "reported_levels_required": 2 } } ``` Esquema personalizado: ```json theme={"dark"} { "type": "ubos", "options": { "ubos_schema_id": "ubos-custom-001", "ubos_threshold": 10 } } ``` **Prioridad de resolución del esquema:** 1. Si se especifica `ubos_schema_id`, se usa ese esquema personalizado (debe existir en tu cuenta). 2. Si se especifica `ubos_form_schema` (`"mx_form"` o `"co_form"`), se usa el esquema por defecto correspondiente. 3. Si no se especifica ninguno, se infiere del país de la verificación (`"co"` → `co_form`, cualquier otro → `mx_form`). **Estructura de respuesta:** ver [Respuestas por tipo de ítem — ubos](/docs/guia-devs/referencia/respuestas-por-tipo-de-item#ubos). ***

`forms` — formularios personalizados

Cuestionarios de onboarding que tú configuras con preguntas abiertas, opciones múltiples u otros campos. Útil para capturar información específica de tu producto que no corresponde a un documento. Solo se puede agregar un `forms` por flujo. **Cuándo usarlo:** capturar datos de contexto propios de tu onboarding (tipo de cuenta deseada, origen de fondos declarado, etc.) directamente desde el widget. ### Configuración Antes de referenciar el formulario en el flujo, crea su esquema con el [endpoint de esquemas de formularios](https://docs.gotrebol.com/api-reference/gestión-de-esquemas-de-formularios/crear-nuevo-esquema-de-formulario) y usa el `schema_id` resultante en `options`. ### Cómo se renderiza el formulario al prospecto El widget usa el esquema JSON del formulario para decidir cómo mostrarlo: * **Secciones (menú lateral):** cada propiedad de nivel raíz con `ui_type: "section"` y `properties` anidadas se muestra como una sección. El título visible es el `ui_label` del objeto. * **Campos sueltos en la raíz:** si hay campos de nivel raíz que no son secciones (texto, número, fecha, etc.), el widget los agrupa automáticamente bajo una sección llamada «Información general». Si ya existe una propiedad raíz `general` como objeto, no se duplica. * **Orden:** sigue el `ui_order` configurado en el esquema, tanto en el menú lateral como en la pantalla del formulario.

Tipos de campo disponibles (`ui_type`)

| Tipo | Descripción | | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | Campo de texto simple. | | `number` | Campo numérico. | | `email` | Campo de email con validación de formato. | | `password` | Campo de contraseña (texto oculto). | | `date` | Selector de fecha. | | `file` | Selector de archivo para carga de documentos. | | `select` | Lista desplegable de selección única. Requiere `ui_items` con strings u objetos `{ label, value }`. | | `multiselect` | Selección múltiple. Requiere `ui_items` con strings u objetos `{ label, value }`. | | `section` | Contenedor para agrupar campos anidados. | | `table` | Tabla para capturar múltiples filas de datos. Requiere `ui_columns`. | | `paragraph` | Texto informativo sin input asociado. Solo requiere `ui_label`. | | `heading` | Encabezado informativo sin input asociado. Solo requiere `ui_label`. | | `checkbox` | Campo booleano (`true`/`false`) renderizado como checkbox con label al lado. Útil para preguntas de sí/no (ej. PEP, cotiza en bolsa). | | `country` | Selector de país con búsqueda (typeahead). Muestra los 249 países y territorios del estándar ISO 3166-1. **Almacena el nombre del país** en la llave del campo y genera automáticamente una llave adicional con sufijo `_code` que contiene el código alpha-2 (ej. si la llave es `nationality`, se almacena `nationality: "México"` y `nationality_code: "MX"`). Sirve tanto para campos de país como de nacionalidad. | #### Ejemplo de respuesta almacenada para `country` Si defines un campo con llave `nationality` y otro con llave `residence`, ambos de tipo `country`, la respuesta del formulario contendrá: ```json theme={"dark"} { "nationality": "México", "nationality_code": "MX", "residence": "Colombia", "residence_code": "CO" } ``` El sufijo `_code` se genera automáticamente — no necesitas declararlo en el esquema.

Opciones de selección (`ui_items`)

Los campos `select` y `multiselect` requieren la propiedad `ui_items` para definir las opciones disponibles. Existen dos formatos: **Formato simple (strings):** el valor almacenado es igual al texto que ve el prospecto. ```json theme={"dark"} { "ui_type": "select", "ui_label": "Tipo de documento", "ui_items": ["Cédula de ciudadanía", "Pasaporte", "Cédula de extranjería"] } ``` **Formato con label y value (objetos):** permite mostrar un texto amigable al prospecto (`label`) mientras se almacena un valor técnico diferente (`value`). Útil cuando necesitas guardar identificadores internos, códigos o valores en otro idioma. ```json theme={"dark"} { "ui_type": "select", "ui_label": "Tipo de accionista", "ui_items": [ { "label": "Persona", "value": "person" }, { "label": "Empresa", "value": "business" } ] } ``` En este ejemplo, el prospecto ve las opciones "Persona" y "Empresa", pero el valor almacenado en la respuesta será `"person"` o `"business"` respectivamente. Puedes mezclar ambos formatos en un mismo `ui_items` si lo necesitas, aunque se recomienda mantener la consistencia dentro de un campo. Si usas el formato de objetos, **todos los objetos deben tener ambas propiedades** (`label` y `value`). Si usas `depends_on_value` referenciando un campo `select` o `multiselect` con formato de objetos, los valores en `depends_on_value` deben coincidir con el **`value`** del objeto, no con el `label`. Por ejemplo, si `ui_items` es `[{ "label": "Persona", "value": "person" }]`, entonces `depends_on_value` debe ser `["person"]`. ### Campos condicionales (`depends_on` / `depends_on_value`) Cualquier campo del esquema puede declararse como **condicional**: solo se mostrará (y, si es requerido, solo se exigirá) cuando el valor de otro campo del mismo nivel cumpla una condición. Esto te permite construir formularios dinámicos sin ramificar el esquema. | Propiedad | Tipo | Descripción | | :----------------- | :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `depends_on` | `string` | Clave del campo del cual depende. **Debe existir en el `ui_order` del mismo nivel** (raíz si el campo está en raíz, o dentro de la misma sección si está anidado). No se permiten dependencias entre niveles. | | `depends_on_value` | `string[]` | Lista de valores que activan la visibilidad del campo. Las entradas se evalúan con lógica **OR (literal)**: basta con que una se cumpla, y **AND (comparación numérica)**: todas tienen que cumplirse. | Cada entrada de `depends_on_value` puede ser de dos tipos: * **Literal:** se compara por igualdad. Si el campo padre es de selección múltiple (array), el match ocurre si el array del padre **incluye** ese valor. * **Comparación numérica:** la cadena debe iniciar con uno de estos operadores seguido de un número, sin espacios: `>`, `<`, `>=`, `<=`, `!=`. El valor del campo padre se intenta convertir a número; si no es numérico, esa entrada simplemente no matchea (las demás se siguen evaluando). No existe un operador `=` porque la igualdad ya está cubierta por el caso literal. **Reglas de validación:** * Si declaras `depends_on`, **es obligatorio** declarar también `depends_on_value` como un array no vacío. * No puedes declarar `depends_on_value` sin `depends_on`. * Cada entrada de `depends_on_value` debe ser un literal o un operador válido seguido de un número parseable (`">abc"` o `">="` se rechazan al crear el esquema). * Mientras la condición no se cumpla, el campo está **oculto** y **no se valida como requerido**, aunque tenga `ui_required: true`. * Cuando todas las entradas de `depends_on_value` son de **comparación numérica**, se evalúa que el valor cumpla con todas las condiciones (AND). De lo contrario, basta con que pase una sola (OR). ```json Ejemplo: literal + comparación numérica theme={"dark"} { "ui_order": ["tipo_persona", "edad", "nit", "tutor_legal"], "tipo_persona": { "ui_type": "select", "ui_label": "Tipo de persona", "ui_items": ["Natural", "Juridica"], "ui_required": true }, "edad": { "ui_type": "number", "ui_label": "Edad", "ui_required": true }, "nit": { "ui_type": "text", "ui_label": "NIT", "ui_required": true, "depends_on": "tipo_persona", "depends_on_value": ["Juridica"] }, "tutor_legal": { "ui_type": "text", "ui_label": "Nombre del tutor legal", "ui_required": true, "depends_on": "edad", "depends_on_value": ["<18"] } } ``` En este ejemplo `nit` solo aparece si el prospecto eligió `"Juridica"`, y `tutor_legal` solo aparece si la edad ingresada es menor a 18. ```json Ejemplo: múltiples condiciones por rangos (AND) theme={"dark"} { "ui_order": ["ingresos_mensuales", "justificacion_origen"], "ingresos_mensuales": { "ui_type": "number", "ui_label": "Ingresos mensuales (USD)", "ui_required": true }, "justificacion_origen": { "ui_type": "text", "ui_label": "Justifica el origen de los fondos", "ui_required": true, "depends_on": "ingresos_mensuales", "depends_on_value": [">=10000", "!=0"] } } ``` La justificación se mostrará si los ingresos son **mayores o iguales a 10.000** y **distintos de 0** (ambas condiciones numéricas deben cumplirse). ### Ejemplo de configuración ```json theme={"dark"} { "type": "forms", "options": { "schema_id": "form-datos-generales", "is_optional": false } } ``` **Estructura de respuesta:** ver [Respuestas por tipo de ítem — forms](/docs/guia-devs/referencia/respuestas-por-tipo-de-item#forms). *** ## Consultas a fuentes externas A diferencia de `ubos` y `forms`, las consultas a fuentes externas no tienen UI para el prospecto. Trébol las ejecuta automáticamente al crear cada verificación con este flujo, consumiendo información de registros públicos. No necesitas añadirlas al payload de cada verificación. ### Disponibles por país Cada consulta tiene sus opciones y estructura de respuesta documentadas en la guía del país: * **Colombia**: [`rues`](/docs/guia-devs/uso-kyb/colombia/items-consultas-publicas#rues), [`public_rut_co`](/docs/guia-devs/uso-kyb/colombia/items-consultas-publicas#public-rut-co), [`public_address_cc_co`](/docs/guia-devs/uso-kyb/colombia/items-consultas-publicas#public-address-cc-co). Referencia completa: [Items de consultas públicas — Colombia](/docs/guia-devs/uso-kyb/colombia/items-consultas-publicas). * **México**: [`siger`](/docs/guia-devs/uso-kyb/mexico/items-consultas-publicas#siger), [`public_sat_signatures`](/docs/guia-devs/uso-kyb/mexico/items-consultas-publicas#public-sat-signatures). Referencia completa: [Items de consultas públicas — México](/docs/guia-devs/uso-kyb/mexico/items-consultas-publicas). ### Opciones para `public_sat_signatures` (México) Requiere una llave `type` en `options` con valor `"business"`, `"representatives"` o ambos, según la información que necesites extraer del SAT. Puedes declarar dos items `public_sat_signatures` en el mismo flujo si necesitas ambos. ```json theme={"dark"} { "type": "public_sat_signatures", "options": { "type": "business" } } ```