Skip to main content
Esta guía te muestra cómo implementar el flujo completo de validación de documentos usando el API de Trébol. Este proceso permite validar documentos de manera asíncrona y recibir notificaciones automáticas cuando la validación esté completa.

​
Resumen del Flujo

El flujo de validación de documentos consta de cinco pasos principales:
  1. Crear flujo personalizado - Configurar el flujo de validación específico para tu caso de uso
  2. Crear verificación - Inicializar la verificación usando el flujo creado
  3. Agregar documentos - Añadir los documentos a validar usando el endpoint add-items
  4. Esperar validación - El sistema procesa los documentos automáticamente
  5. Recibir resultados - Obtener los resultados completos de la validación
  6. Ejecutar extracciones - Añadir los documentos que requieren extraccion usando el endpoint add-items
Este flujo es ideal para casos donde necesitas validar documentos de manera asíncrona y recibir notificaciones cuando el proceso esté completo.

​
Resumen del Proceso

La siguiente tabla muestra cada paso del flujo de validación de documentos y quién es responsable de ejecutarlo:
PasoAcciónResponsableEndpointDescripción
0Crear flujo de validaciónUsuarioPOST /account-flowsConfigurar el flujo personalizado para validaciones (solo una vez)
1Crear verificaciónUsuarioPOST /verificationsInicializar la verificación usando el flujo creado
2Agregar documentosUsuarioPUT /verifications/{id}/add-itemsEnviar documentos para validación
3Procesar documentosTrébol-Sistema procesa y valida los documentos automáticamente
4Notificar completadoTrébolWebhookEnviar notificación cuando la validación esté lista
5Obtener resultadosUsuarioGET /verifications/{id}Consultar los resultados completos de la validación
Los pasos 0-2 y 5 son responsabilidad del usuario (tu aplicación), mientras que los pasos 3-4 son automáticos y manejados por Trébol.

​
Paso 0: Crear el Flujo de Validación

¿Ya tienes un flujo creado? Si ya creaste un flujo previamente, puedes saltarte este paso y usar directamente el id_slug del flujo existente en el Paso 1. Los flujos son reutilizables y no necesitas crear uno nuevo para cada verificación.
Antes de crear verificaciones, necesitas configurar un flujo personalizado que defina cómo se procesarán los documentos. Este flujo se puede reutilizar para múltiples verificaciones. Endpoint: POST /account-flows 
{
  "record_validation_schema": {
    "version": 2,
    "requirements": {}
  },
  "friendly_name": "lean flow",
  "flow_items": {
    "id": "mx_forms",
    "items": [],
    "options": {
      "advanced_siger": true
    }
  },
  "steps": [],
  "item_validation_schema": {
    "validationsMap": {}
  },
  "country": "mx"
}

​
Respuesta de Creación de Flujo

{
  "id_slug": "lean-flow",
  "friendly_name": "lean flow",
  "country": "mx",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z",
  "record_validation_schema": {
    "version": "2",
    "requirements": {}
  },
  "flow_items": {
    "id": "mx_forms",
    "items": [],
    "options": {
      "advanced_siger": true
    }
  },
  "steps": [],
  "item_validation_schema": {
    "validationsMap": {}
  }
}
Campos importantes de la respuesta:
  • id_slug (string): Identificador único del flujo creado. Usa este valor en el campo flow_id al crear verificaciones.
  • friendly_name (string): Nombre descriptivo del flujo tal como lo definiste.
Una vez creado el flujo, puedes usar el id_slug (en este caso lean-flow) para crear verificaciones que utilicen esta configuración.

​
Paso 1: Crear la Verificación

Ahora crea una verificación usando el flujo que acabas de crear. No incluyas documentos iniciales ya que los agregarás en el siguiente paso.
Alternativa sin flujo: Si no deseas usar un flow_id, puedes crear la verificación directamente con al menos un ítem incluido en la misma petición. Esto es útil cuando tienes un caso de uso específico y no necesitas reutilizar la configuración del flujo.
Endpoint: POST /verifications

