Extraer Accionistas de Actas

API KYB: Verificación de Accionistas

Este endpoint permite extraer información detallada de los accionistas de una empresa para el proceso de onboarding de empresas y API KYB. Utiliza OCR de actas constitutivas y otros documentos relevantes para validar la identidad y la estructura accionarial de la entidad.

Campos de Respuesta

Accionistas mas recientes

Trebol dectecta la Lista de accionistas de la empresa en las actas y además condensa la información de las actas con la información de los documentos de personas que se subieron. Los siguientes son los campos que se devuelven:

Nombre	Campo y Tipo	Descripción
ID del Accionista	`id` (integer)	Identificador único del accionista utilizado para referenciar internamente
Moneda	`currency` (string)	Moneda en la que se valoran las acciones (ej: “MXN”)
Acciones Fijas	`fixed_shares` (string)	Número de acciones que no están sujetas a variaciones
Valor de Acciones Fijas	`fixed_value` (string)	Valor monetario de las acciones fijas
Número de Identificación	`id_number` (string)	Número de identificación fiscal (RFC) del accionista
Tipo de Identificación	`id_type` (string)	Tipo de documento de identificación utilizado (ej: “RFC”)
Nombre	`name` (string)	Nombre completo del accionista
Nacionalidad	`nationality` (string)	País de origen del accionista
Total de Acciones	`total_shares` (string)	Cantidad total de acciones en posesión del accionista
Valor Total	`total_value` (string)	Valoración económica total de las acciones
Tipo de Accionista	`type` (string)	Categoría del accionista (ej: “Persona”)
Acciones Variables	`variable_shares` (string)	Número de acciones sujetas a cambios o condiciones
Valor de Acciones Variables	`variable_value` (string)	Valor monetario de las acciones variables
Porcentaje de Participación	`share_percentage` (integer)	Porcentaje de propiedad en la empresa
Estado AML	`aml_validation_status` (string)	Estado de las verificaciones anti-lavado de dinero
Categorías de Riesgo AML	`aml_risk_category` (array)	Lista de categorías de riesgo identificadas
Datos AML	`aml_data` (array)	Información complementaria sobre verificaciones AML
Información de Identidad	`identity` (object)	Datos de identificación oficial del accionista
Información Fiscal	`fiscal` (object)	Datos fiscales y tributarios del accionista
Dirección	`address` (object)	Datos de ubicación física del accionista

Información sobre el capital social de la empresa según el acta más reciente.

Nombre	Campo y Tipo	Descripción
Valor Fijo del Capital	`fixed_value` (string)	Muestra la parte del capital que está establecida y no sujeta a cambios, ayudando a entender la solidez financiera fija de la empresa
Acciones Fijas del Capital	`fixed_shares` (string)	Cantidad de acciones que representan el capital fijo, esencial para evaluar la distribución establecida del capital
Valor Variable del Capital	`variable_value` (string)	Indica la parte del capital que puede variar, importante para analizar posibles cambios en la estructura de capital
Acciones Variables del Capital	`variable_shares` (string)	Cantidad de acciones sujetas a variaciones, crucial para entender posibles diluciones o incrementos en la propiedad
Valor Total del Capital	`total_value` (string)	Valor total combinado del capital fijo y variable, fundamental para evaluar la valoración completa de la empresa
Acciones Totales del Capital	`total_shares` (string)	Número total de acciones emitidas, importante para calcular el porcentaje de participación accionarial

Fuente de donde se obtuvo la lista de accionistas

Información del documento del que se extrajo la lista de accionistas, siguiendo el esquema V2PublicSource.

Nombre	Campo y Tipo	Descripción
ID del Ítem	`item_id` (string)	Referencia única del documento dentro del sistema
Tipo de Ítem	`item_type` (string)	Categoría interna del documento (e.g., `"ac_mx"`)
URL del Documento	`document_url` (string)	Enlace al documento fuente original
Nombre de la Entidad	`entity_name` (string)	Nombre de la entidad o institución que emitió el documento
Fuente de Información	`information_source` (string)	Indica el origen de los datos (e.g., registro público, notaría)
Fecha de Origen	`source_date` (string)	Fecha en la que se originó la información en la fuente
Campos Adicionales	`extra_fields` (object)	Metadatos específicos del documento, como `acta_city`, `acta_number`, `acta_state`, `folio_number`, `folio_date`, `notary_name`, `notary_number` y `type`

Motivo cuando la lista de accionistas viene vacía

