Skip to main content
cit_holding_shareholder_structure representa la estructura de propiedad que un documento describe para una empresa y sus holdings. Es un ítem global: 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 de una verificación. Las actas mexicanas (ac_mx, aa_mx) tienen su propia extracción de accionistas, descrita en Extraer accionistas de actas. 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.
El json_schema del proceso de extracción en el catálogo 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.

Enviar documentos y consultar el catálogo

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.

Contrato común de 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.
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.
​
string | null
Fecha de emisión, certificación o protocolización del documento, por ejemplo 2026-09-30.
​
string | null
Nombre de la empresa que sirve de referencia al grafo del documento.
​
string | null
Tipo de identificación fiscal de la empresa de referencia, por ejemplo RFC.
​
string | null
Número de identificación fiscal de la empresa de referencia.
​
array
Empresas incluidas en el grafo de propiedad del documento.

​
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.
  • Contiene al menos un ítem cit_holding_shareholder_structure o un acta mexicana: ac_mx, aa_mx o pw_mx.
  • 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. 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 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}. 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.
​
array
Árbol de propietarios reales del ítem ubos. La conciliación actualiza esta lista cuando obtiene un resultado no vacío.

Respuesta del ítem 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.