​
Opción 1: Crear verificación con flow_id (recomendado)

{
  "email": "[email protected]",
  "tax_id": "KTM220523T3A",
  "options": {
    "skip_siger": true
  },
  "flow_id": "lean-flow",
  "tag": "test-1757976296"
}

​
Opción 2: Crear verificación con ítems incluidos

{
  "email": "[email protected]",
  "tax_id": "KTM220523T3A",
  "options": {
    "skip_siger": true
  },
  "tag": "test-1757976296",
  "items": [
    {
      "type": "doc_validation",
      "options": {
        "file_url": "https://drive.google.com/uc?export=download&id=some-id",
        "client_item_type": "csf_mx",
        "ruleset": [
          {
            "id": "vr_trebol_antiguedad",
            "params": {
              "days": 365
            }
          }
        ]
      },
      "tags": {
        "internal_id": "some-internal-id"
      }
    }
  ]
}
Parámetros requeridos:
  • email (string): Dirección de correo electrónico del cliente que solicita la validación.
  • tax_id (string): Número de identificación fiscal de la empresa (RFC en México).
  • tag (string): Etiqueta única para identificar tu verificación. Útil para tracking y debugging.
Parámetros condicionales (uno de los dos es requerido):
  • flow_id (string): Identificador del flujo de verificación predefinido. Usa lean-flow para el flujo de validación de documentos. Opcional si incluyes ítems directamente.
  • items (array): Lista de ítems para validar. Debe incluir al menos un ítem si no usas flow_id. Opcional si usas flow_id.

​
Respuesta Exitosa

{
  "id": "vf_12345abcde",
  "status": "pending",
  "account_id": "99999999-9999-9999-9999-999999999999",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z",
  "flow_id": "lean-flow",
  "documents_status": "pending_upload",
  "onboarding_url": "https://onboarding.gotrebol.com/verification/vf_12345abcde",
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "items": [],
  "tag": "test-1757976296",
  "email": "[email protected]",
  "country": "mx",
  "tax_id": "KTM220523T3A"
}
Campos importantes de la respuesta:
  • id (string): ID único de la verificación creada. Necesario para los siguientes pasos.
  • status (string): Estado actual de la verificación. Inicialmente será pending.
  • documents_status (string): Estado de la colección de documentos. Inicialmente será pending_upload.

​
Paso 2: Agregar Documentos para Validación

Una vez creada la verificación, agrega los documentos que deseas validar usando el endpoint add-items. Endpoint: PUT /verifications/{verification-id}/add-items 
[
  {
    "type": "doc_validation",
    "options": {
      "file_url": "https://drive.google.com/uc?export=download&id=some-id",
      "client_item_type": "csf_mx",
      "ruleset": [
        {
          "id": "custom_rule_1",
          "validation_rule": "El documento debe contener un sello de agua visible"
        },
        {
          "id": "vr_trebol_antiguedad",
          "params": {
            "days": 365
          }
        },
        {
          "id": "vr_trebol_entidad",
          "params": {
            "entity": "LEANDRO ALBERTO GAMARRA"
          }
        }
      ]
    },
    "tags": {
      "internal_id": "some-internal-id"
    }
  }
]
Parámetros requeridos:
  • verification-id (path): ID de la verificación obtenido en el paso anterior.
  • type (string): Tipo de item. Usa doc_validation para validación de documentos.
  • options.file_url (string): URL desde donde se puede descargar el documento. Debe estar disponible por al menos 5 minutos.
  • options.client_item_type (string): Tipo específico del documento para optimizar la validación. Ejemplo: csf_mx para constancia de situación fiscal.