Una lista de accionistas vacía no siempre significa lo mismo. Hay tipos de sociedad que no tienen accionistas —tienen socios, asociados o cooperativistas— y hay verificaciones donde el acta todavía no se extrajo. Estos dos campos, al nivel de data, te dicen cuál de los dos casos estás viendo.

Nombre	Campo y Tipo	Descripción
Motivo	`shareholders_unavailable_reason` (string \| null)	Por qué `shareholders` viene vacío. Valores: `business_type_without_shareholders`, `pending_extraction` o `null`
Tipo de sociedad	`business_type` (string \| null)	Tipo de sociedad del que Trébol derivó el motivo, tal como está escrito en el documento

Valores de shareholders_unavailable_reason:

business_type_without_shareholders: el tipo de sociedad no tiene accionistas. La lista vacía es la respuesta correcta y final; no esperes que se llene más adelante. Aplica a Asociación Civil, Sociedad Cooperativa, Sociedad Civil, Sociedad de Producción Rural, instituciones de asistencia y beneficencia privada, condominios, sindicatos, asociaciones religiosas y otras formas cuyos integrantes tienen partes sociales en lugar de acciones.
pending_extraction: todavía no se sabe. Hay un acta en extracción, así que la lista vacía no dice nada. Vuelve a consultar cuando la verificación avance.
null: no hay motivo que reportar. Es lo que devuelve una verificación que sí tiene accionistas cargados, y también una cuyo tipo de sociedad tiene accionistas pero todavía no aparecen (por ejemplo, un acta cuya extracción falló).

Tres reglas que conviene tener claras:

Hay motivo solo si la lista está vacía. Una Sociedad Civil cuyo acta sí listó a sus socios devuelve shareholders_unavailable_reason: null, porque hay datos que mostrar: prevalece el dato sobre el tipo de sociedad. Los dos campos siempre están presentes: lo opcional es el valor, no su presencia. Nunca se omiten del objeto, ni siquiera cuando hay accionistas — en ese caso shareholders_unavailable_reason llega en null.
pending_extraction gana sobre business_type_without_shareholders. Mientras un acta está en vuelo puede cambiar el tipo de sociedad, así que “no tiene accionistas” no es un veredicto definitivo hasta que la extracción termina.
business_type viene con el tipo de sociedad siempre que Trébol lo pueda resolver, y en null cuando no, también cuando el motivo es null y hay accionistas. Sale del acta más reciente y, si ninguna acta lo trae, de la constancia de situación fiscal. Se resuelve igual que en la sección details, así que las dos secciones reportan el mismo tipo.

Usa shareholders_unavailable_reason para decidir qué le muestras a tu usuario. No compares business_type contra tu propia lista de tipos: el campo llega tal como está escrito en el documento y tiene cientos de grafías distintas entre actas, constancias del SAT y SIGER (mayúsculas, plurales, abreviaturas como S.C. y errores de OCR). Trébol ya normaliza todo eso para calcular el motivo.

Dos tipos que no entran en business_type_without_shareholders, aunque a veces se asuma que sí: la Sociedad de Responsabilidad Limitada, cuyos socios se reportan en la sección de accionistas como se espera, y la Sociedad en Comandita por Acciones, cuyos comanditarios sí tienen acciones (a diferencia de la Comandita Simple).

Ejemplo del objeto data de una cooperativa, donde la lista vacía es la respuesta final:

{
    "shareholders": [],
    "capital": null,
    "source": null,
    "shareholders_unavailable_reason": "business_type_without_shareholders",
    "business_type": "SOCIEDAD COOPERATIVA LIMITADA"
}

Cambio aditivo. Los dos campos se suman a la respuesta: no cambian, no renombran y no quitan nada de lo que el endpoint ya devolvía, y no alteran el contenido de shareholders, capital ni source. Si tu integración los ignora, sigue funcionando exactamente igual que antes. Están disponibles desde el 20 de agosto de 2026 en cuatro endpoints, con la misma ubicación que el resto de los campos de cada uno: dentro de data en GET /v2/verifications/{verification_id}/shareholders y GET /v2/companies/{etiqueta}/shareholders, y al nivel raíz de la respuesta en GET /verifications/{verification-id}/shareholders y GET /companies/{etiqueta}/shareholders, que no envuelven los datos en data.

Información de la verificación

Metadatos de la verificación devueltos bajo el objeto meta.verification, siguiendo el esquema V2VerificationMeta.

