Items de documentos — KYB Todos los países

Este documento describe los items de tipo documento que aplican a verificaciones KYB en cualquier país. Son documentos universales que complementan los items específicos por país (México, Colombia, Estados Unidos). Para items específicos de un país, consulta las guías correspondientes:

Tabla resumen

Ítem	Descripción
`person_id`	Identificación oficial de persona física/natural.
`proof_address`	Comprobante de domicilio.
`bank_statement`	Estado de cuenta bancario.
`trust_contract_fideicomiso_extractor`	Contrato de fideicomiso. (Beta)
`union_documents_extractor`	Documentos de unión (pareja de hecho). (Beta)
`financial_statements_any`	Estados financieros de empresas. (Beta)

`person_id` — Identificación oficial (persona)

Tipos de identificación soportados según el país:

ine_mx: Identificación oficial mexicana (INE).
passport: Pasaporte (documento oficial de viaje).
residence_mx: Tarjeta/documento de residencia en México (para no mexicanos).
cc: Cédula de ciudadanía colombiana.

Estructura de respuesta

{
  "item_type": "person_id",
  "item_value": {
    "names": "María Guadalupe",
    "id_number": "1234567890123456",
    "id_type": "ine_mx|passport|residence_mx|cc",
    "issued_date": "2020-01-01",
    "birth_city": "Guadalajara, Jalisco",
    "nationality": "mexicana", 
    "birth_country": "México",
    "place_of_issue": "Ciudad de México"|null,
    "due_date": "2030-01-01"|null,
    "sex": "female"|"male"|null,
    "home_address": "Av. Insurgentes Sur 1234, Col. Del Valle, CDMX"| null,
    "numero_id_nacional": "LOFM900115MDFXRN08"|null,
    "curp": "LOFM900115MDFXRN08"|null,
    "ine_validation_data": {
      "data": {
        "cic": "1234567890123456789",
        "numero_ocr": "123456789012345678",
        "ano_de_emision": "2020",
        "distrito_local": "Distrito 15",
        "ano_de_registro": "2020",
        "expiration_date": "2030-01-01",
        "clave_de_elector": "MARG80010115HDFXXX01",
        "distrito_federal": "Distrito Federal 15",
        "numero_de_emision": "123456",
        "fecha_de_actualizacion_de_la_informacion": "2020-01-01"
      }
    }|null,
    "ine_validation_result": "valid_id|invalid_id|failed|error|missing_parameters|maximum_retries_reached|missing_validation_parameters"|null,
    "ine_validation_message": "ID successfully validated.|A problem occured trying to validate the INE information|null",
    "curp_validation_data": {
      "curp": "LOFM900115MDFXRN08",
      "curp_status": "alta_normal"|"baja_por_defuncion"|"otro"|"no_encontrado",
      "names": "María Guadalupe",
      "gender": "MUJER",
      "act_number": "00452",
      "birth_date": "1990-01-15",
      "birth_entity": "JALISCO",
      "nationality": "MEXICO",
      "first_surname": "López",
      "second_surname": "Fernández",
      "register_entity": "14 JALISCO",
      "evidentiary_document": "Acta de nacimiento",
      "register_municipality": "039 GUADALAJARA"
    }|null,
    "curp_validation_result": "curp_found"|"curp_not_found"|null,
    "curp_validation_message": null,
    "curp_file": "https://files.gotrebol.com/mx/curps/LOFM900115MDFXRN08_file.pdf"|null
  }
}

Los keys due_date, place_of_issue, sex, numero_id_nacional y curp pueden ser null porque son campos opcionales y su presencia depende del tipo de person_id y de si el documento los incluye explícitamente (por ejemplo, curp solo aplica para documentos mexicanos; place_of_issue aplica para la cédula de ciudadanía colombiana).

Validación del INE

Para un item de tipo person_id, si su tipo es ine_mx, se realiza una validación del INE. Los datos de esta validación se encuentran dentro de item_value bajo la clave ine_validation_data. El estado de este proceso se puede identificar mediante dos claves: ine_validation_result y ine_validation_message. Estructura de ine_validation_data: El objeto ine_validation_data.data contiene la siguiente información extraída del INE:

