Account Flows

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ón	Tipo	Descripción
`ubos_data_extraction`	`boolean`	Extrae 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_threshold`	`number`	Porcentaje 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_optional`	`boolean`	Si es `true`, el prospecto puede omitir esta sección.

mx_form
co_form

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

Lista de países y nacionalidades disponibles

Los campos de nacionalidad y país en los formularios de propietarios reales (ubos) utilizan la lista completa de 249 países y territorios según el estándar ISO 3166-1 alpha-2. Los nombres y gentilicios se muestran en español.

Código	País	Nacionalidad
`AF`	Afganistán	Afgano
`AX`	Islas Åland	Alandés
`AL`	Albania	Albanés
`DE`	Alemania	Alemán
`AD`	Andorra	Andorrano
`AO`	Angola	Angoleño
`AI`	Anguila	Anguilano
`AQ`	Antártida	Antártico
`AG`	Antigua y Barbuda	Antiguano
`SA`	Arabia Saudita	Saudí
`DZ`	Argelia	Argelino
`AR`	Argentina	Argentino
`AM`	Armenia	Armenio
`AW`	Aruba	Arubeño
`AU`	Australia	Australiano
`AT`	Austria	Austriaco
`AZ`	Azerbaiyán	Azerbaiyano
`BS`	Bahamas	Bahameño
`BD`	Bangladés	Bangladesí
`BB`	Barbados	Barbadense
`BH`	Baréin	Bareiní
`BE`	Bélgica	Belga
`BZ`	Belice	Beliceño
`BJ`	Benín	Beninés
`BM`	Bermudas	Bermudeño
`BY`	Bielorrusia	Bielorruso
`BO`	Bolivia	Boliviano
`BQ`	Bonaire, San Eustaquio y Saba	Caribeño Neerlandés
`BA`	Bosnia y Herzegovina	Bosnio
`BW`	Botsuana	Botsuano
`BV`	Isla Bouvet	Bouvetense
`BR`	Brasil	Brasileño
`BN`	Brunéi	Bruneano
`BG`	Bulgaria	Búlgaro
`BF`	Burkina Faso	Burkinés
`BI`	Burundi	Burundés
`BT`	Bután	Butanés
`CV`	Cabo Verde	Caboverdiano
`KY`	Islas Caimán	Caimanés
`KH`	Camboya	Camboyano
`CM`	Camerún	Camerunés
`CA`	Canadá	Canadiense
`QA`	Catar	Catarí
`TD`	Chad	Chadiano
`CL`	Chile	Chileno
`CN`	China	Chino
`CY`	Chipre	Chipriota
`VA`	Ciudad del Vaticano	Vaticano
`CO`	Colombia	Colombiano
`KM`	Comoras	Comorense
`KP`	Corea del Norte	Norcoreano
`KR`	Corea del Sur	Surcoreano
`CI`	Costa de Marfil	Marfileño
`CR`	Costa Rica	Costarricense
`HR`	Croacia	Croata
`CU`	Cuba	Cubano
`CW`	Curazao	Curazoleño
`DK`	Dinamarca	Danés
`DM`	Dominica	Dominiqués
`EC`	Ecuador	Ecuatoriano
`EG`	Egipto	Egipcio
`SV`	El Salvador	Salvadoreño
`AE`	Emiratos Árabes Unidos	Emiratí
`ER`	Eritrea	Eritreo
`SK`	Eslovaquia	Eslovaco
`SI`	Eslovenia	Esloveno
`ES`	España	Español
`US`	Estados Unidos	Estadounidense
`EE`	Estonia	Estonio
`SZ`	Esuatini	Suazi
`ET`	Etiopía	Etíope
`PH`	Filipinas	Filipino
`FI`	Finlandia	Finlandés
`FJ`	Fiyi	Fiyiano
`FR`	Francia	Francés
`GA`	Gabón	Gabonés
`GM`	Gambia	Gambiano
`GE`	Georgia	Georgiano
`GH`	Ghana	Ghanés
`GI`	Gibraltar	Gibraltareño
`GD`	Granada	Granadino
`GR`	Grecia	Griego
`GL`	Groenlandia	Groenlandés
`GP`	Guadalupe	Guadalupeño
`GU`	Guam	Guameño
`GT`	Guatemala	Guatemalteco
`GF`	Guayana Francesa	Guayanés Francés
`GG`	Guernsey	Guerneseyano
`GN`	Guinea	Guineano
`GQ`	Guinea Ecuatorial	Ecuatoguineano
`GW`	Guinea-Bisáu	Guineano-Bisauense
`GY`	Guyana	Guyanés
`HT`	Haití	Haitiano
`HM`	Islas Heard y McDonald	Heardense
`HN`	Honduras	Hondureño
`HK`	Hong Kong	Hongkonés
`HU`	Hungría	Húngaro
`IN`	India	Indio
`ID`	Indonesia	Indonesio
`IQ`	Irak	Iraquí
`IR`	Irán	Iraní
`IE`	Irlanda	Irlandés
`IM`	Isla de Man	Manés
`CX`	Isla de Navidad	Navideño
`NF`	Isla Norfolk	Norfolkense
`IS`	Islandia	Islandés
`CC`	Islas Cocos	Cocosiano
`CK`	Islas Cook	Cookiano
`FO`	Islas Feroe	Feroés
`GS`	Islas Georgias del Sur y Sandwich del Sur	Georgiano del Sur
`FK`	Islas Malvinas	Malvinense
`MP`	Islas Marianas del Norte	Mariano del Norte
`MH`	Islas Marshall	Marshalés
`PN`	Islas Pitcairn	Pitcairnense
`SB`	Islas Salomón	Salomonense
`TC`	Islas Turcas y Caicos	Turcocaiqueño
`UM`	Islas Ultramarinas Menores de EE.UU.	Estadounidense
`VG`	Islas Vírgenes Británicas	Virgenense Británico
`VI`	Islas Vírgenes de EE.UU.	Virgenense Estadounidense
`IL`	Israel	Israelí
`IT`	Italia	Italiano
`JM`	Jamaica	Jamaicano
`JP`	Japón	Japonés
`JE`	Jersey	Jerseyano
`JO`	Jordania	Jordano
`KZ`	Kazajistán	Kazajo
`KE`	Kenia	Keniano
`KG`	Kirguistán	Kirguís
`KI`	Kiribati	Kiribatiano
`KW`	Kuwait	Kuwaití
`LA`	Laos	Laosiano
`LS`	Lesoto	Lesotense
`LV`	Letonia	Letón
`LB`	Líbano	Libanés
`LR`	Liberia	Liberiano
`LY`	Libia	Libio
`LI`	Liechtenstein	Liechtensteiniano
`LT`	Lituania	Lituano
`LU`	Luxemburgo	Luxemburgués
`MO`	Macao	Macaense
`MG`	Madagascar	Malgache
`MY`	Malasia	Malasio
`MW`	Malaui	Malauí
`MV`	Maldivas	Maldivo
`ML`	Malí	Maliense
`MT`	Malta	Maltés
`MA`	Marruecos	Marroquí
`MQ`	Martinica	Martiniqués
`MU`	Mauricio	Mauriciano
`MR`	Mauritania	Mauritano
`YT`	Mayotte	Mayotense
`MX`	México	Mexicano
`FM`	Micronesia	Micronesio
`MD`	Moldavia	Moldavo
`MC`	Mónaco	Monegasco
`MN`	Mongolia	Mongol
`ME`	Montenegro	Montenegrino
`MS`	Montserrat	Montserratino
`MZ`	Mozambique	Mozambiqueño
`MM`	Myanmar	Birmano
`NA`	Namibia	Namibio
`NR`	Nauru	Nauruano
`NP`	Nepal	Nepalí
`NI`	Nicaragua	Nicaragüense
`NE`	Níger	Nigerino
`NG`	Nigeria	Nigeriano
`NU`	Niue	Niuano
`NO`	Noruega	Noruego
`NC`	Nueva Caledonia	Neocaledonio
`NZ`	Nueva Zelanda	Neozelandés
`OM`	Omán	Omaní
`NL`	Países Bajos	Neerlandés
`PK`	Pakistán	Paquistaní
`PW`	Palaos	Palauano
`PS`	Palestina	Palestino
`PA`	Panamá	Panameño
`PG`	Papúa Nueva Guinea	Papú
`PY`	Paraguay	Paraguayo
`PE`	Perú	Peruano
`PF`	Polinesia Francesa	Polinesio Francés
`PL`	Polonia	Polaco
`PT`	Portugal	Portugués
`PR`	Puerto Rico	Puertorriqueño
`GB`	Reino Unido	Británico
`CF`	República Centroafricana	Centroafricano
`CZ`	República Checa	Checo
`MK`	República de Macedonia del Norte	Macedonio
`CD`	República Democrática del Congo	Congoleño
`CG`	República del Congo	Congoleño
`DO`	República Dominicana	Dominicano
`SS`	Sudán del Sur	Sursudanés
`RE`	Reunión	Reunionés
`RW`	Ruanda	Ruandés
`RO`	Rumania	Rumano
`RU`	Rusia	Ruso
`EH`	Sahara Occidental	Saharaui
`WS`	Samoa	Samoano
`AS`	Samoa Americana	Samoano Americano
`BL`	San Bartolomé	Bartolomeano
`KN`	San Cristóbal y Nieves	Sancristobaleño
`SM`	San Marino	Sanmarinense
`MF`	San Martín	Sanmartinense
`PM`	San Pedro y Miquelón	Sanpedrino
`VC`	San Vicente y las Granadinas	Sanvicentino
`SH`	Santa Elena, Ascensión y Tristán de Acuña	Santalenense
`LC`	Santa Lucía	Santalucense
`ST`	Santo Tomé y Príncipe	Santotomense
`SN`	Senegal	Senegalés
`RS`	Serbia	Serbio
`SC`	Seychelles	Seychellense
`SL`	Sierra Leona	Sierraleonés
`SG`	Singapur	Singapurense
`SX`	Sint Maarten	Sintmaartenense
`SY`	Siria	Sirio
`SO`	Somalia	Somalí
`LK`	Sri Lanka	Esrilanqués
`ZA`	Sudáfrica	Sudafricano
`SD`	Sudán	Sudanés
`SE`	Suecia	Sueco
`CH`	Suiza	Suizo
`SR`	Surinam	Surinamés
`SJ`	Svalbard y Jan Mayen	Svalbardense
`TH`	Tailandia	Tailandés
`TW`	Taiwán	Taiwanés
`TZ`	Tanzania	Tanzano
`TJ`	Tayikistán	Tayiko
`IO`	Territorio Británico del Océano Índico	Británico del Índico
`TF`	Tierras Australes y Antárticas Francesas	Francés Austral
`TL`	Timor Oriental	Timorense
`TG`	Togo	Togolés
`TK`	Tokelau	Tokelauano
`TO`	Tonga	Tongano
`TT`	Trinidad y Tobago	Trinitense
`TN`	Túnez	Tunecino
`TM`	Turkmenistán	Turkmeno
`TR`	Turquía	Turco
`TV`	Tuvalu	Tuvaluano
`UA`	Ucrania	Ucraniano
`UG`	Uganda	Ugandés
`UY`	Uruguay	Uruguayo
`UZ`	Uzbekistán	Uzbeko
`VU`	Vanuatu	Vanuatuense
`VE`	Venezuela	Venezolano
`VN`	Vietnam	Vietnamita
`WF`	Wallis y Futuna	Wallisiano
`YE`	Yemen	Yemení
`DJ`	Yibuti	Yibutiano
`ZM`	Zambia	Zambiano
`ZW`	Zimbabue	Zimbabuense

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.