Nombre	Campo y Tipo	Descripción
ID de Verificación	`id` (string)	Identificador único de la verificación
Etiqueta	`tag` (string)	Identificador secundario para clasificar y seguir verificaciones específicas
Estado	`status` (string)	Estado de la verificación (e.g., `"finished"`)

Workflow de Verificación

Para facilitar la comprensión del proceso de verificación de accionistas, a continuación se detalla el flujo de trabajo:

Subir Actas y Documentos

El usuario carga las actas constitutivas, actas de asamblea, comprobantes de domicilio y otros documentos necesarios para el proceso de onboarding de empresas. Este paso implica la recopilación de toda la documentación requerida para iniciar el proceso de verificación, asegurando que se disponen de todos los documentos legales y fiscales necesarios para la evaluación.

Trebol Identifica Accionistas Más Recientes

Utilizando tecnologías de OCR de actas constitutivas, Trebol extrae y actualiza la información de los accionistas más recientes de la empresa. Esto automatiza la extracción de datos clave, mejorando la eficiencia del proceso y garantizando que la información de propiedad está actualizada y es precisa para una evaluación adecuada.

Recibir Notificación Webhook

Una vez completada la identificación y verificación, Trebol envía una notificación a través de un webhook configurado por el usuario. Esto permite la integración con otros sistemas y la automatización de flujos de trabajo posteriores, notificando la finalización del proceso de verificación y permitiendo iniciar la revisión de la información.

Leer Información de Accionistas

El usuario o tu sistema accede a los datos detallados de los accionistas mediante una solicitud al endpoint, obteniendo información actualizada y verificada. Esto facilita la visualización y utilización de los datos para decisiones de negocio y cumplimiento, proporcionando acceso a información detallada para realizar evaluaciones de riesgo y cumplimiento normativo.

Endpoint

GET https://api.gotrebol.com/v2/verifications/{verification_id}/shareholders

Descripción

Obtiene la lista de accionistas de una empresa verificada, incluyendo detalles como porcentaje de acciones, tipo de accionista, información fiscal y de identidad. Este proceso es esencial para el onboarding de persona moral y cumple con las disposiciones CNBV.

Parámetros de Ruta

Parámetro	Tipo	Descripción
verification_id	string	Identificador único de la verificación (UUID).

Query parameters

boolean

Si es true, el response incluye data.citations.url con la URL firmada al artifact de coordenadas. Ver Coordenadas de citas.

Campo `data.citations`

Cuando se pasa ?with_citations=true, el response incluye el objeto citations dentro de data:

{
  "data": {
    "shareholders": [...],
    "capital": {...},
    "source": {...},
    "citations": {
      "url": "https://files.gotrebol.com/{verification_id}/citations/shareholders.json?..."
    }
  }
}

La URL firmada caduca 1 hora después de generarla. Descarga el JSON y persiste su contenido en tu lado si necesitas acceso posterior. Si la URL caduca, vuelve a llamar al endpoint con el flag para obtener una nueva.

Trébol genera el artifact con el evento verification.v2.finished. Los requests anteriores a ese evento no traen la URL de citations.

Respuesta

Devuelve un objeto JSON con la información de los accionistas y el capital social de la empresa verificada.

Ejemplo de Respuesta