cic (string): Clave de Identificación Ciudadana (CIC).
numero_ocr (string): Número OCR del documento.
ano_de_emision (string): Año de emisión del documento.
distrito_local (string): Distrito local electoral.
ano_de_registro (string): Año de registro del documento.
expiration_date (string): Fecha de expiración del documento.
clave_de_elector (string): Clave de elector.
distrito_federal (string): Distrito federal electoral.
numero_de_emision (string): Número de emisión del documento.
fecha_de_actualizacion_de_la_informacion (string): Fecha de actualización de la información.

La validación del INE solo se realiza cuando el id_type del item person_id es ine_mx. Para otros tipos de identificación (como passport, residence_mx o cc), estos campos vendrán en null.

Para saber cómo detectar si la validación del INE falló (e.g. ine_validation_result: "failed" o "error"), consulta la referencia de errores en consultas públicas.

Validación de CURP (RENAPO)

Cuando el item_value del person_id incluye la llave curp con un valor no nulo (típicamente al procesar un ine_mx, un passport mexicano o un residence_mx), Trébol consulta automáticamente RENAPO. La consulta corre de forma asíncrona: el item_value inicial puede devolverse con los cuatro campos (curp_validation_data, curp_validation_result, curp_validation_message y curp_file) en null y Trébol los puebla cuando dispara el webhook verification_people.curp_search_completed. Para acceder a los datos, vuelve a consultar GET /verifications/{verification-id} tras recibir el webhook. La respuesta usa el mismo conjunto de datos que el ítem dedicado curp_item, con tres diferencias en el item_value del person_id: (1) no incluye curp_validated_at, (2) no incluye curp_validation_status, y (3) curp_file queda al mismo nivel que curp_validation_data dentro de item_value (en curp_item está anidado dentro de curp_validation_data). Estructura de curp_validation_data:

Nombre	Campo JSON	Tipo	Descripción
CURP normalizado	`curp`	string	CURP devuelto por RENAPO (puede diferir del `curp` original si RENAPO devuelve uno normalizado).
Estado del CURP	`curp_status`	string	Estado en el registro. Valores: `alta_normal`, `baja_por_defuncion`, `otro`, `no_encontrado`.
Nombres	`names`	string	Nombres de pila reportados por RENAPO.
Género	`gender`	string	Género reportado por RENAPO (`HOMBRE` o `MUJER`).
Número de acta	`act_number`	string	Número del acta de nacimiento.
Fecha de nacimiento	`birth_date`	string	Formato `YYYY-MM-DD`.
Entidad de nacimiento	`birth_entity`	string	Entidad federativa de nacimiento.
Nacionalidad	`nationality`	string	Nacionalidad reportada.
Primer apellido	`first_surname`	string	Primer apellido.
Segundo apellido	`second_surname`	string	Segundo apellido.
Entidad de registro	`register_entity`	string	Entidad federativa donde se registró el acta.
Municipio de registro	`register_municipality`	string	Municipio donde se registró el acta.
Documento probatorio	`evidentiary_document`	string	Documento probatorio (típicamente `"Acta de nacimiento"`).

curp_validation_result — resultado de la consulta:

curp_found: Trébol encontró el CURP en RENAPO. La consulta fue exitosa.
curp_not_found: Trébol no encontró el CURP en RENAPO. La consulta corrió sin error, pero el CURP no existe.

curp_validation_message — campo reservado para un mensaje legible asociado al resultado. Actualmente llega siempre en null para el item_value del person_id (a diferencia de curp_item, donde sí se puebla). Existe por consistencia con la convención de ine_validation_message y puede llevar texto descriptivo en el futuro. Para conocer el resultado de la consulta, lee curp_validation_result. curp_file — URL firmada al PDF descargado de RENAPO con la constancia del CURP. Vive como campo de primer nivel dentro de item_value (no anidado dentro de curp_validation_data). La URL incluye un parámetro Expires=… y caduca; cuando expire, vuelve a consultar GET /verifications/{verification-id} para obtener una URL renovada.

