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": "regla_1",
            "validation_rule": "El documento no debe ser mas antiguo a 1 año a partir de la fecha actual"
          }
        ]
      },
      "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": "regla_1",
          "validation_rule": "El documento no debe ser mas antiguo a 1 año a partir de la fecha actual"
        },
        {
          "id": "regla_2",
          "validation_rule": "El documento debe pertenecer a 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 personalizadas que se aplicarán durante la validación del documento. Cada regla debe tener las propiedades 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.

​
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: 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 consultar 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