{
    "success": true,
    "data": {
        "shareholders": [
            {
                "id": 102345,
                "currency": "MXN",
                "fixed_shares": "60",
                "fixed_value": "60000",
                "id_number": "ELON900101XYZ",
                "id_type": "RFC",
                "name": "ELON MUSK",
                "nationality": "Estadounidense",
                "total_shares": "60",
                "total_value": "60000",
                "type": "Persona",
                "variable_shares": "0",
                "variable_value": "0",
                "share_percentage": 60,
                "aml_validation_status": "no_aml_items",
                "aml_risk_category": [],
                "aml_data": [],
                "identity": {
                    "person_id": {
                        "description": "ine_mx - MUSE900101XYZ123",
                        "address": "CALLE TESLA 100 COL. SILICON VALLEY, CIUDAD DE MÉXICO, CDMX.",
                        "document_date": "2029-10-31",
                        "extra_fields": {
                            "curp": "MUSE900101HDFXLN02"
                        },
                        "validations": [
                            {
                                "source": "ine",
                                "validated_at": "2024-01-10T09:15:00Z",
                                "validation_result": "valid_id"
                            }
                        ],
                        "source": {
                            "item_id": 95001,
                            "document_url": "https://files.ejemplo.com/verification/95001_original_file.pdf",
                            "item_type": "person_id",
                            "document_date": "2029-10-31",
                            "document_number": "MUSE900101XYZ123",
                            "entity_name": "ELON MUSK",
                            "extra_fields": {
                                "idType": "ine_mx"
                            }
                        }
                    },
                    "address_data": {
                        "description": "person - ELON MUSK",
                        "address": "CALLE TESLA 100 COL. SILICON VALLEY CP 01001 CIUDAD DE MÉXICO, CDMX",
                        "document_date": "2024-02-15T00:00:00Z"
                    }
                },
                "fiscal": {
                    "tax_id": "MUSE900101XYZ",
                    "tax_regime": "Persona Física con Actividad Empresarial",
                    "tax_status": "Activo",
                    "validations": [
                        {
                            "source": "sat",
                            "validated_at": "2024-01-10T09:15:00Z",
                            "validation_result": "valid_tax_id"
                        }
                    ]
                },
                "address": {
                    "street": "CALLE TESLA",
                    "exterior_number": "100",
                    "neighborhood": "SILICON VALLEY",
                    "municipality": "CIUDAD DE MÉXICO",
                    "state": "CDMX",
                    "zip_code": "01001",
                    "country": "México"
                }
            },
            {
                "id": 102346,
                "currency": "MXN",
                "fixed_shares": "40",
                "fixed_value": "40000",
                "id_number": "SLHC400128ABC",
                "id_type": "RFC",
                "name": "CARLOS SLIM HELÚ",
                "nationality": "Mexicana",
                "total_shares": "40",
                "total_value": "40000",
                "type": "Persona",
                "variable_shares": "0",
                "variable_value": "0",
                "share_percentage": 40,
                "aml_validation_status": "no_aml_items",
                "aml_risk_category": [],
                "aml_data": [],
                "identity": {
                    "person_id": {
                        "description": "ine_mx - SLHC400128ABC",
                        "address": "AV. REFORMA 1234 COL. LOMAS DE CHAPULTEPEC, CIUDAD DE MÉXICO, CDMX.",
                        "document_date": "2030-12-31",
                        "extra_fields": {
                            "curp": "SLHC400128HDFXLN01",
                            "rfc": "SLHC400128ABC"
                        },
                        "validations": [
                            {
                                "source": "ine",
                                "validated_at": "2024-01-15T10:30:00Z",
                                "validation_result": "valid_id"
                            }
                        ],
                        "source": {
                            "item_id": 95000,
                            "document_url": "https://files.ejemplo.com/verification/95000_original_file.pdf",
                            "item_type": "person_id",
                            "document_date": "2030-12-31",
                            "document_number": "SLHC400128ABC",
                            "entity_name": "CARLOS SLIM HELÚ",
                            "extra_fields": {
                                "idType": "ine_mx"
                            }
                        }
                    },
                    "address_data": {
                        "description": "person - CARLOS SLIM HELÚ",
                        "address": "AV. REFORMA 1234 COL. LOMAS DE CHAPULTEPEC CP 11000 CIUDAD DE MÉXICO, CDMX",
                        "document_date": "2024-02-20T00:00:00Z",
                        "source": {
                            "item_id": 95001,
                            "document_url": "https://files.ejemplo.com/verification/95001_original_file.pdf",
                            "item_type": "proof_address",
                            "document_date": "2024-02-20",
                            "entity_name": "CARLOS SLIM HELÚ"
                        },
                        "service_type": null
                    }
                },
                "fiscal": {
                    "csf_mx": {
                        "status": "ACTIVO",
                        "rfc": "SLHC400128ABC",
                        "curp": "SLHC400128HDFXLN01",
                        "domicilioFiscal": "AV. REFORMA 1234 COL. LOMAS DE CHAPULTEPEC, CIUDAD DE MÉXICO, CDMX 11000",
                        "mainActivity": [
                            {
                                "date": "2021-05-10",
                                "order": 1,
                                "percentage": 80,
                                "economicActivity": "Telecomunicaciones"
                            },
                            {
                                "date": "2021-05-10",
                                "order": 2,
                                "percentage": 20,
                                "economicActivity": "Inversionista"
                            }
                        ],
                        "sourceLines": [
                            "Constancia de Situación Fiscal (validación QR)",
                            "10-05-2024"
                        ],
                        "addressInfo": {
                            "streetType": "AVENIDA",
                            "streetName": "REFORMA",
                            "externalNumber": "1234",
                            "internalNumber": "",
                            "neighborhood": "LOMAS DE CHAPULTEPEC",
                            "city": "CIUDAD DE MÉXICO",
                            "district": "MIGUEL HIDALGO",
                            "state": "CIUDAD DE MÉXICO",
                            "postCode": "11000"
                        },
                        "source": {
                            "item_id": 95002,
                            "document_url": "https://files.ejemplo.com/verification/95002_original_file.pdf",
                            "item_type": "csf_mx",
                            "entity_name": "CLEVELAND TECH SOLUTIONS",
                            "document_date": "2021-05-10",
                            "extra_fields": {
                                "taxIdNumber": "SLHC400128ABC",
                                "qrValidation": true,
                                "qrValidatedAt": "2024-05-10T15:45:00Z"
                            }
                        }
                    }
                },
                "address": {
                    "proof_address": {
                        "description": "person - CARLOS SLIM HELÚ",
                        "address": "AV. REFORMA 1234 COL. LOMAS DE CHAPULTEPEC CP 11000 CIUDAD DE MÉXICO, CDMX",
                        "document_date": "2024-02-20T00:00:00Z",
                        "source": {
                            "item_id": 95001,
                            "item_type": "proof_address",
                            "document_date": "2024-02-20",
                            "entity_name": "CARLOS SLIM HELÚ"
                        },
                        "type": "person",
                        "provider": null,
                        "service_type": null
                    }
                }
            }
        ],
        "capital": {
            "fixed_value": "100000",
            "fixed_shares": "100",
            "fixed_value_currency": "MXN",
            "variable_value": "0",
            "variable_shares": "0",
            "total_value": "100000",
            "total_shares": "100",
            "total_value_currency": "MXN"
        },
        "source": {
            "item_id": 95003,
            "item_type": "ac_mx",
            "document_url": "https://files.ejemplo.com/verification/95003_original_file.pdf",
            "document_date": "2020-06-01",
            "document_number": "56789",
            "entity_name": "CLEVELAND TECH SOLUTIONS",
            "extra_fields": {
                "folio_number": "98765",
                "folio_date": "2020-06-15",
                "notary_name": "MARÍA GONZÁLEZ PÉREZ",
                "notary_number": "45",
                "notary_state": "CIUDAD DE MÉXICO",
                "notary_city": "CIUDAD DE MÉXICO",
                "folio_data_source": {
                    "folio_number_source": "registro_publico",
                    "folio_date_source": "ac_mx"
                }
            },
            "information_source": "acta_constitutiva",
            "source_date": "2020-06-01"
        },
        "shareholders_unavailable_reason": null,
        "business_type": "SOCIEDAD ANONIMA DE CAPITAL VARIABLE"
    },
    "meta": {
        "section": "shareholders",
        "verification": {
            "id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
            "tag": "kyb-demo-02",
            "status": "finished"
        }
    }
}