Trébol solo dispara la consulta de RENAPO cuando el person_id incluye un número CURP. Si el id_type no aporta un CURP (por ejemplo, una cédula colombiana o un pasaporte no mexicano), los cuatro campos llegan en null y nunca llega el webhook curp_search_completed.

Si la consulta no corre (por ejemplo, porque no hay CURP en el documento) o si curp_validation_result es curp_not_found, el objeto curp_validation_data y la URL curp_file pueden llegar en null. Verifica siempre que el objeto y la URL existan antes de leerlos.

curp_validation_result: "curp_not_found" indica que la consulta corrió bien y RENAPO no tiene ese CURP — no es un error. Los errores reales (timeouts, indisponibilidad del servicio) llegan en el campo people_error del webhook verification_people.curp_search_completed; consulta la referencia de errores en consultas públicas para ver cómo procesarlos.

Ejemplo de salida para cédula de ciudadanía colombiana

{
  "item_type": "person_id",
  "item_value": {
    "names": "Laura Fernanda Gómez Pérez",
    "id_number": "1032456789",
    "id_type": "cc",
    "issued_date": "2018-07-28",
    "birth_city": "Medellín, Antioquia",
    "nationality": "colombiana",
    "birth_country": "Colombia",
    "place_of_issue": "Bogotá D.C.",
    "sex": "female",
    "due_date": null,
    "home_address": null,
    "numero_id_nacional": null,
    "curp": null,
    "ine_validation_data": null,
    "ine_validation_result": null,
    "ine_validation_message": null,
    "curp_validation_data": null,
    "curp_validation_result": null,
    "curp_validation_message": null,
    "curp_file": null
  }
}

Ejemplo de salida para pasaporte

{
  "item_type": "person_id",
  "item_value": {
        "due_date": "2034-11-04T00:00:00Z",
        "id_number": "N71096495",
        "id_type": "passport",
        "issued_date": "2024-11-04T00:00:00Z",
        "names": "DANIEL GOMEZ HURTADO",
        "birth_city": "MIGUEL HIDALGO, DISTRITO FEDERAL",
        "nationality": "mexicana",
        "birth_country": "México",
        "place_of_issue": "",
        "sex": "male",
        "national_id_number": "GALD640615HDUPPA07",
        "curp": "GALD640615HDUPPA07",
        "home_address": null,
        "ine_validation_data": null,
        "ine_validation_result": "missing_validation_parameters",
        "ine_validation_message": null,
        "curp_validation_data": {
            "curp": "GALD640615HDUPPA07",
            "curp_status": "alta_normal",
            "names": "DANIEL",
            "gender": "HOMBRE",
            "act_number": "00153",
            "birth_date": "1964-06-15",
            "birth_entity": "DISTRITO FEDERAL",
            "nationality": "MEXICO",
            "first_surname": "GOMEZ",
            "second_surname": "HURTADO",
            "register_entity": "09 DISTRITO FEDERAL",
            "evidentiary_document": "Acta de nacimiento",
            "register_municipality": "016 MIGUEL HIDALGO"
        },
        "curp_validation_result": "curp_found",
        "curp_validation_message": null,
        "curp_file": "https://files.gotrebol.com/mx/curps/GALD640615HDUPPA07_file.pdf"
    }
}

`proof_address` — Comprobante de domicilio

{
  "item_type": "proof_address",
  "item_value": {
    "provider": "CFE",
    "address": "Av. Reforma 456, Col. Juárez, CDMX",
    "entity_name": "EMPRESA EJEMPLO, S.A. DE C.V.",
    "document_date": "2024-01-01",
    "service_type": "energia_electrica|impuesto_predial|agua|telefono|gas_natural|contrato_de_arrendamiento|internet|cable|otros",
    "type": "business|person",
    "mx_address": {
      "tipo_vialidad": "Avenida",
      "nombre_vialidad": "Reforma",
      "numero_exterior": "456",
      "numero_interior": "Piso 3",
      "tipo_asentamiento": "Colonia",
      "nombre_asentamiento": "Juárez",
      "codigo_postal": "06600",
      "localidad": "Cuauhtémoc",
      "municipio_o_ente_territorial": "Cuauhtémoc",
      "entidad_federativa": "Ciudad de México",
      "pais": "MX"
    }
  }
}