Parámetros opcionales:
  • options.ruleset (array): Lista de reglas de validación que se aplicarán durante la validación del documento. Puedes usar tanto reglas predefinidas de Trébol como reglas personalizadas. Para reglas predefinidas: usa id y params (si aplica). Para reglas personalizadas: usa id y validation_rule.
  • tags (object): Diccionario de etiquetas que se asignarán al ítem. Puedes crear una etiqueta para que a futuro puedas identificar el ítem con algún identificador interno de tu sistema.

​
Reglas de Validación Predefinidas de Trébol

Trébol ofrece reglas de validación predefinidas y optimizadas que puedes usar directamente en tu ruleset sin necesidad de definir el prompt completo. Estas reglas están diseñadas para los casos de uso más comunes y ofrecen mejor rendimiento.
Ventaja de usar reglas predefinidas: Las reglas predefinidas de Trébol están optimizadas y no requieren que escribas el prompt de validación. Solo necesitas el ID de la regla y los parámetros necesarios. Importante: No incluyas el campo validation_rule cuando uses reglas predefinidas.

​
Reglas Disponibles

Valida si el documento ha vencido o no. Ideal para documentos con fecha de vencimiento como identificaciones oficiales, pasaportes, o certificados.Parámetros:
  • Ninguno
Ejemplo de uso:
{
  "id": "vr_trebol_vencimiento",
  "params": {}
}
Casos de uso:
  • Validar que una identificación oficial (INE) esté vigente
  • Verificar que un pasaporte no haya expirado
  • Confirmar la vigencia de certificados o licencias
Valida si el documento tiene menos de X días de antigüedad desde su fecha de emisión. Útil para documentos que solo tienen fecha de emisión y necesitas verificar que no sean muy antiguos.Parámetros:
  • days (number): Número máximo de días permitidos desde la emisión del documento
Ejemplo de uso:
{
  "id": "vr_trebol_antiguedad",
  "params": {
    "days": 90
  }
}
Casos de uso:
  • Validar que una Constancia de Situación Fiscal tenga menos de 60 días
  • Verificar que un comprobante de domicilio sea reciente (menos de 90 días)
  • Confirmar que un estado de cuenta bancario sea actual
Valida si un texto específico (nombre de persona, empresa, RFC, etc.) es mencionado en el documento.Parámetros:
  • entity (string): Texto que debe aparecer en el documento
Ejemplo de uso:
{
  "id": "vr_trebol_entidad",
  "params": {
    "entity": "ACME Corporation S.A. de C.V."
  }
}
Casos de uso:
  • Verificar que un documento pertenezca a una persona específica
  • Confirmar que el RFC coincida con el esperado
  • Validar que una empresa sea mencionada en el documento

​
Ejemplo Completo con Reglas Predefinidas

{
  "type": "doc_validation",
  "options": {
    "file_url": "https://drive.google.com/uc?export=download&id=some-id",
    "client_item_type": "csf_mx",
    "ruleset": [
      {
        "id": "vr_trebol_antiguedad",
        "params": {
          "days": 60
        }
      },
      {
        "id": "vr_trebol_entidad",
        "params": {
          "entity": "ACME Corporation S.A. de C.V."
        }
      },
      {
        "id": "regla_personalizada_1",
        "validation_rule": "El RFC debe coincidir con el formato correcto mexicano"
      }
    ]
  },
  "tags": {
    "internal_id": "csf-validation-001"
  }
}
Combinar reglas: Puedes combinar múltiples reglas predefinidas de Trébol en el mismo ruleset, e incluso mezclarlas con reglas personalizadas según tus necesidades.

​
Diferencia entre Reglas Predefinidas y Personalizadas