Intro al API de Trébol

Guías por caso de uso

Extraer Accionistas de Actas

API KYB: Verificación de Accionistas

Campos de Respuesta

Accionistas mas recientes

Fuente de donde se obtuvo la lista de accionistas

Motivo cuando la lista de accionistas viene vacía

Información de la verificación

Workflow de Verificación

Subir Actas y Documentos

Trebol Identifica Accionistas Más Recientes

Recibir Notificación Webhook

Leer Información de Accionistas

Endpoint

Descripción

Parámetros de Ruta

Query parameters

Campo `data.citations`

Respuesta

Ejemplo de Respuesta

​API KYB: Verificación de Accionistas

​Campos de Respuesta

​Accionistas mas recientes

​Capital social de la empresa

​Fuente de donde se obtuvo la lista de accionistas

​Motivo cuando la lista de accionistas viene vacía

​Información de la verificación

​Workflow de Verificación

​Subir Actas y Documentos

​Trebol Identifica Accionistas Más Recientes

​Recibir Notificación Webhook

​Leer Información de Accionistas

​Endpoint

​Descripción

​Parámetros de Ruta

​Query parameters

​Campo data.citations

​Respuesta

​Ejemplo de Respuesta

API KYB: Verificación de Accionistas

Campos de Respuesta

Accionistas mas recientes

Capital social de la empresa

Fuente de donde se obtuvo la lista de accionistas

Motivo cuando la lista de accionistas viene vacía

Información de la verificación

Workflow de Verificación

Subir Actas y Documentos

Trebol Identifica Accionistas Más Recientes

Recibir Notificación Webhook

Leer Información de Accionistas

Endpoint

Descripción

Parámetros de Ruta

Query parameters

Campo `data.citations`

Respuesta

Ejemplo de Respuesta