Skip to main content
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.

​
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ónTipoDescripción
ubos_data_extractionbooleanExtrae 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_idstringID de un esquema de formulario personalizado creado con el endpoint de esquemas de formularios. 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_thresholdnumberPorcentaje 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_requirednumberCantidad 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_addbooleanSi 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_optionalbooleanSi 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 y referéncialo por su id_schema.
La estructura del ui_schema_definition para UBOs es la misma que usas para el item forms. Consulta la sección de tipos de campo disponibles 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):
Campos obligatorios en todo esquema de UBOs
{
  "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).
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.

​
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 (name, type, share_percentage).
  2. Crea el esquema con el endpoint de esquemas de formularios.
  3. Usa el id_schema resultante como valor de ubos_schema_id en las opciones del item ubos.
Ejemplo: crear un esquema personalizado para UBOs
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: 
{
  "type": "ubos",
  "options": {
    "ubos_schema_id": "ubos-custom-001",
    "ubos_threshold": 25
  }
}

​
Ejemplos de configuración

Usar el esquema por defecto de México: 
{
  "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"): 
{
  "type": "ubos",
  "options": {
    "ubos_threshold": 5,
    "maintain_threshold_on_add": true
  }
}
Solo los primeros 2 niveles obligatorios: 
{
  "type": "ubos",
  "options": {
    "ubos_form_schema": "mx_form",
    "ubos_threshold": 25,
    "reported_levels_required": 2
  }
}
Esquema personalizado: 
{
  "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.

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

TipoDescripción
textCampo de texto simple.
numberCampo numérico.
emailCampo de email con validación de formato.
passwordCampo de contraseña (texto oculto).
dateSelector de fecha.
fileSelector de archivo para carga de documentos.
selectLista desplegable de selección única. Requiere ui_items con strings u objetos { label, value }.
multiselectSelección múltiple. Requiere ui_items con strings u objetos { label, value }.
sectionContenedor para agrupar campos anidados.
tableTabla para capturar múltiples filas de datos. Requiere ui_columns.
paragraphTexto informativo sin input asociado. Solo requiere ui_label.
headingEncabezado informativo sin input asociado. Solo requiere ui_label.
checkboxCampo booleano (true/false) renderizado como checkbox con label al lado. Útil para preguntas de sí/no (ej. PEP, cotiza en bolsa).
countrySelector 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á: 
{
  "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. 
{
  "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. 
{
  "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.
PropiedadTipoDescripción
depends_onstringClave 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_valuestring[]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).
Ejemplo: literal + comparación numérica
{
  "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.
Ejemplo: múltiples condiciones por rangos (AND)
{
  "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

{
  "type": "forms",
  "options": {
    "schema_id": "form-datos-generales",
    "is_optional": false
  }
}
Estructura de respuesta: ver Respuestas por tipo de ítem — 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:

​
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. 
{
  "type": "public_sat_signatures",
  "options": {
    "type": "business"
  }
}