> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding de account holder

> El esquema de data y los slots de documentos del tipo de onboarding account_holder: información de la empresa, representantes legales, perfil transaccional y accionistas.

`account_holder` es el tipo de onboarding para abrir una `Entity` mexicana como titular de cuenta. Una vez que Fintoc aprueba la revisión, la `Entity` puede ser titular de objetos `Account`. Esta página documenta el esquema que envías en `data` al crear un onboarding `account_holder` y los slots de documentos que abre el onboarding.

Para el flujo completo, desde crear la `Entity` hasta enviarla a revisión, sigue [Onboarding de una entidad por API](/es/guides/business-accounts/entities/onboard-an-entity-by-api). Esta página cubre solo lo que es específico del tipo `account_holder`.

<Info>
  **Disponibilidad**

  `account_holder` admite objetos `Entity` mexicanos. Crear un onboarding `account_holder` para una `Entity` de otro país devuelve `422 Unprocessable Entity` con el código `country_not_supported`.
</Info>

## La estructura de la solicitud

Envía `type` y `data` en el primer nivel de la solicitud de creación:

```json theme={null}
{
  "type": "account_holder",
  "data": {
    "company_information": { },
    "legal_representatives": [ ],
    "transactional_profile": { },
    "shareholders": [ ]
  }
}
```

El objeto `data` contiene cuatro claves, todas obligatorias. Las secciones siguientes documentan cada una. La referencia de la API describe `data` como un objeto de forma libre, porque su estructura depende de `type`; esta página es el esquema de `account_holder`.

`legal_representatives` y `shareholders` reportan sus errores de forma independiente, así que una respuesta puede traer errores de ambos bloques. `company_information` y `transactional_profile` son la excepción. Fintoc los valida en ese orden y se detiene en el primer bloque que falla. Una solicitud con errores en ambos bloques reporta solo `company_information`.

## company\_information

La identidad de la empresa y sus datos de liquidación. Todos los campos son obligatorios:

| Campo                | Tipo   | Obligatorio | Descripción                                                                                                                     |
| :------------------- | :----- | :---------- | :------------------------------------------------------------------------------------------------------------------------------ |
| `business_activity`  | string | Obligatorio | Actividad económica principal de la empresa.                                                                                    |
| `business_address`   | string | Obligatorio | Dirección física donde opera la empresa.                                                                                        |
| `fiscal_address`     | string | Obligatorio | Dirección registrada ante la autoridad fiscal mexicana.                                                                         |
| `incorporation_date` | string | Obligatorio | Fecha de constitución de la empresa, como fecha ISO 8601. La respuesta devuelve este valor como fecha y hora en UTC (ISO 8601). |
| `phone`              | string | Obligatorio | Teléfono de contacto en formato E.164: un `+` inicial seguido de entre 8 y 15 dígitos, y el primero no puede ser `0`.           |
| `settlement_account` | string | Obligatorio | Cuenta que recibe las liquidaciones, como CLABE (Clave Bancaria Estandarizada) de 18 dígitos.                                   |

<Warning>
  **La validación de la CLABE cambia según el modo**

  `settlement_account` debe tener 18 dígitos. Fintoc acepta el valor cuando los primeros tres dígitos corresponden a una institución mexicana soportada y el dígito de control de la CLABE es correcto. Fintoc también acepta sus propias CLABEs y en esos casos omite el dígito de control. En modo `test`, esto aplica a los códigos de banco de sandbox. En modo `live`, aplica al código de banco propio de Fintoc. Una CLABE de una institución mexicana soportada se comporta igual en ambos modos. Una CLABE de sandbox que funciona en `test` devuelve un error en `live`. Un valor inválido devuelve `400 Bad Request` con el código `invalid_clabe` y `param` en `company_information.settlement_account`.
</Warning>

## legal\_representatives

Las personas autorizadas para actuar en nombre de la empresa. Declara al menos una. Fintoc no impone un máximo, y todos los campos son obligatorios en cada entrada:

