Skip to main content
Trébol ofrece un servicio de OCR y validación para procesos de Know Your Business (KYB). Esta guía proporciona los pasos necesarios para integrar nuestro producto en tu flujo de trabajo, asegurando que los documentos se procesen de manera eficiente y precisa.

​
Preparación de Documentos

Antes de iniciar una verificación, asegúrate de preparar los documentos conforme a las siguientes especificaciones:
  1. Tipo de Documento
    • Cada documento debe enviarse con un tipo específico. Aunque el tipo genérico (generic) es suficiente, especificar el tipo del documento optimiza la validación.
      Si nos envías el document en generic, Trébol se encarga de identificar el tipo de documento
  2. URL Descargable
    • Proporciona una URL desde donde se pueda descargar el documento.
      La URL debe estar disponible por al menos 5 minutos para garantizar la descarga exitosa por parte de Trébol.
  3. Guía del Tipo de Documento (Opcional)
    • Puedes incluir una guía opcional para el tipo de documento mediante el atributo client_item_type.
    • Ejemplo de guía:
      • ac_mx: Acta constitutiva.
      • person_id: INE o pasaportes. Puedes consultar la lista completa de tipos de documentos en Tipos de Documentos

​
Preparación del Alcance (scope)

  • Define el alcance de la información que deseas extraer del documento.
  • Ejemplo: Si el documento contiene poderes legales de un firmante, utiliza el scope powers.
Los scopes disponibles son:
ScopeDescripción
powersUtilizado para capturar las facultades legales del firmante
doc_validationUtilizado para limitar el alcance de la verificación de la persona a la validación de documentos

​
Preparación de Firmantes (key_people)

  • Si necesitas buscar información de personas específicas (como poderes legales), incluye un arreglo con los nombres completos y el scope deseado. Puedes agregar estas personas por medio de su nombre completo o por medio del documento de identificación.
  • Ejemplo: 
    "key_people": [
  {
    "names": "Juan Pérez",
    "scope": ["powers"]
  }
]

​
Crear una Verificación

Para crear una verificación, envía una solicitud a la API de Trébol con la información requerida. A continuación se detallan los componentes de la solicitud y la respuesta esperada.

​
Endpoint

POST /verifications

​
Atributos de la solicitud

AtributoTipoDescripción
countrystringCódigo del país (e.g., mx).
tagstringIdentificador único para la verificación.
tax_idstringIdentificador fiscal (opcional, dependiendo del flujo).
flow_idstringIdentificador del flujo de verificación.
optionsobjectOpciones adicionales para la verificación.
metadataobjectInformación adicional personalizada.
itemsarrayArreglo de documentos a verificar.
key_peoplearrayArreglo de personas clave y sus scopes (opcional).
{
  "country": "mx",
  "tag": "uuid-company-1234",
  "tax_id": "ABC123456789",
  "flow_id": "flow_default",
  "metadata": {
    "custom_key": "custom_value"
  },
  "items": [
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/acta-constitutiva.pdf",
        "client_item_type": "ac_mx"
      }
    }
  ],
  "key_people": [
    {
      "names": "Juan Pérez",
      "scope": ["powers"]
    }
  ]
}

​
Respuesta

AtributoTipoDescripción
verification_idstringIdentificador único de la verificación, utilizado para consultar el estado y los datos extraídos.
statusstringEstado inicial de la verificación (e.g., pending).
created_attimestampTimestamp de creación de la verificación.
{
  "verification_id": "ver_abC123DeF456",
  "status": "pending",
  "created_at": "2024-08-01T12:00:00Z"
}

​
Ejemplos de Solicitudes

​
Verificación Simple (Consulta de RFC)

Este ejemplo muestra cómo crear una verificación para consultar un RFC sin documentos adicionales. Con estos items se consultará la FIEL, la FIEL del represennte legal , y la razón social en el SIGER o registro publico de la propiedad y el comercio. 
{
  "tax_id": "CMT2404303V2",
  "tag": "tu uuid de este cliente o verificación",
  "country": "mx",
  "items": [
    {
      "type": "public_sat_signatures",
      "options": {
        "type": "representatives"
      }
    },
    {
      "type": "public_sat_signatures",
      "options": {
        "type": "business",
        "tax_id_number": "CMT2404303V2"
      }
    }
  ]
}'

​
Verificación con Documentos

Este ejemplo ilustra cómo crear una verificación que incluye documentos para validación adicional. 
{
  "country": "mx",
  "tag": "uuid-company-5678",
  "items": [
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/acta-constitutiva.pdf",
        "client_item_type": "ac_mx" //opcional
      }
    },
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/ine-rep-legal.pdf",
        "client_item_type": "person_id", //opcional
        "peopleScope": ["powers"]
      }
    }
  ],
  "metadata": {
    "custom_key": "custom_value" //opcional
  },
  "key_people": [
    {
      "names": "Juan Pérez", // apoderados solicitados por medio de nombre completo y no por medio del documento
      "scope": ["powers"]
    }
  ]
}