La estructura del objeto de regla varía según el tipo que uses. Es importante entender estas diferencias para evitar errores en la configuración.
Importante: No mezcles la estructura de reglas predefinidas con personalizadas. Cada tipo tiene campos específicos que debes usar correctamente.
Reglas Predefinidas de Trébol
Las reglas predefinidas usan una estructura simplificada:
  • ID: Debe comenzar con vr_trebol_
  • Campos requeridos: id y params
  • Campo prohibido: validation_rule (NO lo incluyas)
{
  "id": "vr_trebol_antiguedad",
  "params": {
    "days": 60
  }
}
Reglas Personalizadas
Las reglas personalizadas requieren que definas tu propio prompt de validación:
  • ID: Cualquier identificador personalizado
  • Campos requeridos: id y validation_rule
{
  "id": "mi_regla_personalizada",
  "validation_rule": "El documento debe contener un sello de agua visible"
}
Comparación Rápida
AspectoReglas PredefinidasReglas Personalizadas
idvr_trebol_*Cualquier texto
validation_rule❌ No incluir✅ Requerido
params✅ Requerido❌ No incluir
RendimientoOptimizadoEstándar

​
Respuesta del Add Items

[
  {
    "id": 29639,
    "item_order": 3,
    "item_status": "pending",
    "item_type": "generic",
    "item_value": {},
    "item_options": {},
    "tags": {
      "internal_id": "some-internal-id"
    }
  }
]
Campos importantes de la respuesta:
  • id (integer): ID único del item/documento agregado. Necesario para identificar el documento en webhooks y resultados.
  • item_status (string): Estado actual del item. Inicialmente será pending.

​
Paso 3: Esperar la Validación

Una vez agregados los documentos, el sistema de Trébol procesará automáticamente la validación. Este proceso puede tomar varios minutos dependiendo de la complejidad del documento.

​
Configurar Webhooks

Para recibir notificaciones automáticas cuando la validación esté completa, configura un webhook: Endpoint: POST /webhooks 
{
  "url": "https://tu-servidor.com/webhooks/trebol",
  "events": ["verification_item.v2.completed"],
  "description": "Webhook para notificaciones de validación de documentos"
}

​
Notificación de Completado

Cuando la validación esté completa, recibirás una notificación webhook con la siguiente estructura: 
{
  "event_name": "verification_item.v2.completed",
  "data": {
    "verification_id": "vf_12345abcde",
    "item_id": 29639,
    "account_id": "99999999-9999-9999-9999-999999999999",
    "account_name": "Mi Empresa",
    "item_type": "doc_validation",
    "completed_at": "2025-01-15T10:45:00Z"
  }
}
Campos importantes del webhook:
  • event_name (string): Nombre del evento webhook. verification_item.v2.completed indica que un item de verificación fue completado.
  • data.verification_id (string): ID de la verificación a la que pertenece el item completado.
  • data.item_id (integer): ID del item/documento que fue completado.
  • data.completed_at (string): Timestamp ISO 8601 de cuando se completó la validación.
Una vez recibida esta notificación, puedes proceder a obtener los resultados completos de la validación.

​
Paso 4: Obtener Resultados de Validación

Para obtener los resultados completos de la validación, consulta el endpoint de verificación: Endpoint: GET /verifications/{verification-id}
Identificar el ítem completado: Cuando recibas la notificación webhook, usa el item_id del webhook para identificar qué documento específico fue validado. Si agregaste una etiqueta personalizada al crear el ítem (usando el campo tags), también puedes usar esa información para hacer coincidir el ítem con el ID de tu sistema interno.
cURL
curl -X GET 'https://api.gotrebol.com/verifications/vf_12345abcde' \
  -H 'Authorization: Bearer YOUR_API_KEY'

​
Respuesta con Resultados Completos

