Overview — KYB México

Esta guía explica cómo crear verificaciones KYB para empresas mexicanas usando Trébol. Incluye los items aplicables, cómo manejar apoderados y administradores, variaciones de creación con ejemplos de payload copy-pasteables, y consideraciones específicas del caso de uso. Para entender el método de creación a usar (Aplicativo Web, widget, API sin flujo, API con flujo), consulta Cómo funciona Trébol. Esta guía asume creación vía API.

¿Qué puedes verificar?

KYB México permite verificar:

Personas morales: empresas mexicanas (S.A. de C.V., S. de R.L., S.A.P.I., etc.)
Personas físicas con actividad empresarial
Representantes legales y apoderados de una empresa

Trébol automatiza la extracción de información de actas constitutivas, poderes notariales, constancias de situación fiscal y consultas a fuentes oficiales (SIGER, SAT).

Items aplicables

Documentos

Items que representan archivos que se cargan a Trébol (el cliente los proporciona o los sube el usuario final vía widget).

Ítem	Descripción
`ac_mx`	Acta constitutiva
`aa_mx`	Acta de asamblea
`pw_mx`	Poder notarial
`fme_mx`	Folio mercantil electrónico
`csf_mx`	Constancia de situación fiscal
`designacion_responsable_cumplimiento_extractor`	Designación de responsable de cumplimiento
`issste_unified_record`	Expediente electrónico único del ISSSTE
`tax_payment_compliance`	Opinión de cumplimiento

Ver detalle completo y estructura de respuesta en Items de documentos — KYB México.

Consultas públicas

Items que Trébol consulta automáticamente ante fuentes oficiales (no requieren archivo cargado).

Ítem	Descripción
`siger`	Consulta del Sistema Integral de Gestión Registral
`siger_shareholders`	Búsqueda de empresas relacionadas por accionistas
`public_sat_signatures`	Firmas electrónicas (FIEL) y sellos digitales registrados en el SAT
`curp_item`	Consulta y validación de CURP

Ver detalle completo, opciones de creación y estructura de respuesta en Items de consultas públicas — KYB México.

Items globales aplicables

Además de los MX-específicos, puedes usar items globales en verificaciones KYB MX:

person_id (INE, pasaporte, residencia MX)
proof_address (comprobante de domicilio)
bank_statement (estado de cuenta)
generic (para clasificación automática)

Ver detalle en Respuestas por tipo de ítem.

Key people y scope (apoderados y poderes)

Para extraer información de apoderados, administradores o personas con poderes legales de la empresa, usa el atributo key_people en el payload de creación.

Estructura de `key_people`

Arreglo de personas con names y scope. Puedes agregar personas por nombre completo o por documento de identificación.

Atributo	Tipo	Descripción
`names`	`string`	Nombre completo de la persona
`scope`	`string[]`	Alcance de la extracción para esta persona

Valores de `scope`

Scope	Descripción
`powers`	Extraer facultades legales del firmante (poder notarial)
`doc_validation`	Limitar el alcance de la verificación de la persona a la validación de documentos

Ejemplo de uso

"key_people": [
  {
    "names": "Juan Pérez",
    "scope": ["powers"]
  }
]

Para entender en detalle las diferencias entre key_people, full_list, executives, board_members, auditors y proxies en la respuesta del endpoint de people, consulta Firmantes y apoderados.

Variaciones de creación

Cada variación incluye un ejemplo de payload completo copy-pasteable. Se asume endpoint POST /verifications y autenticación con API Key (ver Crear una verificación para detalles del endpoint genérico).

1. Consulta simple (solo RFC → SIGER + SAT)

Verificación sin documentos. Solo con el RFC se consulta el SIGER, la FIEL de la empresa, la FIEL del representante legal y la razón social.

{
  "country": "mx",
  "tag": "uuid-cliente-1234",
  "tax_id": "CMT2404303V2",
  "items": [
    {
      "type": "siger"
    },
    {
      "type": "public_sat_signatures",
      "options": {
        "type": "business",
        "tax_id_number": "CMT2404303V2"
      }
    },
    {
      "type": "public_sat_signatures",
      "options": {
        "type": "representatives"
      }
    }
  ]
}

2. Con documentos: clasificación automática + extracción