​
Opciones Avanzadas de SIGER

Trébol ofrece opciones avanzadas para el procesamiento de información de SIGER que permiten una extracción más completa y automatizada de documentos.

​
Creación Automática de Items de Acta (siger_data_extraction)

Puedes habilitar la creación automática de items de tipo acta basados en eventos identificados en los actos de SIGER mediante el flag siger_data_extraction. Esta funcionalidad analiza cada acto mediante IA y crea items solo para aquellos que contienen eventos relevantes de la empresa. Ejemplo: 
{
  "country": "mx",
  "tag": "uuid-company-advanced",
  "tax_id": "ABC123456789",
  "items": [
    {
      "type": "siger",
      "options": {
        "siger_data_extraction": true,
        "legal_name": "EMPRESA EJEMPLO, S.A. DE C.V."
      }
    }
  ]
}
Comportamiento:
  • El sistema intenta analizar todos los actos del SIGER mediante IA (FME - Feature Minute Extractor) dentro de un límite de tiempo de 13 minutos
  • Los actos se procesan en orden cronológico inverso (más recientes primero)
  • Los resultados del análisis se almacenan en el item SIGER para los actos procesados
  • Cuando siger_data_extraction: true, se crean automáticamente items de tipo acta (ac_mx, aa_mx, fme_mx) solo para actos con eventos relevantes
  • Los items creados incluyen toda la información extraída (firmantes, accionistas, poderes, etc.)
El análisis FME intenta procesar todos los actos dentro del límite de tiempo, incluso si el flag está desactivado. El flag solo controla si se crean los items de acta automáticamente. Si hay muchos actos, algunos pueden no ser procesados, pero los más recientes siempre se priorizan.
Límite de tiempo: El proceso tiene un máximo de 13 minutos por razones de seguridad y confiabilidad. Si se alcanza este límite antes de procesar todos los actos, el sistema persiste los datos de los actos procesados hasta ese momento y finaliza exitosamente.
Para identificar empresas en las que participan los accionistas de una empresa, activa el flag search_related_companies_siger en las opciones del item SIGER o en las opciones de verificación. El sistema creará automáticamente un ítem siger_shareholders cuando el item SIGER se complete. Ejemplo con flag en opciones del item: 
{
  "country": "mx",
  "tag": "uuid-company-shareholders",
  "tax_id": "ABC123456789",
  "items": [
    {
      "type": "siger",
      "options": {
        "legal_name": "EMPRESA EJEMPLO, S.A. DE C.V.",
        "search_related_companies_siger": true
      }
    }
  ]
}
Ejemplo con flag en opciones de verificación: 
{
  "country": "mx",
  "tag": "uuid-company-shareholders",
  "tax_id": "ABC123456789",
  "items": [
    {
      "type": "siger",
      "options": {
        "legal_name": "EMPRESA EJEMPLO, S.A. DE C.V."
      }
    }
  ],
  "options": {
    "search_related_companies_siger": true
  }
}
Comportamiento:
  • Cuando el item SIGER se completa, el sistema automáticamente crea un item siger_shareholders
  • Identifica los accionistas de la empresa consultada en SIGER
  • Busca otras empresas donde estos accionistas participan
  • Retorna información de las empresas relacionadas encontradas en el nuevo item
  • Útil para análisis de beneficiarios finales (UBOs) y estructuras corporativas
Importante: El item siger_shareholders se crea automáticamente cuando el item SIGER se completa. No es necesario crearlo manualmente en el payload de la verificación. El item SIGER debe tener resultados con información de accionistas para que se active esta funcionalidad.

​
Ejemplo Completo con Opciones Avanzadas

Este ejemplo muestra cómo crear una verificación que combine:
  • Creación automática de items de acta desde SIGER
  • Búsqueda de empresas relacionadas por accionistas
  • Consulta de firmas SAT de la empresa y representantes
{
  "country": "mx",
  "tag": "uuid-company-complete",
  "tax_id": "ABC123456789",
  "items": [
    {
      "type": "siger",
      "options": {
        "siger_data_extraction": true,
        "search_related_companies_siger": true,
        "legal_name": "EMPRESA EJEMPLO, S.A. DE C.V.",
        "state_code": "9"
      }
    },
    {
      "type": "public_sat_signatures",
      "options": {
        "type": "business",
        "tax_id_number": "ABC123456789"
      }
    },
    {
      "type": "public_sat_signatures",
      "options": {
        "type": "representatives"
      }
    }
  ]
}
Resultado esperado:
  • El item SIGER se procesará y extraerá información de los documentos
  • Se crearán automáticamente items de tipo acta (ac_mx, aa_mx, fme_mx) para actos con eventos relevantes
  • Se creará automáticamente un item siger_shareholders con información de empresas relacionadas
  • Se consultarán las firmas SAT de la empresa y sus representantes legales