| Campo                   | Tipo   | Obligatorio | Descripción                                                                                                                                                                      |
| :---------------------- | :----- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`                 | string | Obligatorio | Correo electrónico del representante legal.                                                                                                                                      |
| `first_name`            | string | Obligatorio | Nombre de pila del representante legal.                                                                                                                                          |
| `identification_number` | string | Obligatorio | Clave Única de Registro de Población (CURP) del representante legal.                                                                                                             |
| `last_name`             | string | Obligatorio | Apellido del representante legal.                                                                                                                                                |
| `nationality`           | string | Obligatorio | Código de país ISO 3166-1 alfa-2 de dos letras de la nacionalidad del representante. Fintoc acepta mayúsculas y minúsculas. La respuesta devuelve el valor tal como lo enviaste. |
| `position`              | string | Obligatorio | Cargo que ocupa el representante legal en la empresa, por ejemplo `Director General`.                                                                                            |

Un arreglo vacío devuelve `400 Bad Request` con el código `legal_representatives_required`. Los errores de este bloque se acumulan entre entradas, y `param` incluye el índice de la entrada que falla, por ejemplo `legal_representatives.0.email`.

## transactional\_profile

El volumen y el origen del dinero que la `Entity` espera mover. Todos los campos son obligatorios:

| Campo                      | Tipo              | Obligatorio | Descripción                                                                                                                                                      |
| :------------------------- | :---------------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `monthly_amount_range`     | string            | Obligatorio | Monto mensual esperado, en pesos mexicanos. Uno de `1_500000` para 1 a 500.000, `500001_1000000` para 500.001 a 1.000.000, o `gt_1000000` para más de 1.000.000. |
| `monthly_operations_range` | string            | Obligatorio | Cantidad mensual esperada de operaciones. Uno de `1_15000` para 1 a 15.000, `15001_50000` para 15.001 a 50.000, o `gte_50001` para 50.001 o más.                 |
| `resource_origins`         | arreglo de string | Obligatorio | De dónde proviene el dinero que mueve la `Entity`. Envía al menos un valor de la lista siguiente.                                                                |

`resource_origins` acepta estos valores:

| Valor de `resource_origins` | Origen de los fondos                        |
| :-------------------------- | :------------------------------------------ |
| `asset_sales`               | Producto de la venta de activos.            |
| `budget_allocations`        | Presupuesto asignado por otra organización. |
| `donations`                 | Donaciones recibidas.                       |
| `investments`               | Rendimientos de inversiones.                |
| `profits`                   | Utilidades operativas de la empresa.        |
| `royalties`                 | Pagos por regalías.                         |
| `trusts`                    | Distribuciones de un fideicomiso.           |

La respuesta repite `transactional_profile` con `declaration_accepted` en `true`, que Fintoc agrega al crear el onboarding. No envíes `declaration_accepted`; la API lo ignora.

## shareholders

El árbol de propiedad de la empresa. Declara al menos un accionista; un arreglo vacío devuelve `400 Bad Request` con el código `shareholders_required`. Cada nodo del árbol, en la raíz y a cualquier profundidad, acepta estos campos:

| Campo         | Tipo                   | Obligatorio                     | Descripción                                                                                                                                                          |
| :------------ | :--------------------- | :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children`    | arreglo de accionistas | Opcional, solo `legal_entity`   | Accionistas que son dueños de este accionista. Envía esto solo cuando `type` es `legal_entity`.                                                                      |
| `holder_id`   | string                 | Obligatorio                     | RFC (identificador fiscal mexicano) del accionista.                                                                                                                  |
| `last_name`   | string                 | Opcional, solo `natural_person` | Apellido del accionista. Envía esto solo cuando `type` es `natural_person`. Enviarlo para un `legal_entity` devuelve `400 Bad Request` con el código `invalid_name`. |
| `name`        | string                 | Obligatorio                     | Nombre de pila cuando `type` es `natural_person`, o razón social cuando `type` es `legal_entity`.                                                                    |
| `nationality` | string                 | Obligatorio                     | Código de país ISO 3166-1 alfa-2 de dos letras de la nacionalidad del accionista. Fintoc acepta mayúsculas o minúsculas y devuelve el valor tal como lo enviaste.    |
| `percentage`  | number                 | Obligatorio                     | Participación que tiene el accionista, de `0` a `100`. Envía un número JSON; la API rechaza un número como string.                                                   |
| `type`        | string                 | Obligatorio                     | Tipo de accionista. Uno de `natural_person` o `legal_entity`.                                                                                                        |

Dos reglas restringen el árbol:

* **Cada nivel suma entre `76` y `100`.** Los porcentajes de la raíz deben sumar al menos `76` y como máximo `100`. Cada arreglo `children` debe cumplir el mismo rango. Un nivel por debajo de `76` devuelve el código `participation_below_threshold`. Un nivel por encima de `100` devuelve el código `shareholder_participation_exceeded`.
* **Solo un `legal_entity` anida.** Un `natural_person` que lleve `children` devuelve el código `only_legal_entity_can_nest`. Un `legal_entity` sin `children` es válido, y Fintoc no revisa la suma de un nivel que no existe. Fintoc no impone un límite de profundidad de anidamiento.

A diferencia de `legal_representatives`, este bloque reporta un error a la vez. Corrige el nodo reportado y reenvía.

