Crear el flujo

Un flujo de onboarding (account-flow) es una configuración reutilizable que define qué documentos pedirle al prospecto, qué items capturar (formularios, beneficiarios reales, consultas externas) y qué reglas aplicar. Una vez creado, lo usas cada vez que creas una verificación con el widget — Trébol ejecuta automáticamente todo lo configurado.

Esta guía cubre la configuración lógica y de producto del flujo. Para el schema técnico del endpoint, consulta la Referencia API.

Conceptos clave

Un flujo se compone de 3 piezas que trabajan en conjunto:

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.

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.

Experiencia (UI)

flow_items Define items adicionales: formularios, beneficiarios reales y consultas a fuentes externas que Trébol ejecuta automáticamente con cada verificación.

Ejemplo mínimo de un flujo

Lo mínimo que necesitas: country, id_slug, friendly_name y un record_validation_schema con al menos un requerimiento. flow_items es opcional.

{
  "friendly_name": "Onboarding Empresa MX - Mínimo",
  "id_slug": "onboarding-mx-minimo",
  "country": "mx",
  "record_validation_schema": {
    "version": 2,
    "requirements": {
      "req_csf": {
        "allowed_item_types": ["csf_mx"],
        "ui_options": {
          "label": "Constancia de Situación Fiscal"
        }
      }
    }
  }
}

Para flujos más completos (con ubos, formularios, consultas externas o reglas de validación), continúa leyendo las secciones siguientes.

Debes asignar siempre un friendly_name, nombre por el cual vas a reconocer tu flujo recién creado desde la UI de Trébol, y el id_slug, identificador único que servirá para identificarlo dentro del sistema de Trébol.

Límite de tamaño del payload (200 KB)El cuerpo de las solicitudes a los endpoints de account-flows y form schemas está limitado a 200 KB por nuestro WAF. Si la configuración que envías (reglas de validación, esquemas de formulario extensos, listas largas de flow_items, etc.) supera ese tamaño, la solicitud será rechazada.Si te acercas al límite, considera acortar textos repetitivos en ui_label y description de los formularios, o simplificar el record_validation_schema.

Estructura del flujo

1. Regionalización (`country`)

El campo country determina el contexto legal y las validaciones automáticas.

Valor	Comportamiento
`mx`	Habilita validaciones del SAT y documentos como `csf_mx`.
`co`	Habilita validaciones del RUES/DIAN y documentos como `rut_co`.
`null` / `not_specified`	Modo Genérico. Sin validaciones de formato locales.

2. Requerimientos de documentos (`record_validation_schema`)

Este esquema dicta qué documentos son obligatorios y cuáles opcionales para aprobar el expediente. Por medio de este parámetro se genera la sección del widget de carga de documentos, 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, misma estructura que requirements pero opcionales.

Para configurar allowed_item_types dentro de cada requerimiento, usa solamente los códigos documentados en Tipos de ítem. Al decidir qué código usar, ten en cuenta el country configurado para el flujo. Puedes usar uno o más códigos en cada requerimiento.

La estructura exacta para pasar cada uno de estos valores está claramente definida en la Referencia API.

Reglas de validación (`validation_options.ruleset`)

Cada requerimiento puede incluir reglas de validación que se evalúan automáticamente sobre el documento mediante IA. Se configuran dentro de validation_options.ruleset siguiendo la misma estructura documentada en Reglas de validación — predefinidas (vr_trebol_*) o personalizadas.

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

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.

