> ## 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.
# Extraer Apoderados de Actas y Poderes
> Guía para consultar y validar firmantes y administradores de una empresa
## API KYB: Verificación de Firmantes y Administradores
Este endpoint permite extraer información detallada de los firmantes y administradores 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 los roles clave dentro de la entidad.
Esta página documenta la respuesta de `GET /v2/verifications/{verification-id}/people` (auth con header `x-api-key`). Para el detalle del endpoint y ejemplos de request consulta [Obtener sección por ID de verificación](https://docs.gotrebol.com/api-reference/leer-información-de-la-empresa/obtener-sección-por-id-de-verificación) y la guía [Leer información](/docs/guia-devs/monitorear/leer).
## Estructura de la Respuesta
La respuesta incluye tres listas de personas:
* `key_people`: Lista de firmantes.
* `signatory_groups`: Administradores agrupados por tipo (`executives`, `board_members`, etc.). Ver [Información de `signatory_groups`](#signatory-groups).
* `full_list`: Lista completa de todas las personas detectadas.
## Información de Personas Clave
#### 1. Datos Personales
| Nombre | Campo JSON | Descripción |
| --------------------- | ------------------ | ----------------------------------------------- |
| Nombres | `names` | Nombre completo del firmante o administrador |
| Identificación | `id_number` | RFC o CURP detectado |
| RFC explícito | `id_number_rfc` | RFC cuando difiere de `id_number` |
| Tipo de ID | `id_type` | `"rfc"` o `"curp"` (o `null`) |
| Tipo de entidad | `type` | `"person"` o `"business"` |
| Género | `gender` | Género reportado |
| Nacionalidad | `nationality` | Nacionalidad (toma valor de CURP cuando existe) |
| Código de país | `iso_country_code` | ISO 3166-1 alpha-2 (p. ej. `MX`, `US`) |
| Fecha de nacimiento | `birth_date` | Fecha de nacimiento |
| Entidad de nacimiento | `birth_entity` | Entidad de nacimiento |
| ID interno | `people_id` | ID interno de la persona en Trébol |
| Sugerido por IA | `ai_suggested` | `true` si fue detectada por IA |
| Revisado por humano | `human_reviewed` | `true` si fue revisada manualmente |
#### 2. Roles y Poderes
| Nombre | Campo JSON | Descripción |
| ------ | ---------- | --------------------------------------------- |
| Roles | `roles` | Lista de roles asignados dentro de la empresa |
#### 3. Documentación Adicional
`identity`, `fiscal`, `address` y `ubo_forms` son objetos abiertos cuya estructura depende del documento extraído. Consulta [Items de documentos](/docs/guia-devs/uso-kyb/todos-paises/items-documentos) para los esquemas por tipo.
| Nombre | Campo JSON | Descripción |
| -------------------- | --------------------- | -------------------------------------------------------------------- |
| Identificación | `identity` | Datos extraídos de documentos de identidad (INE/Pasaporte) |
| Datos básicos | `basic_data` | Nombre y apellidos normalizados de la persona |
| Información Fiscal | `fiscal` | Datos extraídos del CSF u otros comprobantes fiscales |
| Domicilio | `address` | Datos extraídos de comprobantes de domicilio |
| Formularios UBO | `ubo_forms` | Datos extraídos de formularios UBO |
| Identidades externas | `external_identities` | Datos obtenidos de fuentes externas (p. ej. consulta CURP en RENAPO) |
## Detalles de Roles y Poderes
### Información del Rol
Cada persona puede tener varios roles, cada rol puede tener varios poderes asociados. La estructura de los roles y poderes es la siguiente:
| Nombre | Campo JSON | Descripción |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------- |
| ID del Rol | `id` | Identificador único del rol |
| Nombre del Rol | `role_name` | Nombre del rol (ej: presidente, secretario) |
| Grupo | `group_name` | Categoría del rol |
| Evento | `event` | Evento que originó el rol (`addition`, `mentioned`, `renewal`, `removal`) |
| Duración | `duration` | Duración en años (-1 = indefinido) |
| Poderes | `powers` | Lista de poderes otorgados |
| Fuente | `source` | Detalles del documento validador (ver tabla abajo) |
| Vencimiento de Poderes | `powers_due_date` | Fecha de vencimiento de los poderes |
| Origen del Vencimiento | `powers_due_date_source` | Origen de la fecha (`legal` o `document`) |
#### Objeto `source`
Estructura del documento validador:
| Campo JSON | Descripción |
| ----------------- | --------------------------------------------------- |
| `item_id` | ID del item documental |
| `item_type` | Tipo del documento (`ac_mx`, `person_id`, etc.) |
| `document_url` | URL firmada al PDF original |
| `document_date` | Fecha del documento |
| `document_number` | Número/folio del documento |
| `entity_name` | Nombre de la entidad |
| `extra_fields` | Datos adicionales específicos del tipo de documento |
### Poderes Legales
Este es el objeto que describe los poderes legales del representante legal:
| Nombre | Campo JSON | Descripción |
| ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------ |
| Duración | `duration` | Duración del poder (-1 = indefinido) |
| Tiene Poder | `has_power` | Indica si tiene el poder |
| Tiene Límites | `has_limits` | Indica si existen limitaciones |
| Nombre del Poder | `power_name` | Tipo de poder otorgado |
| Tipo de Firma | `signature_type` | Tipo de firma requerida: `"joint"` para firma mancomunada o `"individual"` para firma individual |
| Descripción de Límites | `limits_description` | Descripción de limitaciones |
### Tipos de Poderes
Trebol soporta los siguientes tipos de poderes:
| Nombre | Campo JSON | Descripción |
| ---------------------------- | -------------------------- | --------------------------------------------------------- |
| Títulos de Crédito | `loans` | Poder para firmar titulos de créditos empresariales |
| Poder de Dominio | `assets_management` | Poder para otorgar garantías, comproventa de activos, etc |
| Poder de Administración | `administration` | Poder para la gestión operativa general |
| Poder de Cuentas Bancarias | `bank_accounts` | Poder para abrir o cerrar cuentas bancarias |
| Poder de Delegación | `delegate` | Poder que permite delegar poderes |
| Poder de Pleitos y Cobranzas | `lawsuits_and_collections` | Poder que permite hacer la gestión de pleitos y cobranzas |
### Grupos de Roles
Ya que las empresas deciden tener distintos nombres para los roles, Trebol estandariza los distintos cargos en los siguientes grupos:
| Nombre | Campo JSON | Descripción |
| --------------- | --------------- | -------------------------------------------- |
| Consejo | `board_members` | Son los miembros del consejo |
| Administradores | `executives` | Es el administrador único o equivalentes |
| Apoderados | `proxies` | Son los apoderados de la empresa |
| Vigilancia | `auditors` | Son los comisarios o auditores de la empresa |
Información de `signatory_groups`
Cada elemento dentro de `signatory_groups[group]` (p. ej. `signatory_groups.executives[]`) aparece de forma plana: el rol y sus folios viven al mismo nivel que los datos de la persona, **no** anidados dentro de un arreglo `roles`. Comparte la mayoría de campos con `key_people`, pero tiene 7 propios:
| Nombre | Campo JSON | Tipo | Descripción |
| -------------------- | ------------------------ | -------------- | -------------------------------------------------------------------------- |
| ID del rol | `role_id` | string \| null | Identificador único del rol asignado a esta persona. |
| Nombre del rol | `role_name` | string | Nombre del rol (ej. `presidente`, `secretario`). |
| Evento | `event` | enum | Evento que originó el rol (`addition`, `mentioned`, `renewal`, `removal`). |
| Duración | `duration` | number | Duración en años del rol (`-1` = indefinido). |
| Número de folio | `folio_number` | string \| null | Folio del documento que valida el rol. |
| Fecha del folio | `folio_date` | string \| null | Fecha del folio (`YYYY-MM-DD`). |
| Fecha de inscripción | `folio_inscription_date` | string \| null | Fecha de inscripción del folio. |
Los campos `names`, `id_number`, `id_number_rfc`, `id_type`, `type`, `identity`, `fiscal`, `address`, `external_identities`, `ubo_forms`, `iso_country_code` y `source` siguen la misma semántica que en [Información de Personas Clave](#informacion-de-personas-clave).
## Información de Identidad
Cuando se sube un documento de identificación, domicilio, o comprobante fiscal, Trebol lo valida y extrae la información relevante.
### Objeto `identity.person_id`
Datos extraídos del documento de identidad:
| Nombre | Campo JSON | Descripción |
| ---------------------- | -------------------- | --------------------------------------------------------------------------- |
| Descripción | `description` | Tipo de identificación (p. ej. `ine_mx - DASJ850405HSPRVN02`) |
| Dirección | `address` | Dirección registrada en el documento |
| Fecha del Documento | `document_date` | Fecha del documento |
| Fecha de Vencimiento | `due_date` | Vencimiento del documento |
| Fecha de Emisión | `issued_date` | Emisión del documento |
| Fecha de Nacimiento | `birth_date` | Fecha de nacimiento |
| Ciudad de Nacimiento | `birth_city` | Ciudad de nacimiento |
| País de Nacimiento | `birth_country` | País de nacimiento |
| Número Nacional | `national_id_number` | Número nacional de identificación |
| Género | `gender` | Género |
| Nacionalidad | `nationality` | Nacionalidad |
| Campos Extra | `extra_fields` | Datos adicionales (CURP, RFC, etc.) |
| Validaciones | `validations` | Validaciones aplicadas al documento (ver tabla abajo) |
| Fuente | `source` | Datos del documento (ver [`source`](#objeto-source) en la sección anterior) |
| Dirección Estructurada | `mx_address` | Dirección desagregada cuando aplica para México |
#### Cada item de `validations`
| Campo JSON | Descripción |
| ------------------- | -------------------------------------- |
| `validated_at` | Timestamp de la validación |
| `validation_result` | Resultado (p. ej. `valid_id`) |
| `source` | Origen de la validación (p. ej. `ine`) |
### Objeto `basic_data`
Nombre y apellidos normalizados de la persona:
| Campo JSON | Descripción |
| ------------------ | --------------- |
| `first_name` | Nombre |
| `other_names` | Otros nombres |
| `first_last_name` | Primer apellido |
| `other_last_names` | Otros apellidos |
## Información de Domicilio
El objeto `address` contiene los datos extraídos de comprobantes de domicilio. Es un mapa libre cuya estructura depende del tipo de documento. Consulta [Items de documentos](/docs/guia-devs/uso-kyb/todos-paises/items-documentos) para los esquemas por tipo.
## Información Fiscal
El objeto `fiscal` contiene los datos extraídos del CSF u otros comprobantes fiscales (RFC, CURP, dirección fiscal, actividades económicas, etc.). Es un mapa libre cuya estructura depende del documento. Consulta [Items de documentos](/docs/guia-devs/uso-kyb/todos-paises/items-documentos) para los esquemas por tipo.
## Identidades externas
Trébol consulta RENAPO de forma automática cuando uno de los documentos de la persona (`person_id`) aporta un número CURP (típicamente extraído de un `ine_mx`, un `passport` mexicano o un `residence_mx`). Cuando la consulta termina, Trébol expone los datos en el `item_value` del `person_id` y en `external_identities.curp` dentro de cada elemento de `full_list` y `key_people`.
La consulta corre de forma asíncrona. El endpoint devuelve `external_identities` poblado solo después de que Trébol dispara el webhook [`verification_people.curp_search_completed`](/docs/guia-devs/webhooks#verification_people-curp_search_completed). Antes de ese webhook, la llave `curp` puede no existir o venir en `null`. Para detalles sobre los campos equivalentes disponibles en el `item_value` de cada `person_id`, consulta [Items de documentos — Validación de CURP (RENAPO)](/docs/guia-devs/uso-kyb/todos-paises/items-documentos#validacion-curp-renapo).
| Nombre | Campo JSON | Descripción |
| ------------------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Número de búsqueda | `search_number` | CURP utilizado para la consulta. |
| Éxito | `success` | `true` si Trébol logró completar la consulta. |
| Mensaje | `message` | Mensaje legible cuando `success` es `false`. Llega en `null` cuando todo va bien. |
| Datos del solicitante | `applicant_data` | Datos personales reportados por RENAPO. Puede llegar en `null` cuando `success` es `false`. |
| Datos del documento probatorio | `evidentiary_document_data` | Datos del acta de nacimiento o documento probatorio. Puede llegar en `null` cuando `success` es `false`. |
| Archivo CURP | `curp_file` | URL firmada al PDF descargado de RENAPO. La URL incluye `Expires=…` y caduca: cuando expire, vuelve a consultar [`GET /v2/verifications/{verification-id}/people`](https://docs.gotrebol.com/api-reference/leer-información-de-la-empresa/obtener-sección-por-id-de-verificación) para obtener una URL renovada. |
Cuando `success` es `false`, los objetos `applicant_data` y `evidentiary_document_data` pueden llegar en `null` y `message` describe la causa. Verifica siempre `success` antes de leer los campos anidados.
## Ejemplo de Respuesta
El siguiente ejemplo es una versión recortada para ilustrar la forma general. Para la respuesta completa con todos los campos y un ejemplo navegable, consulta [Obtener sección por ID de verificación](https://docs.gotrebol.com/api-reference/leer-información-de-la-empresa/obtener-sección-por-id-de-verificación) en el API Reference y selecciona el ejemplo `people`.
```json theme={"dark"}
{
"success": true,
"data": {
"key_people": [
{
"names": "DANIEL SERVITJE",
"id_number": "DASJ850405XX1",
"id_type": "rfc",
"type": "person",
"iso_country_code": "MX",
"birth_date": "1985-04-05",
"roles": [
{
"id": "role-1",
"role_name": "presidente",
"group_name": "executives",
"event": "addition",
"duration": -1,
"powers": [
{
"power_name": "administration",
"has_power": true,
"has_limits": false,
"signature_type": "joint",
"duration": -1,
"limits_description": ""
}
],
"source": {
"item_id": 94852,
"item_type": "ac_mx",
"document_date": "2015-06-15",
"entity_name": "ACME MEXICO"
}
}
],
"identity": {
"person_id": {
"description": "ine_mx - DASJ850405HSPRVN02",
"extra_fields": {
"curp": "DASJ850405HSPRVN02",
"rfc": "DASJ850405XX1"
},
"source": {
"item_id": 84856,
"item_type": "person_id"
}
}
},
"fiscal": {},
"address": {},
"ubo_forms": {},
"external_identities": {
"curp": {
"search_number": "DASJ850405HSPRVN02",
"success": true,
"message": null,
"applicant_data": {
"curp": "DASJ850405HSPRVN02",
"names": "DANIEL",
"gender": "HOMBRE",
"birth_date": "1985-04-05",
"birth_entity": "DISTRITO FEDERAL",
"nationality": "MEXICO",
"first_surname": "SERVITJE",
"second_surname": "MONTULL",
"evidentiary_document": "Acta de nacimiento"
},
"evidentiary_document_data": {
"act_number": "00452",
"registry_date": "1985",
"register_entity": "09 DISTRITO FEDERAL",
"register_municipality": "016 MIGUEL HIDALGO"
},
"curp_file": "https://files.gotrebol.com/mx/curps/DASJ850405HSPRVN02_file.pdf?Expires=…&Signature=…"
}
},
"people_id": 3025,
"ai_suggested": false,
"human_reviewed": false
}
],
"signatory_groups": {
"executives": [
{
"role_id": "role-1",
"names": "DANIEL SERVITJE",
"id_number": "DASJ850405XX1",
"id_number_rfc": "DASJ850405XX1",
"id_type": "rfc",
"role_name": "presidente",
"event": "addition",
"duration": -1,
"folio_number": "00452",
"folio_date": "2015-06-15",
"folio_inscription_date": "2015-06-20",
"iso_country_code": "MX",
"type": "person",
"source": {
"item_id": 94852,
"item_type": "ac_mx",
"document_date": "2015-06-15",
"entity_name": "ACME MEXICO"
},
"identity": {},
"fiscal": {},
"address": {},
"external_identities": {},
"ubo_forms": {}
}
]
},
"full_list": []
},
"meta": {
"section": "people",
"verification": {
"id": "09786e1d-92b7-4503-b84d-d455375be01d",
"tag": "id-trebol-demo-01",
"status": "finished"
}
}
}
```