Campo	Tipo	Cuándo aplica	Descripción
`id`	`string`	Siempre requerido	Identificador de la regla. Para reglas predefinidas de Trébol usa `vr_trebol_*`. Para reglas personalizadas, cualquier identificador único.
`error_message`	`string`	Requerido en account flow	Mensaje 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_rule`	`string`	Solo reglas personalizadas	Texto completo de la pregunta de validación. No incluir en reglas predefinidas de Trébol (`vr_trebol_*`).
`params`	`object`	Solo reglas predefinidas	Pará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.

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 dashboard resuelve manualmente desde la webapp.

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 la webapp, 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.

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.

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.

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.

Intro al API de Trébol

Log Stream

Conceptos Clave

Experiencia (UI)

Compliance (Reglas)

Regionalización

Estructura del Flujo

1. Configurando la Experiencia (`flow_items`)

2. Definiendo Reglas de Negocio (`record_validation_schema`)

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

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

3. Regionalización (`country`)

Ejemplo de Configuración

Tipos de Documentos Soportados

Intro al API de Trébol

Log Stream

​Conceptos Clave

Experiencia (UI)

Compliance (Reglas)

Regionalización

​Estructura del Flujo

​1. Configurando la Experiencia (flow_items)

​2. Definiendo Reglas de Negocio (record_validation_schema)

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

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

​3. Regionalización (country)

​Ejemplo de Configuración

​Tipos de Documentos Soportados

Conceptos Clave

Estructura del Flujo

1. Configurando la Experiencia (`flow_items`)

2. Definiendo Reglas de Negocio (`record_validation_schema`)

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

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

3. Regionalización (`country`)

Ejemplo de Configuración

Tipos de Documentos Soportados