Skip to main content
Los Account Flows son el núcleo de la experiencia de onboarding en nuestra plataforma. Permiten definir exactamente qué información, documentos y validaciones se requieren de un prospecto (individuo o empresa) para convertirse en un cliente verificado.
Esta guía está enfocada en la configuración lógica y de producto de los flujos. Para detalles técnicos de implementación, consulta la Referencia de API.

​
Conceptos Clave

Un Account Flow se compone de 3 piezas fundamentales que trabajan en conjunto:

Experiencia (UI)

flow_items Define secciones de solicitud de información adicional y consultas de información externa. Más adelante se aclara cuáles ítems se pueden enviar para cada caso.

Compliance (Reglas)

record_validation_schema Define qué requisitos de documentos debe cumplir el expediente para ser aprobado. Es el único parámetro obligatorio: todo flujo necesita al menos un requerimiento de documentos.

Regionalización

country Define los tipos de documento a solicitar y las validaciones a realizar sobre el número de documento ingresado por el prospecto al iniciar la verificación.

​
Estructura del Flujo

​
1. Configurando la Experiencia (flow_items)

El objeto flow_items controla la secuencia de pasos que el usuario final completará. Es el único lugar donde se deben solicitar datos estructurados (formularios) o información de Beneficiarios finales. Además de la solicitud de información externa. Tipos de Items Exclusivos de flow_items:
  • forms: Formularios personalizados para capturar datos (ej. teléfono, dirección, actividad económica). Solo puedes agregar uno por flujo. Antes de usarlo, crea el esquema del formulario mediante este endpoint y usa su schema_id en la llave options.
  • ubos: Módulo especializado para la captura de Beneficiarios Finales (UBOs). Solo puedes agregar uno por flujo. Opciones disponibles para ubos:
    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. Este valor se usa recursivamente para calcular el umbral de empresas anidadas.
    is_optionalbooleanSi es true, el prospecto puede omitir esta sección.
    Formulario para México. Solicita los siguientes 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).
Fuentes externas:
  • Colombia: rues, public_rut_co, public_address_cc_co.
  • México: siger, public_sat_signatures. Requieren una llave type en options con valor "business", "representatives" o ambos, según la información que necesites extraer del SAT.
Ejemplo de México (JSON)
{
  "flow_items": {
    "id": "mx_public_sat_signatures_example",
    "items": [
      {
        "type": "public_sat_signatures",
        "options": {
          "type": "business"
        }
      },
      {
        "type": "public_sat_signatures",
        "options": {
          "type": "representatives"
        }
      },
      {
        "type": "ubos",
        "options": {
          "is_optional": true,
          "ubos_data_extraction": false,
          "ubos_form_schema": "mx_form",
          "ubos_threshold": 25
        }
      },
      {
        "type": "forms",
        "options": {
          "schema_id": "onboarding-form-test",
          "is_optional": true
        }
      }
    ]
  }
}
Opciones: También puedes pasar configuraciones adicionales bajo la llave options. Estas se aplicarán a cada verificación que se cree con este flujo:
  • creator_email: Asociar un email a todas las verificaciones creadas con ese flujo.
  • next_steps_checkout: Lista de pasos a seguir para tu prospecto al finalizar el flujo de onboarding. Se puede enviar un array vacío para no mostrar ningún paso. Puedes revisar su estructura en el API Reference
Los items forms y ubos son exclusivos para la interacción con el prospecto y NO deben incluirse en el record_validation_schema, ya que no son documentos sujetos a validación de expediente tradicional.

​
2. Definiendo Reglas de Negocio (record_validation_schema)

Este esquema dicta qué documentos son obligatorios y cuáles son opcionales para aprobar el expediente. Por medio de este parametro se genera la sección del widget de carga de documentos, la cual es la única requerida en cualquier flujo de onboarding.
  • version: Versión del esquema de validación. Actualmente solo se soporta la versión 2.
  • requirements: Mapa de documentos obligatorios donde la clave es un ID personalizado (por ejemplo, "doc_1"). Al menos debes incluir uno por flujo.
  • optional_requirements: Documentos complementarios, usan la misma estructura que los requirements y son opcionales.
La estructura de cómo debes pasar cada uno de estos valores a la hora de crear el flow está claramente definida en el API Reference

​
3. Regionalización (country)

El campo country determina el contexto legal y las validaciones automáticas.
ValorComportamiento
mxHabilita validaciones del SAT y documentos como csf_mx.
coHabilita validaciones del RUES/DIAN y documentos como rut_co.
null / not_specifiedModo Genérico. Sin validaciones de formato locales.

​
Ejemplo de Configuración

Ejemplo de un flujo de onboarding para una Empresa Mexicana. Nota cómo forms está en flow_items pero no en record_validation_schema.
Configuración del Body (JSON)
{
  "friendly_name": "Onboarding Empresa MX - Estándar",
  "id_slug": "onboarding-test-1",
  "country": "mx",
  "flow_items": {
    "id": "mx-business-onboarding-v1",
    "items": [
      {
        "type": "forms",
        "options": {
          "schema_id": "form-datos-generales",
          "is_optional": false
        }
      }
    ],
    "options": {
      "creator_email": "[email protected]"
    }
  },
  "record_validation_schema": {
    "version": 2,
    "requirements": {
      "req_acta": {
        "allowed_item_types": ["ac_mx", "pw_mx"],
        "ui_options": {
          "label": "Documento Legal",
          "description": "Acta Constitutiva o Poder"
        }
      },
      "req_fiscal": {
        "allowed_item_types": ["csf_mx"],
        "ui_options": {
          "label": "Documento Fiscal",
          "description": "CSF Actualizada"
        }
      }
    },
    "optional_requirements": {}
  }
}
Debes asignar siempre un friendly_name, nombre por medio del cual vas a reconocer tu flujo recién creado desde la UI de Trébol, y el id_slug, identificador único de tu flujo que servirá para identificarlo dentro del sistema de Trébol.

​
Tipos de Documentos Soportados

Para configurar allowed_item_types en el esquema de validación, usa solamente los códigos aquí documentados. Al decidir qué código usar, ten en cuenta el país que configuraste para el flujo. Puedes usar uno o más códigos en cada requerimiento del record_validation_schema.