## Slots de documentos

Crear el onboarding abre todos los slots que el tipo requiere, y cada uno reporta `missing` hasta que subes un archivo. Todos los slots son obligatorios antes de que puedas enviar el onboarding. El tamaño máximo es 20 MB en todos los slots.

En los slots de la empresa y en los documentos de los accionistas, Fintoc lee el tipo de contenido a partir de los bytes del archivo. El tipo de contenido que declara tu carga no importa. Los dos slots del representante legal revisan ambos valores. Envía el `Content-Type` de la parte como uno de los tipos aceptados de ese slot, porque Fintoc rechaza la carga antes de inspeccionar los bytes.

El onboarding abre cinco slots de la empresa, listados en el arreglo `documents` del primer nivel:

| `slot_key`                     | Tipos de contenido aceptados                 |
| :----------------------------- | :------------------------------------------- |
| `articles_of_incorporation`    | `application/pdf`                            |
| `proof_of_address`             | `application/pdf`, `image/jpeg`, `image/png` |
| `settlement_bank_statement`    | `application/pdf`                            |
| `shareholder_structure`        | `application/pdf`                            |
| `tax_registration_certificate` | `application/pdf`                            |

Cada representante legal tiene su propio arreglo `documents` con dos slots:

| `slot_key`          | Tipos de contenido aceptados                 |
| :------------------ | :------------------------------------------- |
| `identification`    | `application/pdf`, `image/jpeg`, `image/png` |
| `power_of_attorney` | `application/pdf`                            |

Cada accionista tiene un único objeto `document` en lugar de un arreglo, porque un accionista tiene exactamente un documento. Fintoc elige el slot a partir del `type` del accionista, así que la ruta de carga no lleva `slot_key`:

| `type` del accionista | `slot_key`                  | Tipos de contenido aceptados                 |
| :-------------------- | :-------------------------- | :------------------------------------------- |
| `legal_entity`        | `articles_of_incorporation` | `application/pdf`, `image/jpeg`, `image/png` |
| `natural_person`      | `identification`            | `application/pdf`, `image/jpeg`, `image/png` |

Una empresa con un representante legal y tres accionistas abre entonces diez slots: cinco de la empresa, dos del representante y uno por accionista.

## Un ejemplo completo

Este payload declara un representante legal y dos accionistas raíz. Uno de los accionistas raíz anida un tercer accionista. Todos los valores son datos de prueba que no corresponden a ninguna empresa ni persona real. El `settlement_account` es una CLABE de prueba documentada. Fintoc la acepta porque su código de banco y su dígito de control son válidos. Una CLABE de puros ceros devuelve `400 Bad Request`, porque `000` no es un código de banco soportado.

```json theme={null}
{
  "type": "account_holder",
  "data": {
    "company_information": {
      "business_activity": "Servicios financieros",
      "business_address": "Av. Insurgentes 456, CDMX",
      "fiscal_address": "Av. Reforma 123, CDMX",
      "incorporation_date": "2020-01-15",
      "phone": "+521111111111",
      "settlement_account": "646969000000000000"
    },
    "legal_representatives": [
      {
        "first_name": "Test Customer 1",
        "last_name": "Customer",
        "email": "rep@example.com",
        "nationality": "mx",
        "identification_number": "AAAA010101HDFAAA01",
        "position": "Director General"
      }
    ],
    "transactional_profile": {
      "resource_origins": ["trusts", "investments"],
      "monthly_amount_range": "1_500000",
      "monthly_operations_range": "1_15000"
    },
    "shareholders": [
      {
        "type": "natural_person",
        "name": "Test Customer 2",
        "last_name": "Customer",
        "holder_id": "AAAA010101AAA",
        "nationality": "mx",
        "percentage": 60
      },
      {
        "type": "legal_entity",
        "name": "Test Entity 2",
        "holder_id": "AAA010101AAA",
        "nationality": "mx",
        "percentage": 40,
        "children": [
          {
            "type": "natural_person",
            "name": "Test Customer 3",
            "last_name": "Customer",
            "holder_id": "AAAA010101AAA",
            "nationality": "mx",
            "percentage": 80
          }
        ]
      }
    ]
  }
}
```

## Qué sigue

* [Onboarding de una entidad por API](/es/guides/business-accounts/entities/onboard-an-entity-by-api) para el flujo completo, incluidas las cargas, el envío y la revisión.
* [Requisitos de KYC para México](/es/guides/business-accounts/kyc-requirements/mexico) para los documentos que revisa el equipo de cumplimiento de Fintoc.
* [El objeto Onboarding](/es/api/business-accounts-api/onboardings/onboarding-object) para los atributos de la respuesta.