Verificación que incluye documentos para que Trébol clasifique automáticamente y extraiga la información. Usa items de tipo generic. El campo client_item_type es opcional: si lo defines, ayudas al clasificador con un hint del tipo esperado; si lo omites, Trébol detecta el tipo por sí solo. Para extraer poderes de apoderados o limitar el alcance de validación de personas, agrega key_people a nivel de la verificación.

{
  "country": "mx",
  "tag": "uuid-cliente-5678",
  "friendly_name": "ACME S.A de C.V",
  "items": [
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/acta-constitutiva.pdf",
        "client_item_type": "ac_mx"
      }
    },
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/ine-rep-legal.pdf",
        "client_item_type": "person_id"
      }
    }
  ],
  "metadata": {
    "custom_key": "custom_value"
  },
  "key_people": [
    {
      "names": "Juan Pérez",
      "scope": ["powers"]
    }
  ]
}

3. Con tipo conocido: solo validación o solo extracción

Cuando ya sabes qué tipo de documento te entregan, puedes saltarte la clasificación. Hay dos sub-casos: 3.a — Solo validación (item doc_validation): Trébol verifica que el archivo coincida con el tipo declarado y cumpla las reglas que configures. No extrae información. El campo client_item_type es obligatorio porque define contra qué tipo se compara.

{
  "country": "mx",
  "tag": "uuid-cliente-validacion",
  "items": [
    {
      "type": "doc_validation",
      "options": {
        "file_url": "https://www.ejemplo.com/acta-constitutiva.pdf",
        "client_item_type": "ac_mx",
        "ruleset": [
          {
            "id": "vr_trebol_entidad",
            "error_message": "El acta debe mencionar a ACME S.A. de C.V.",
            "params": {
              "entity_name": "ACME S.A. de C.V."
            }
          }
        ]
      }
    }
  ]
}

ruleset es opcional. Para el catálogo completo de reglas predefinidas (vr_trebol_*) y cómo armar reglas personalizadas, ver Reglas de validación. 3.b — Solo extracción (tipo directo, ej. ac_mx): Trébol extrae la información asumiendo que el documento es del tipo declarado. No valida tipo ni reglas.

{
  "country": "mx",
  "tag": "uuid-cliente-extraccion",
  "items": [
    {
      "type": "ac_mx",
      "options": {
        "file_url": "https://www.ejemplo.com/acta-constitutiva.pdf"
      }
    }
  ]
}

Si quieres validar y extraer, ver Combinar Validación + Extracción.

4. SIGER en profundidad (`siger_data_extraction` + `search_related_companies_siger`)

Caso puro de consulta SIGER profunda. Combina dos flags:

siger_data_extraction: true: analiza los actos registrados en SIGER y crea automáticamente items de tipo acta (ac_mx, aa_mx, fme_mx) solo para los actos con eventos relevantes.
search_related_companies_siger: true: identifica empresas en las que participan los accionistas de la empresa consultada. Al completar el item SIGER, se crea automáticamente un item siger_shareholders con las coincidencias.

siger_data_extraction no funciona con documentos cargadosSi agregas el item siger en una verificación que también incluye documentos cargados, el item siger NO puede llevar siger_data_extraction: true. Usa ese flag solo cuando la verificación sea puramente de consulta SIGER (sin documentos adicionales).

Para que SIGER ejecute la búsqueda necesita el legal_name de la empresa. Hay dos formas de aportárselo:

4.a — Vía `tax_id` + `public_sat_signatures` (SIGER toma el `legal_name` del SAT)

Si la verificación incluye tax_id y al menos un item public_sat_signatures con type: "business", SIGER toma automáticamente el legal_name que devuelve el SAT. No necesitas declararlo en las opciones del item siger.

{
  "country": "mx",
  "tag": "uuid-cliente-siger-via-sat",
  "tax_id": "ABC123456789",
  "items": [
    {
      "type": "siger",
      "options": {
        "siger_data_extraction": true,
        "search_related_companies_siger": true
      }
    },
    {
      "type": "public_sat_signatures",
      "options": {
        "type": "business",
        "tax_id_number": "ABC123456789"
      }
    }
  ]
}

4.b — Sin `tax_id`: `legal_name` explícito en SIGER

