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

# Crear el flujo

> Diseña y gestiona flujos de onboarding reutilizables para el widget.

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.

<Note>
  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](https://docs.gotrebol.com/api-reference/gestión-de-flujos-de-cuenta/crear-nuevo-flujo).
</Note>

## Conceptos clave

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

<CardGroup cols={3}>
  <Card title="Regionalización" icon="globe">
    **`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.
  </Card>

  <Card title="Compliance (reglas)" icon="shield-check">
    **`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**.
  </Card>

  <Card title="Experiencia (UI)" icon="laptop-file">
    **`flow_items`** Define items adicionales: formularios, beneficiarios reales y consultas a fuentes externas que Trébol ejecuta automáticamente con cada verificación.
  </Card>
</CardGroup>

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

```json theme={"dark"}
{
  "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.

<Warning>
  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.
</Warning>

<Warning>
  **Límite de tamaño del payload (200 KB)**

  El cuerpo de las solicitudes a los endpoints de account-flows y [form schemas](https://docs.gotrebol.com/api-reference/gestión-de-esquemas-de-formularios/crear-nuevo-esquema-de-formulario) 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`.
</Warning>

## 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](/docs/guia-devs/referencia/tipos-item). 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.

<Warning>
  La estructura exacta para pasar cada uno de estos valores está claramente definida en la [Referencia API](https://docs.gotrebol.com/api-reference/gestión-de-flujos-de-cuenta/crear-nuevo-flujo#body-record-validation-schema-requirements).
</Warning>

#### 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](/docs/guia-devs/crear-verificaciones/via-api/reglas-validacion) — predefinidas (`vr_trebol_*`) o personalizadas.

```json Ejemplo de requerimiento con ruleset theme={"dark"}
{
  "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. |

<Tabs>
  <Tab title="invalidate (default)">
    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"`.
  </Tab>

  <Tab title="ignore">
    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.
  </Tab>
</Tabs>

<Note>
  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.
</Note>

### 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](/docs/guia-devs/crear-verificaciones/via-widget/items).

<Warning>
  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.
</Warning>

### 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](https://docs.gotrebol.com/api-reference/gestión-de-flujos-de-cuenta/crear-nuevo-flujo#response-flow-items-options-next-steps-checkout).

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

<CardGroup cols={2}>
  <Card title="KYB México" href="/docs/guia-devs/uso-kyb/mexico/overview#ejemplo-de-flujo-completo">
    Flujo para empresas mexicanas: CSF, acta constitutiva, SIGER, SAT, ubos mx\_form.
  </Card>

  <Card title="KYB Colombia" href="/docs/guia-devs/uso-kyb/colombia/overview#ejemplo-de-flujo-completo">
    Flujo para empresas colombianas: RUT, Cámara de Comercio, RUES, ubos co\_form.
  </Card>

  <Card title="KYB Estados Unidos" href="/docs/guia-devs/uso-kyb/eeuu/overview#ejemplo-de-flujo-completo">
    Flujo para empresas en EEUU: certificate of incorporation, IRS EIN.
  </Card>

  <Card title="Hipotecas" href="/docs/guia-devs/uso-hipotecas/overview#ejemplo-de-flujo-completo">
    Flujo para underwriting hipotecario: property\_deed, lien\_certificate.
  </Card>

  <Card title="Nómina" href="/docs/guia-devs/uso-nomina/overview#ejemplo-de-flujo-completo">
    Flujo para payroll lending: payroll\_receipt.
  </Card>
</CardGroup>

## Siguientes pasos

<CardGroup cols={2}>
  <Card title="Instalar el widget" href="/docs/guia-devs/crear-verificaciones/via-widget/instalar">
    Embebe el widget en tu HTML con unas pocas líneas de código.
  </Card>

  <Card title="Personalizar el widget" href="/docs/guia-devs/crear-verificaciones/via-widget/personalizar">
    Configura colores, logo, políticas y textos.
  </Card>

  <Card title="Items del flujo" href="/docs/guia-devs/crear-verificaciones/via-widget/items">
    Detalle de ubos, forms y consultas a fuentes externas.
  </Card>

  <Card title="Estados del expediente" href="/docs/guia-devs/crear-verificaciones/via-widget/estados-expediente">
    Cómo monitorear el progreso del expediente del usuario final.
  </Card>
</CardGroup>