{
  "id": "vf_12345abcde",
  "status": "complete",
  "account_id": "99999999-9999-9999-9999-999999999999",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:45:00Z",
  "flow_id": "lean-flow",
  "documents_status": "full_upload",
  "items": [
    {
      "id": 29639,
      "item_status": "complete",
      "item_type": "doc_validation",
      "item_internal_status": "validation_completed",
      "item_value": {
        "rules_validation_result": [
          {
            "id": "regla_1",
            "validation_rule": "El documento no debe ser mas antiguo a 1 año a partir de la fecha actual",
            "variable_value": "2024-05-13",
            "validation_result": true
          },
          {
            "id": "regla_2",
            "validation_rule": "El documento debe pertenecer a LEANDRO ALBERTO GAMARRA",
            "variable_value": "SOLUCIONES INTEGRALES SAYNET",
            "validation_result": false
          }
        ],
        "log": {
          "item_type_validated_at": "2025-09-16T18:54:38.694Z",
          "rules_validated_at": "2025-09-16T18:54:38.694Z"
        },
        "item_type_validation_result": [
          {
            "validation_result": true,
            "reason": "El documento es una CSF mexicana porque está titulado \"Constancia de Situación Fiscal\" y contiene elementos clave como RFC, nombre, domicilio fiscal, actividades económicas, regímenes, obligaciones y un sello digital, todos emitidos por el SAT."
          }
        ]
      },
      "tags": {
        "internal_id": "some-internal-id"
      }
    }
  ],
  "tag": "test-1757976296",
  "email": "[email protected]",
  "country": "mx",
  "tax_id": "KTM220523T3A"
}
Campos importantes de la respuesta:
  • status (string): Estado general de la verificación. complete indica que todos los items han sido procesados.
  • items[].item_status (string): Estado del item individual. complete indica que la validación fue exitosa.
  • items[].item_value.rules_validation_result (array): Lista de resultados para cada regla de validación aplicada al documento.
  • items[].item_value.item_type_validation_result (array): Lista de resultados para la validación del tipo de documento.
  • items[].tags (object): Diccionario de etiquetas que se asignaron al ítem.

​
Paso 5: Agregar Items de Extracción (Opcional)

Una vez que has validado los documentos y confirmado que son del tipo correcto, puedes proceder a agregar items de extracción para obtener la información específica de cada uno. Endpoint: PUT /verifications/{verification-id}/add-items
Basado en resultados de validación: Usa los resultados del Paso 4 para determinar qué tipos de items agregar. Si por ejemplo, la validación confirmó que un documento es una CSF, ahora puedes agregar un item csf_mx para extraer la información fiscal.

​
Ejemplo de Solicitud

[
    {
      "type": "ac_mx",
      "options": {
        "file_url": "https://drive.google.com/uc?export=download&id=some-id"
      },
      "tags": {
        "internal_id": "acta-001"
      }
    },
    {
      "type": "union_documents_extractor",
      "options": {
        "file_url": "https://drive.google.com/uc?export=download&id=some-id"
      },
      "tags": {
        "internal_id": "union-doc-001"
      }
    },
    {
      "type": "csf_mx",
      "options": {
        "file_url": "https://drive.google.com/uc?export=download&id=some-id",
        "constancia_type": "business"
      },
      "tags": {
        "internal_id": "csf-001"
      }
    }
  ]
'

​
Tipos de Items Disponibles

​
Documentos Mexicanos

  • ac_mx: Para actas constitutivas mexicanas
  • aa_mx: Para actas de asamblea mexicanas
  • pw_mx: Para otorgamiento de poderes
  • fme_mx: Para folios mercantiles
  • csf_mx: Para constancias de situación fiscal mexicanas
  • person_id: Para Ids personales (INE, pasaportes, etc)
  • proof_address: Para comprobantes de domicilio
  • bank_statement: Para extractos bancarios

​
Extractores Especializados

  • lien_certificate: Para certificados de gravamen
  • property_deed: Para escrituras de propiedad
  • property_tax_receipt: Para recibos de impuestos prediales
  • payroll_receipt: Para recibos de nóminas
  • camara_comercio_co_extractor: Cámara de comercio (Cámara de Comercio)
  • trust_contract_fideicomiso_extractor: Contrato de fideicomiso
  • union_documents_extractor: Documentos de unión (pareja de hecho)
  • designacion_responsable_cumplimiento_extractor: Designación de responsable de cumplimiento
  • registro_actividades_vulnerables_extractor: Registro de actividades vulnerables
  • irs_ein_assignment_letter_extractor: Letra de asignación de EIN (Internal Revenue Service)
  • certificate_of_incumbency_extractor: Certificado de incumbencia
  • certificate_of_incorporation_extractor: Certificado de constitución
  • fincen_msb_registration_extractor: Registro de MSB (Money Services Business) en FinCEN