Si la verificación no incluye tax_id (y por lo tanto tampoco puedes incluir public_sat_signatures, que lo requiere), debes declarar el legal_name directamente en las opciones del item siger.

{
  "country": "mx",
  "tag": "uuid-cliente-siger-directo",
  "items": [
    {
      "type": "siger",
      "options": {
        "siger_data_extraction": true,
        "search_related_companies_siger": true,
        "legal_name": "EMPRESA EJEMPLO, S.A. DE C.V."
      }
    }
  ]
}

Detalle técnico de los flags y opciones adicionales (ej. state_code) en Items de consultas públicas — SIGER.

5. Combinación completa (consultas públicas + documentos con las 3 formas)

Caso de KYB realista que combina todo: consultas públicas, las 3 formas de procesar documentos, y key_people para los poderes del representante legal.

{
  "country": "mx",
  "tag": "uuid-cliente-completo",
  "tax_id": "ABC123456789",
  "friendly_name": "ACME S.A. de C.V.",
  "items": [
    {
      "type": "siger",
      "options": {
        "search_related_companies_siger": true
      }
    },
    {
      "type": "public_sat_signatures",
      "options": {
        "type": "business",
        "tax_id_number": "ABC123456789"
      }
    },
    {
      "type": "public_sat_signatures",
      "options": {
        "type": "representatives"
      }
    },
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/acta-constitutiva.pdf"
      }
    },
    {
      "type": "doc_validation",
      "options": {
        "file_url": "https://www.ejemplo.com/ine-rep-legal.pdf",
        "client_item_type": "person_id"
      }
    },
    {
      "type": "csf_mx",
      "options": {
        "file_url": "https://www.ejemplo.com/csf.pdf"
      }
    }
  ],
  "metadata": {
    "custom_key": "custom_value"
  },
  "key_people": [
    {
      "names": "Juan Pérez",
      "scope": ["powers"]
    }
  ]
}

Qué pasa en la verificación:

SIGER consulta el registro mercantil con el legal_name que aporta el SAT, y crea un item siger_shareholders con las empresas relacionadas vía accionistas.
SAT entrega las firmas (FIEL/sellos) de la empresa y de los representantes legales.
El acta constitutiva (generic) se clasifica automáticamente — Trébol detecta que es un acta — y se extrae su información.
El INE (doc_validation) se valida que sea un documento de identidad. No se extrae información.
La CSF (csf_mx) se extrae directamente, sin validar tipo ni reglas.
key_people indica a Trébol que extraiga los poderes legales de Juan Pérez de los documentos cargados.

Como la verificación incluye documentos cargados, el item siger no puede llevar siger_data_extraction: true (ver Warning en variación 4). Si necesitas la extracción profunda de SIGER, ejecuta una verificación separada solo de consulta SIGER.

Ejemplo de flujo completo

Ejemplo de un flujo completo para onboarding de empresas mexicanas. Incluye requerimientos obligatorios con reglas de validación, un requerimiento opcional con conditional_render, consultas a fuentes externas (SAT), captura de beneficiarios finales con mx_form y un formulario para capturar datos adicionales de la empresa.

El schema_id del item forms se obtiene primero creando el esquema con el endpoint de esquemas de formularios. Ver detalle en Items del flujo — forms.