`bank_statement` — Estado de cuenta bancario

{
  "item_type": "bank_statement",
  "item_value": {
    "address": "Av. Insurgentes Sur 789, Col. Del Valle, CDMX",
    "entity_name": "EMPRESA EJEMPLO, S.A. DE C.V.",
    "document_date": "2024-01-01",
    "type": "business|person",
    "banking_information": {
      "bank_name": "Banco de México",
      "bank_country": "MX",
      "clabe_number": "012180001234567890",
      "bank_account_number": "1234567890",
      "currency": "MXN",
      "rfc": "ABC123456789"
    }
  }
}

`trust_contract_fideicomiso_extractor` — Contrato de fideicomiso

{
  "type": "trust_contract_fideicomiso_extractor",
  "payload": {
    "contract_number": "...",
    "trust_name": "...",
    "trust_type": "administracion|garantia|inversion|fuente_pago|administracion_fuente_pago|otro",
    "constitution_date": "YYYY-MM-DD",
    "signature_date": "YYYY-MM-DD",
    "duration": "...",
    "trust_purpose": "...",
    "jurisdiction": "...",
    "signature_place": "...",
    "involved_parties": [
      {
        "roles": ["fiduciario|fideicomitente|fideicomisario|fideicomisario_primer_lugar|fideicomisario_segundo_lugar|administrador_primario|administrador_maestro|garante|otro"],
        "legal_name": "...",
        "alias": "...",
        "rfc": "...",
        "entity_type": "persona_fisica|persona_moral|entidad_extranjera|institucion_financiera|gobierno|otro",
        "nationality": "...",
        "legal_representative": "...",
        "address": {
          "street_number": "...",
          "neighborhood": "...",
          "municipality": "...",
          "state": "...",
          "postal_code": "...",
          "country": "...",
          "full_address": "..."
        },
        "contact_data": {
          "phone": "...",
          "email": ["..."],
          "contact_name": "..."
        },
        "constitution_data": {
          "constitution_date": "...",
          "notary_city": "...",
          "notary_number": "...",
          "public_deed": "...",
          "commercial_folio": "..."
        }
      }
    ],
    "financial_structure": {
      "main_currency": "MXN|USD|EUR|CAD|GBP|JPY|otra",
      "initial_contribution": {
        "amount": 0,
        "currency": "MXN|USD|EUR|CAD|GBP|JPY|otra",
        "descripcion": "..."
      },
      "trust_assets": "...",
      "credit_structure": [
        { "class": "A", "amount": 0, "currency": "MXN|USD|EUR|CAD|GBP|JPY|otra", "descripcion": "..." }
      ],
      "total_potential_amount": { "amount": 0, "currency": "MXN|USD|EUR|CAD|GBP|JPY|otra" },
      "trustee_fees": [{ "amount": 0, "currency": "MXN|USD|EUR|CAD|GBP|JPY|otra" }]
    },
    "related_contracts": [
      { "nombre": "...", "annex": "...", "descripcion": "..." }
    ],
    "guarantees": ["..."],
    "risk_indicators": {
      "foreign_entities": [],
      "tax_havens": [],
      "risk_terms": [],
      "complex_structures": [],
      "conflicts_of_interest": []
    },
    "financial_flows": {
      "bank_accounts": [],
      "fund_flow": "...",
      "payment_waterfall": "..."
    },
    "validations": {
      "inconsistent_dates": [],
      "inconsistent_amounts": [],
      "missing_information": [],
      "red_flags": []
    }
  }
}

`union_documents_extractor` — Documentos de unión