​
Items que no aplican

  • doc_validation: Para validacion de documentos
  • generic: Documentos genericos

​
Opciones Específicas

​
Para items csf_mx:

  • constancia_type (opcional): Especifica si es para empresa ("business") o individuo ("individual")

​
Respuesta Exitosa

{
  "success": true,
  "items": [
    {
      "id": 29640,
      "item_status": "pending",
      "item_type": "ac_mx",
      "options": {
        "file_url": "https://www.googleapis.com/downloadableFile"
      },
      "tags": {
        "internal_id": "acta-001"
      }
    }
  ]
}
Flujo completo: Después de este paso, los items de extracción serán procesados y recibirás webhooks cuando la extracción esté completa. Puedes ver los resultados usando el endpoint GET /verifications/{verification - id}.

​
Notificación de Extracción Completada

Cuando la extracción de información esté completa, recibirás una notificación webhook con el evento verification_item.v2.extraction_completed: 
{
  "event": "verification_item.v2.extraction_completed",
  "data": {
    "verification_id": "vf_12345abcde",
    "item_id": 29640,
    "item_type": "csf_mx",
    "extraction_completed_at": "2025-01-15T11:30:00Z",
    "success": true
  }
}
Campos de la notificación:
  • verification_id (string): ID de la verificación
  • item_id (number): ID del item que completó la extracción
  • item_type (string): Tipo de item extraído (ej. “csf_mx”, “ac_mx”)
  • extraction_completed_at (string): Timestamp ISO 8601 de cuando se completó la extracción
  • success (boolean): Indica si la extracción fue exitosa
Procesamiento asíncrono: La extracción de información puede tomar varios minutos dependiendo del tipo de documento y la complejidad del contenido. Usa esta notificación para saber cuándo los datos están listos para ser consultados.

​
Mejores Prácticas

​
Gestión de Flujos

Los flujos creados son reutilizables. Una vez configurado un flujo, puedes usarlo para múltiples verificaciones sin necesidad de recrearlo.
  • Crea flujos específicos para diferentes tipos de validación
  • Usa nombres descriptivos en friendly_name para facilitar la identificación
  • Considera crear flujos separados para diferentes países o casos de uso

​
Gestión de URLs de Documentos

Las URLs de documentos deben estar disponibles por al menos 5 minutos para garantizar la descarga exitosa.
  • Usa URLs con tokens de acceso temporal cuando sea posible

​
Manejo de Webhooks

  • Implementa validación de firma webhook para seguridad
  • Configura timeouts apropiados para evitar reintentos excesivos
  • Mantén un log de eventos webhook para debugging

​
Procesamiento Asíncrono

  • No bloquees tu aplicación esperando resultados de validación
  • Usa el sistema de webhooks para notificaciones automáticas
  • Implementa polling como fallback si los webhooks fallan

​
Troubleshooting

​
Documento no se descarga

Problema: El documento no se puede descargar desde la URL proporcionada. Soluciones:
  • Verifica que la URL sea accesible públicamente
  • Asegúrate de que la URL no requiera autenticación
  • Confirma que la URL esté disponible por al menos 5 minutos

​
Webhook no recibido

Problema: No recibes la notificación webhook cuando la validación está completa. Soluciones:
  • Verifica que tu endpoint webhook esté funcionando correctamente
  • Confirma que el webhook esté configurado con el evento correcto
  • Revisa los logs de tu servidor para errores de conexión