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

​
Reglas de Validación de Documentos (validation_options.ruleset)

Cada requerimiento puede incluir reglas de validación de negocio que se evalúan automáticamente sobre el documento mediante IA. Se configuran dentro de validation_options.ruleset. Las reglas siguen la misma estructura de reglas predefinidas y personalizadas documentada en la guía de flujo de validación de documentos, con una diferencia clave: al configurar el ruleset dentro de un account flow, cada regla requiere el campo error_message, que define el mensaje que verá el usuario si la regla no se cumple.
CampoTipoCuándo aplicaDescripción
idstringSiempre requeridoIdentificador de la regla. Para reglas predefinidas de Trébol usa vr_trebol_*. Para reglas personalizadas, cualquier identificador único.
error_messagestringRequerido en account flowMensaje de error que se mostrará si la regla no se cumple. Solo aplica en la configuración del record_validation_schema de un account flow.
validation_rulestringSolo reglas personalizadasTexto completo de la pregunta de validación. No incluir en reglas predefinidas de Trébol (vr_trebol_*).
paramsobjectSolo reglas predefinidasParámetros para sustituir placeholders en reglas predefinidas de Trébol.
Ejemplo de requerimiento con ruleset
{
  "record_validation_schema": {
    "version": 2,
    "requirements": {
      "req_csf": {
        "allowed_item_types": ["csf_mx"],
        "ui_options": {
          "label": "Constancia de Situación Fiscal",
          "description": "CSF actualizada con menos de 60 días"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate",
          "ruleset": [
            {
              "id": "vr_trebol_antiguedad",
              "params": { "days": 60 },
              "error_message": "La CSF debe tener menos de 60 días de antigüedad"
            },
            {
              "id": "regla_rfc",
              "validation_rule": "¿El RFC visible en el documento coincide con el RFC registrado de la empresa?",
              "error_message": "El RFC del documento no coincide con el de la empresa"
            }
          ]
        }
      }
    }
  }
}

​
Comportamiento ante error de validación (validation_options.on_invalid_type_error)

Esta propiedad controla qué sucede cuando un documento no pasa la validación de tipo o de ruleset. Se aplica por igual a ambos tipos de error: si el documento no coincide con los allowed_item_types configurados, o si falla alguna regla del ruleset.
ValorComportamiento
"invalidate" (default)El documento se marca como error. El prospecto ve una alerta en el widget y puede decidir subir otro documento o continuar con el actual.
"ignore"El documento se marca como “en revisión”. El prospecto no ve ningún error en el widget. El operador del dashboard resuelve manualmente desde la webapp.
Cuando un documento falla la validación de tipo o de ruleset:
  • El widget muestra al prospecto una alerta indicando que el tipo de documento no es válido o que no cumple las reglas configuradas.
  • El prospecto puede decidir subir un documento diferente o continuar con el documento actual.
  • Los errores se reflejan inmediatamente en el estado del requerimiento como status: "error".
Los errores de sistema (validation_request_failed) siempre se tratan como errores independientemente del valor de on_invalid_type_error, ya que representan fallos técnicos y no decisiones de validación.
Ejemplo con on_invalid_type_error:
{
  "record_validation_schema": {
    "version": 2,
    "requirements": {
      "req_csf": {
        "allowed_item_types": ["csf_mx"],
        "ui_options": {
          "label": "Constancia de Situación Fiscal",
          "description": "CSF actualizada"
        },
        "validation_options": {
          "on_invalid_type_error": "ignore",
          "ruleset": [
            {
              "id": "vr_trebol_antiguedad",
              "params": { "days": 60 },
              "error_message": "La CSF debe tener menos de 60 días de antigüedad"
            }
          ]
        }
      }
    }
  }
}

​
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": "compliance@tuempresa.com"
    }
  },
  "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"
        },
        "validation_options": {
          "on_invalid_type_error": "ignore",
          "ruleset": [
            {
              "id": "vr_trebol_antiguedad",
              "params": { "days": 60 },
              "error_message": "La CSF debe tener menos de 60 días de antigüedad"
            }
          ]
        }
      }
    },
    "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.