Skip to main content

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.

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. Si no se especifica, se infiere del país de la verificación.
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 (ubos_form_schema)

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.

​
Ejemplos de configuración

Configuración básica: 
{
  "type": "ubos",
  "options": {
    "is_optional": true,
    "ubos_data_extraction": false,
    "ubos_form_schema": "mx_form",
    "ubos_threshold": 25
  }
}
Solo los primeros 2 niveles obligatorios: 
{
  "type": "ubos",
  "options": {
    "ubos_form_schema": "mx_form",
    "ubos_threshold": 25,
    "reported_levels_required": 2
  }
}
Todos los niveles obligatorios con threshold constante: 
{
  "type": "ubos",
  "options": {
    "ubos_form_schema": "co_form",
    "ubos_threshold": 5,
    "maintain_threshold_on_add": true
  }
}
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.

​
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": "textarea",
    "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"
  }
}