{
  "country": "mx",
  "tag": "uuid-company-1234",
  "tax_id": "ABC123456789",
  "flow_id": "flow_default",
  "options": {
    "advanced_siger": true
  },
  "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"]
    }
  ]
}

{
  "verification_id": "ver_abC123DeF456",
  "status": "pending",
  "created_at": "2024-08-01T12:00:00Z"
}
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",
  "options": {
    "advanced_siger": true
  },
  "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"
      }
    }
  ],
  "options": {
    "advanced_siger": true
  }
}'

​
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"]
    }
  ]
}