{
  "type": "union_documents_extractor",
  "payload": {
    "general_summary": "...",
    "executive_summary": {
      "total_documents": 0,
      "complete_documents": 0,
      "incomplete_documents": 0
    },
    "general_information": {
      "denominacion_social": "...",
      "entity_type": "Organizacion sindical|Sindicato nacional|Sindicato empresarial|Sindicato gremial|Federacion sindical|Confederacion sindical|Otro",
      "constitution_date": "YYYY-MM-DD",
      "registration_date": "YYYY-MM-DD",
      "registration_number": "...",
      "duration": 0,
      "address": "...",
      "main_activity": "...",
      "sources": [
        {
          "source_description": "...",
          "document_id": 1,
          "page": 1,
          "paragraph": 1,
          "clause": "..."
        }
      ]
    },
    "documents": [
      {
        "document_id": 1,
        "document_name": "...",
        "document_type": "Resolución de registro|Solicitud de registro|Acta de constitución|Acta de asamblea|Estatutos sociales|Modificación de directiva|Certificación de copias|Padrón de socios|Otro",
        "summary": "...",
        "completeness_analysis": {
          "justification": "...",
          "total_pages": 0,
          "found_pages": 0,
          "status": "Completo|Incompleto"
        },
        "extracted_data": {
          "general_information": [
            {
              "field": "...",
              "value": "...",
              "source": {
                "source_description": "...",
                "document_id": 1,
                "page": 1,
                "paragraph": 1,
                "clause": "..."
              }
            }
          ],
          "relevant_appointments": [
            {
              "name": "...",
              "position": "Secretario General|Secretario de Organización|Secretario de Actas|Secretario del Interior|Secretario de Conflictos y Trabajo|Secretario Tesorero|Secretario de Prensa|Presidente|Vicepresidente|Tesorero|Vocal|Representante Legal|Apoderado|Otro",
              "identification_type": "RFC|CURP|NSS|Pasaporte|Cédula profesional|Otro",
              "identification_number": "...",
              "nationality": "...",
              "address": "...",
              "powers": "...",
              "position_validity": "...",
              "source": {}
            }
          ],
          "social_statutes": {
            "mentioned": true|false,
            "included": true|false,
            "summary": "...",
            "source": {}
          }
        }
      }
    ]
  }
}

`financial_statements_any` — Estados financieros

Item en fase Beta. La estructura de respuesta detallada se documentará próximamente.

Intro al API de Trébol

Guías por caso de uso

Items de documentos — KYB Todos los países

Tabla resumen

`person_id` — Identificación oficial (persona)

Estructura de respuesta

Validación del INE

Validación de CURP (RENAPO)

Ejemplo de salida para cédula de ciudadanía colombiana

Ejemplo de salida para pasaporte

`proof_address` — Comprobante de domicilio

`bank_statement` — Estado de cuenta bancario

`trust_contract_fideicomiso_extractor` — Contrato de fideicomiso

`union_documents_extractor` — Documentos de unión

`financial_statements_any` — Estados financieros

​Tabla resumen

​person_id — Identificación oficial (persona)

​Estructura de respuesta

​Validación del INE

​Validación de CURP (RENAPO)

​Ejemplo de salida para cédula de ciudadanía colombiana

​Ejemplo de salida para pasaporte

​proof_address — Comprobante de domicilio

​bank_statement — Estado de cuenta bancario

​trust_contract_fideicomiso_extractor — Contrato de fideicomiso

​union_documents_extractor — Documentos de unión

​financial_statements_any — Estados financieros

Tabla resumen

`person_id` — Identificación oficial (persona)

Estructura de respuesta

Validación del INE

Validación de CURP (RENAPO)

Ejemplo de salida para cédula de ciudadanía colombiana

Ejemplo de salida para pasaporte

`proof_address` — Comprobante de domicilio

`bank_statement` — Estado de cuenta bancario

`trust_contract_fideicomiso_extractor` — Contrato de fideicomiso

`union_documents_extractor` — Documentos de unión

`financial_statements_any` — Estados financieros