{
  "friendly_name": "Onboarding Empresa MX - Estándar",
  "id_slug": "onboarding-mx-estandar",
  "country": "mx",
  "record_validation_schema": {
    "version": 2,
    "requirements": {
      "doc_1": {
        "allowed_item_types": ["csf_mx"],
        "ui_options": {
          "label": "Constancia de Situación Fiscal",
          "description": "CSF con menos de 60 días de antigüedad"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate",
          "ruleset": [
            {
              "id": "vr_trebol_antiguedad",
              "params": { "days": 60 },
              "error_message": "La CSF debe tener menos de 60 días de antigüedad"
            }
          ]
        }
      },
      "doc_2": {
        "allowed_item_types": ["ac_mx"],
        "ui_options": {
          "label": "Acta Constitutiva",
          "description": "Documento que certifica la constitución de la empresa."
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      }
    },
    "optional_requirements": {
      "doc_3": {
        "ui_options": {
          "label": "Poder Notarial",
          "description": "Documento que certifica el poder notarial del representante legal de la empresa.",
          "conditional_render": true,
          "conditional_render_label": "¿Los poderes del representante legal figuran en un acta de asamblea o poder notarial?"
        },
        "allowed_item_types": ["pw_mx", "aa_mx", "ac_mx"],
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      }
    }
  },
  "flow_items": {
    "items": [
      {
        "type": "public_sat_signatures",
        "options": { "type": "business" }
      },
      {
        "type": "public_sat_signatures",
        "options": { "type": "representatives" }
      },
      {
        "type": "ubos",
        "options": {
          "ubos_form_schema": "mx_form",
          "ubos_threshold": 25,
          "is_optional": false
        }
      },
      {
        "type": "forms",
        "options": {
          "schema_id": "form-datos-empresa-mx",
          "is_optional": false
        }
      }
    ],
    "options": {
      "creator_email": "compliance@tuempresa.com"
    }
  }
}

Ver Crear el flujo para detalle de cada sección del flujo.

Siguientes pasos

Items de documentos

Detalle de estructura de respuesta para ac_mx, csf_mx, pw_mx, etc.

Items de consultas públicas

Detalle de SIGER, SAT, CURP con opciones y flags.

Accionistas

Cómo extraer información de accionistas.

Firmantes y apoderados

Cómo extraer roles, poderes y key_people.

Cómo funciona Trébol

Comparación de Aplicativo Web, widget, API sin/con flujo.

Estados de verificación

Ciclo de vida de una verificación.

Intro al API de Trébol

Guías por caso de uso

Overview — KYB México

¿Qué puedes verificar?

Items aplicables

Documentos

Consultas públicas

Items globales aplicables

Key people y scope (apoderados y poderes)

Estructura de `key_people`

Valores de `scope`

Ejemplo de uso

Variaciones de creación

1. Consulta simple (solo RFC → SIGER + SAT)

2. Con documentos: clasificación automática + extracción

3. Con tipo conocido: solo validación o solo extracción

4. SIGER en profundidad (`siger_data_extraction` + `search_related_companies_siger`)

4.a — Vía `tax_id` + `public_sat_signatures` (SIGER toma el `legal_name` del SAT)

4.b — Sin `tax_id`: `legal_name` explícito en SIGER

5. Combinación completa (consultas públicas + documentos con las 3 formas)

Ejemplo de flujo completo

Siguientes pasos

Items de documentos

Items de consultas públicas

Accionistas

Firmantes y apoderados

Cómo funciona Trébol

Estados de verificación

Intro al API de Trébol

Guías por caso de uso

Documentation Index

​¿Qué puedes verificar?

​Items aplicables

​Documentos

​Consultas públicas

​Items globales aplicables

​Key people y scope (apoderados y poderes)

​Estructura de key_people

​Valores de scope

​Ejemplo de uso

​Variaciones de creación

​1. Consulta simple (solo RFC → SIGER + SAT)

​2. Con documentos: clasificación automática + extracción

​3. Con tipo conocido: solo validación o solo extracción

​4. SIGER en profundidad (siger_data_extraction + search_related_companies_siger)

​4.a — Vía tax_id + public_sat_signatures (SIGER toma el legal_name del SAT)

​4.b — Sin tax_id: legal_name explícito en SIGER

​5. Combinación completa (consultas públicas + documentos con las 3 formas)

​Ejemplo de flujo completo

​Siguientes pasos

Items de documentos

Items de consultas públicas

Accionistas

Firmantes y apoderados

Cómo funciona Trébol

Estados de verificación

¿Qué puedes verificar?

Items aplicables

Documentos

Consultas públicas

Items globales aplicables

Key people y scope (apoderados y poderes)

Estructura de `key_people`

Valores de `scope`

Ejemplo de uso

Variaciones de creación

1. Consulta simple (solo RFC → SIGER + SAT)

2. Con documentos: clasificación automática + extracción

3. Con tipo conocido: solo validación o solo extracción

4. SIGER en profundidad (`siger_data_extraction` + `search_related_companies_siger`)

4.a — Vía `tax_id` + `public_sat_signatures` (SIGER toma el `legal_name` del SAT)

4.b — Sin `tax_id`: `legal_name` explícito en SIGER

5. Combinación completa (consultas públicas + documentos con las 3 formas)

Ejemplo de flujo completo

Siguientes pasos