> ## 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. # Estructura accionaria de holdings > Interpreta el grafo de cit_holding_shareholder_structure y conoce los requisitos de su conciliación automática en el ítem ubos. `cit_holding_shareholder_structure` representa la estructura de propiedad que un documento describe para una empresa y sus holdings. Es un [ítem global](https://gotrebol.com/docs/guia-devs/uso-kyb/todos-paises/items-globales.md): Trébol mantiene el tipo y sus procesos. El resultado es un grafo que relaciona empresas y accionistas mediante identificadores dentro del documento. Trébol puede usarlo junto con otros documentos accionarios para conciliar los [propietarios reales](https://gotrebol.com/docs/guia-devs/referencia/respuestas-por-tipo-de-item.md#ubos) de una verificación. Las actas mexicanas (`ac_mx`, `aa_mx`) tienen su propia extracción de accionistas, descrita en [Extraer accionistas de actas](https://gotrebol.com/docs/guia-devs/uso-kyb/mexico/accionistas.md). Este tipo cubre documentos que describen la cadena de propiedad de varias empresas, como la de un grupo con holdings. La conciliación combina ambas fuentes en el ítem `ubos`. > [!NOTE] > > El `json_schema` del proceso de extracción en el [catálogo](https://gotrebol.com/docs/guia-devs/uso-kyb/todos-paises/items-globales.md) define los campos exigidos y sus valores admitidos. > Esta guía describe los campos de un resultado actual y cómo los usa la conciliación. ## Requisitos y envío Necesitas un documento legible que describa la estructura accionaria. Trébol debe poder descargarlo y abrirlo durante el procesamiento. La extracción del documento no requiere que la verificación tenga un ítem `ubos`. La conciliación automática en ese ítem tiene requisitos adicionales, descritos más adelante. Usa la clasificación automática con `generic`, sin `client_item_type`. La clasificación depende del contenido del documento. Comprueba que el `item_type` final sea `cit_holding_shareholder_structure` antes de interpretar sus campos como este grafo. > [card] [Enviar documentos y consultar el catálogo](https://gotrebol.com/docs/guia-devs/uso-kyb/todos-paises/items-globales.md) > > Consulta las solicitudes de ejemplo, las opciones de archivo y contraseña, y las limitaciones del envío explícito de nombres globales. ## Identificar el resultado Consulta `GET /verification-items/{id}` después del procesamiento. Busca en `item_value.pipeline.extraction` el proceso con `process_reference: "extraer estructura accionaria"`. Esa es la referencia vigente del proceso de extracción. Trébol puede actualizar los procesos globales. Toma la referencia del proceso de extracción activo en el catálogo en lugar de fijarla en tu código. Antes de leer `value`, comprueba `executed: true` y `execution_result: "success"`. Si la consulta devuelve un error HTTP, revisa [Errores](https://gotrebol.com/docs/guia-devs/errores.md). > [card] [Contrato común de resultados](https://gotrebol.com/docs/producto/guias/tipos-de-item-personalizados.md#donde-salen-los-resultados) > > Consulta el estado de cada proceso, los errores y la estructura pública de `item_value.pipeline`. ### Ejemplo de resultado El siguiente ejemplo sigue la estructura de un resultado real, con datos ficticios. Omite los campos del archivo, como `original_file_url`, porque no forman parte del grafo. ```json theme={"dark"} { "id": 12345, "item_type": "cit_holding_shareholder_structure", "item_status": "complete", "item_value": { "current_stage": "extraction", "pipeline": { "validation": [], "extraction": [ { "process_reference": "extraer estructura accionaria", "executed": true, "execution_result": "success", "value": { "document_date": "2026-09-30", "root_company_name": "Compañía Ejemplo, S.A. de C.V.", "root_company_tax_id_type": "RFC", "root_company_tax_id_number": "CEJ200101AB1", "companies": [ { "id": "c1", "company_name": "Compañía Ejemplo, S.A. de C.V.", "is_root": true, "business_type": "S.A. de C.V.", "nationality": "Mexico", "nationality_code": "MX", "currency": "MXN", "total_shares": 100, "total_amount": 100000, "authorized_capital": 100000, "shareholders": [ { "id": "c2", "name": "Holding Ejemplo, S. de R.L. de C.V.", "type": "business", "business_type": "S. de R.L. de C.V.", "nationality": "Mexico", "nationality_code": "MX", "id_number": null, "share_count": 99, "share_amount": 99000, "share_percentage": 99, "email": null, "phone": null, "occupation": null }, { "name": "Ana Ejemplo", "type": "person", "business_type": null, "nationality": "Mexico", "nationality_code": "MX", "id_number": "EJAA800101AB1", "share_count": 1, "share_amount": 1000, "share_percentage": 1, "email": "ana@ejemplo.com", "phone": "+52 55 5555 0101", "occupation": "Empresaria" } ] }, { "id": "c2", "company_name": "Holding Ejemplo, S. de R.L. de C.V.", "is_root": false, "business_type": "S. de R.L. de C.V.", "nationality": "Mexico", "nationality_code": "MX", "currency": "MXN", "total_shares": 100, "total_amount": 50000, "authorized_capital": 50000, "shareholders": [ { "name": "Ana Ejemplo", "type": "person", "business_type": null, "nationality": "Mexico", "nationality_code": "MX", "id_number": "EJAA800101AB1", "share_count": 60, "share_amount": 30000, "share_percentage": 60, "email": "ana@ejemplo.com", "phone": "+52 55 5555 0101", "occupation": "Empresaria" }, { "name": "Luis Ejemplo", "type": "person", "business_type": null, "nationality": "Mexico", "nationality_code": "MX", "id_number": "EJLL750505CD2", "share_count": 40, "share_amount": 20000, "share_percentage": 40, "email": null, "phone": null, "occupation": null } ] } ] } } ] } } } ``` En este ejemplo, `c1` es la empresa raíz. Su accionista con `id: "c2"` es Holding Ejemplo, que aparece como segunda empresa del grafo con sus propios accionistas. Los identificadores relacionan entidades dentro del resultado del documento. No son los identificadores de los ítems de verificación. `share_percentage` es el porcentaje local de cada accionista en su empresa. Para obtener la participación efectiva, multiplica los porcentajes a lo largo de la cadena. Ana Ejemplo tiene 1 % directo de la empresa raíz. También tiene 60 % de Holding Ejemplo, que tiene 99 % de la empresa raíz. Su participación efectiva es 1 % + 99 % × 60 % = 60.4 %. ### Campos del resultado Estos campos pertenecen al `value` del proceso de extracción. Un campo con `null` indica que el dato no está disponible o no aplica. **document\_date** `string | null` Fecha de emisión, certificación o protocolización del documento, por ejemplo `2026-09-30`. **root\_company\_name** `string | null` Nombre de la empresa que sirve de referencia al grafo del documento. **root\_company\_tax\_id\_type** `string | null` Tipo de identificación fiscal de la empresa de referencia, por ejemplo `RFC`. **root\_company\_tax\_id\_number** `string | null` Número de identificación fiscal de la empresa de referencia. **companies** `array` Empresas incluidas en el grafo de propiedad del documento. **campos de cada empresa** **id** `string` Identificador de la empresa dentro del grafo. Un accionista que es otra empresa del grafo usa este valor en su `id`. **company\_name** `string` Nombre de la empresa representada en esa entrada. **is\_root** `boolean` `true` para la empresa raíz del grafo. **business\_type** `string | null` Tipo societario, por ejemplo `S.A. de C.V.`. **nationality** `string | null` País de la empresa, como aparece en la extracción. **nationality\_code** `string | null` Código del país de la empresa, por ejemplo `MX`. **currency** `string | null` Moneda de los importes de capital, por ejemplo `MXN`. **total\_shares** `number | null` Total de acciones o partes sociales de la empresa. **total\_amount** `number | null` Importe total del capital que representan esas acciones o partes sociales. **authorized\_capital** `number | null` Capital social autorizado de la empresa. **shareholders** `array` Accionistas de la empresa representada en esa entrada. Puede venir vacío. **campos de cada accionista** **id** `string` Si el accionista es otra empresa del grafo, contiene el `id` de esa empresa. **name** `string` Nombre del accionista. **type** `string` `person` para una persona física o `business` para una empresa. **business\_type** `string | null` Tipo societario, cuando el accionista es una empresa. **nationality** `string | null` País del accionista, como aparece en la extracción. **nationality\_code** `string | null` Código del país del accionista, por ejemplo `MX`. **id\_number** `string | null` Número de identificación del accionista que aparece en el documento. **share\_count** `number | null` Número de acciones o partes sociales del accionista en esa empresa. **share\_amount** `number | null` Importe del capital del accionista en esa empresa. **share\_percentage** `number | null` Porcentaje local del accionista en esa empresa. No es la participación efectiva desde la empresa raíz. **email** `string | null` Correo del accionista, cuando el documento lo incluye. **phone** `string | null` Teléfono del accionista, cuando el documento lo incluye. **occupation** `string | null` Ocupación del accionista, cuando el documento la incluye. ## Conciliación automática en ubos La conciliación reúne los documentos accionarios de una verificación y actualiza su árbol de propietarios reales. Es un proceso asíncrono separado de la extracción de cada documento. Para que se evalúe, la verificación debe cumplir estas condiciones: * Contiene un ítem [`ubos`](https://gotrebol.com/docs/guia-devs/referencia/respuestas-por-tipo-de-item#ubos). * Contiene al menos un ítem `cit_holding_shareholder_structure` o un acta mexicana: [`ac_mx`, `aa_mx` o `pw_mx`](https://gotrebol.com/docs/guia-devs/uso-kyb/mexico/items-documentos). * Tiene al menos un ítem no opcional con archivo y todos los ítems no opcionales con archivo están completos. * No se creó desde el [widget](https://gotrebol.com/docs/guia-devs/crear-verificaciones/via-widget/overview.md). En ese flujo, la persona completa el formulario de propietarios reales y la conciliación no lo modifica. Para incorporar este grafo, la extracción debe ser exitosa y contener `companies`. Si varios documentos describen la misma empresa, la conciliación da prioridad al más reciente, sea un acta o este grafo. Compara la fecha de cada acta con el `document_date` del grafo. Si `document_date` es `null`, prefiere un documento fechado de la misma empresa. ### Cuándo consultar el resultado Trébol evalúa la conciliación cuando pasan unos minutos sin que se complete otro documento accionario. Cada documento accionario completado reinicia esa espera. Después, el análisis de los documentos tarda un tiempo adicional. Una extracción completa no implica que la conciliación ya terminó. La conciliación no tiene un evento de webhook propio. Usa los [webhooks](https://gotrebol.com/docs/guia-devs/webhooks.md) para saber cuándo terminan los documentos y consulta el ítem `ubos` después de ese periodo. Si sus datos no cambian, revisa las condiciones anteriores y el resultado de la extracción. ### Empresa objetivo La conciliación usa como empresa objetivo el `business_name` de la verificación. Trébol obtiene ese nombre de los documentos y lo devuelve en [`GET /verifications/{id}`](https://gotrebol.com/docs/api-reference/leer-información-de-la-empresa/obtener-una-verificación-por-su-id). La conciliación no lo sustituye por el nombre de otro documento. Comprueba que identifica la empresa que quieres analizar. ### Resultado en el ítem ubos Un resultado no vacío reemplaza los datos existentes en `item_value.ubos.data` del ítem `ubos`. Consulta ese ítem para obtener el árbol conciliado. Los campos de cada propietario dependen del formulario de propietarios reales configurado para el ítem, como `mx_form` o `co_form`. El árbol anida los accionistas de cada empresa dentro de ella y conserva el porcentaje local de cada nivel. Trébol no calcula la participación efectiva; obtenla multiplicando los porcentajes a lo largo de la cadena, como en el ejemplo del grafo. **item\_value.ubos.data** `array` Árbol de propietarios reales del ítem `ubos`. La conciliación actualiza esta lista cuando obtiene un resultado no vacío. > [card] [Respuesta del ítem ubos](https://gotrebol.com/docs/guia-devs/referencia/respuestas-por-tipo-de-item.md#ubos) > > Consulta un ejemplo de `item_value.ubos.data` y los campos de cada propietario. ## Limitaciones * El grafo de extracción describe un documento. La conciliación integra ese grafo con los demás documentos accionarios admitidos de la verificación. * Los datos que no aplican a un accionista pueden venir con `null` o con valores incoherentes. Revisa `email`, `phone`, `id_number` y `occupation` antes de usarlos, sobre todo en accionistas `business`. * La suma de `share_percentage` en una empresa puede no llegar a 100 si el documento no detalla a todos sus accionistas. * Si faltan los requisitos de conciliación, el grafo extraído puede estar disponible sin una actualización automática de `ubos`. * Un resultado vacío de conciliación conserva los datos existentes en `ubos`. No interpretes esos datos como prueba de una conciliación reciente. * Si cambia el contenido utilizado mientras se concilia, Trébol descarta el resultado anterior y evalúa nuevamente los documentos tras su procesamiento. * Los campos admitidos y las reglas configuradas dependen del esquema y los procesos vigentes del catálogo. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.