Valor	Comportamiento
`"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 Aplicativo Web resuelve manualmente.

invalidate (default)
ignore

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".

Cuando un documento falla la validación de tipo o de ruleset:

El widget muestra al prospecto el requerimiento como “en revisión”. No se muestra ningún error.
Desde el Aplicativo Web, el operador ve el requerimiento con estado “Revisión requerida” junto con el detalle de qué falló (status_reasons).
El operador tiene 3 opciones para resolver el documento:
1. Invalidar y pedir nuevo documento: se invalida el documento cargado y se solicita al prospecto que suba otro.
2. Descartar sin acción: no se ejecuta extracción ni se pide otro documento. El requerimiento se marca como resuelto.
3. Aceptar y extraer: se acepta el documento y se elige el tipo de ítem con el cual ejecutar la extracción. El sistema sugiere el tipo de documento que detectó automáticamente.

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.

3. Items del flujo (`flow_items`)

flow_items.items define los items que el flujo captura o ejecuta automáticamente con cada verificación. Se dividen en:

Items del widget (ubos, forms): UI que completa el prospecto.
Consultas a fuentes externas (siger, rues, public_sat_signatures, etc.): Trébol las corre en segundo plano, sin UI.

Ver detalle de cada tipo, opciones disponibles y ejemplos de configuración en Items del flujo.

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.

4. Opciones del flujo (`flow_items.options`)

Configuraciones adicionales bajo la llave options que se aplican a cada verificación creada con este flujo:

creator_email: asocia un email a todas las verificaciones creadas con este 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 la Referencia API.

Ejemplos completos por caso de uso

Cada guía por caso de uso incluye un flujo completo de ejemplo adaptado a su contexto (country, item types, consultas públicas aplicables).

KYB México

Flujo para empresas mexicanas: CSF, acta constitutiva, SIGER, SAT, ubos mx_form.

KYB Colombia

Flujo para empresas colombianas: RUT, Cámara de Comercio, RUES, ubos co_form.

KYB Estados Unidos

Flujo para empresas en EEUU: certificate of incorporation, IRS EIN.

Hipotecas

Flujo para underwriting hipotecario: property_deed, lien_certificate.

Nómina

Flujo para payroll lending: payroll_receipt.

Siguientes pasos

Instalar el widget

Embebe el widget en tu HTML con unas pocas líneas de código.

Personalizar el widget

Configura colores, logo, políticas y textos.

Items del flujo

Detalle de ubos, forms y consultas a fuentes externas.

Estados del expediente

Cómo monitorear el progreso del expediente del usuario final.

Intro al API de Trébol

Guías por caso de uso

Conceptos clave

Regionalización

Compliance (reglas)

Experiencia (UI)

Ejemplo mínimo de un flujo

Estructura del flujo

1. Regionalización (`country`)

2. Requerimientos de documentos (`record_validation_schema`)

Reglas de validación (`validation_options.ruleset`)

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

3. Items del flujo (`flow_items`)

4. Opciones del flujo (`flow_items.options`)

Ejemplos completos por caso de uso

KYB México

KYB Colombia

KYB Estados Unidos

Hipotecas

Nómina

Siguientes pasos

Instalar el widget

Personalizar el widget

Items del flujo

Estados del expediente

Intro al API de Trébol

Guías por caso de uso

Documentation Index

​Conceptos clave

Regionalización

Compliance (reglas)

Experiencia (UI)

​Ejemplo mínimo de un flujo

​Estructura del flujo

​1. Regionalización (country)

​2. Requerimientos de documentos (record_validation_schema)

​Reglas de validación (validation_options.ruleset)

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

​3. Items del flujo (flow_items)

​4. Opciones del flujo (flow_items.options)

​Ejemplos completos por caso de uso

KYB México

KYB Colombia

KYB Estados Unidos

Hipotecas

Nómina

​Siguientes pasos

Instalar el widget

Personalizar el widget

Items del flujo

Estados del expediente

Conceptos clave

Ejemplo mínimo de un flujo

Estructura del flujo

1. Regionalización (`country`)

2. Requerimientos de documentos (`record_validation_schema`)

Reglas de validación (`validation_options.ruleset`)

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

3. Items del flujo (`flow_items`)

4. Opciones del flujo (`flow_items.options`)

Ejemplos completos por caso de uso

Siguientes pasos