Flujo de Validación de Documentos

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:

Crear flujo personalizado - Configurar el flujo de validación específico para tu caso de uso
Crear verificación - Inicializar la verificación usando el flujo creado
Agregar documentos - Añadir los documentos a validar usando el endpoint add-items
Esperar validación - El sistema procesa los documentos automáticamente
Recibir resultados - Obtener los resultados completos de la validación

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:

Paso	Acción	Responsable	Endpoint	Descripción
0	Crear flujo de validación	Usuario	`POST /account-flows`	Configurar el flujo personalizado para validaciones (solo una vez)
1	Crear verificación	Usuario	`POST /verifications`	Inicializar la verificación usando el flujo creado
2	Agregar documentos	Usuario	`PUT /verifications/{id}/add-items`	Enviar documentos para validación
3	Procesar documentos	Trébol	-	Sistema procesa y valida los documentos automáticamente
4	Notificar completado	Trébol	Webhook	Enviar notificación cuando la validación esté lista
5	Obtener resultados	Usuario	`GET /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. Endpoint: POST /verifications

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

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).
flow_id (string): Identificador del flujo de verificación predefinido. Usa lean-flow para el flujo de validación de documentos.
tag (string): Etiqueta única para identificar tu verificación. Útil para tracking y debugging.

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=1UuVEkuWpPl0fDPxMnf6AgUGoZxhlz5Dt",
      "client_item_type": "csf_mx",
      "ruleset": [
        "El documento no debe ser más antiguo a 1 año",
        "El documento debe pertenecer a LEANDRO ALBERTO GAMARRA"
      ]
    }
  }
]

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.

Parámetros opcionales:

options.client_item_type (string): Tipo específico del documento para optimizar la validación. Ejemplo: csf_mx para constancia de situación fiscal.
options.ruleset (array): Lista de reglas personalizadas que se aplicarán durante la validación del documento.

Respuesta del Add Items

[
  {
    "id": 29639,
    "item_order": 3,
    "item_status": "pending",
    "item_type": "generic",
    "item_value": {},
    "item_options": {
      "upload_url": "https://files.sandbox.gotrebol.com/uploads/29639_original_file?response-content-type=binary%2Foctet-stream&response-content-disposition=inline&Expires=1757721700&Key-Pair-Id=KG3EWMEY9ARYS&Signature=AYi3Q58r0MuFCxoIYVhxIaH9DYNA-lBO~zohmXYT28b3KEPI8xUmFlOmR0bOlPwceZujge0cKExpUmXxw4aw3XrrCbPqp0XHc2knx1LtGrtNdB9M2GPZ9srMAofixIki0wSswZ3mEdq4iOxKKTtJlhiEbVXYyPOmeWA~EIR1tDr2mNkGS5sOHSkmOHTpnobjnn5oGwwADykdn-5jf9-AnGbXkGWSgjQwIVKxcJny3SLeGL03gg3STfM68gnBM2QbNJQAYDjdYNzEVylTBFVL8SMiQHVlW5SimIojL9paOKUt6xTS78PhhkGeEapjioAOmzJA1mEcy8LPL5QmvDHaLQ__"
    }
  }
]

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.
item_options.upload_url (string): URL de carga alternativa si el documento necesita ser subido directamente.

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}

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_value": {
        "document_type": "csf_mx",
        "validation_results": [
          {
            "rule": "El documento no debe ser más antiguo a 1 año",
            "status": "passed",
            "details": "Documento emitido hace 6 meses"
          },
          {
            "rule": "El documento debe pertenecer a LEANDRO ALBERTO GAMARRA",
            "status": "passed",
            "details": "Nombre encontrado en el documento"
          }
        ],
        "extracted_data": {
          "tax_id": "KTM220523T3A",
          "name": "LEANDRO ALBERTO GAMARRA",
          "issue_date": "2024-07-15",
          "status": "active"
        }
      },
      "validation_result": {
        "overall_status": "valid",
        "confidence_score": 0.95,
        "processed_at": "2025-01-15T10:45:00Z"
      }
    }
  ],
  "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[].validation_result.overall_status (string): Estado general de la validación del documento. Puede ser valid, invalid, o warning.
items[].validation_result.confidence_score (number): Puntuación de confianza de la validación (0.0 a 1.0). Valores más altos indican mayor confianza.
items[].item_value.validation_results (array): Lista de resultados para cada regla de validación aplicada al documento.

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

Intro al API de Trébol

​Resumen del Flujo

​Resumen del Proceso

​Paso 0: Crear el Flujo de Validación

​Respuesta de Creación de Flujo

​Paso 1: Crear la Verificación

​Respuesta Exitosa

​Paso 2: Agregar Documentos para Validación

​Respuesta del Add Items

​Paso 3: Esperar la Validación

​Configurar Webhooks

​Notificación de Completado

​Paso 4: Obtener Resultados de Validación

​Respuesta con Resultados Completos

​Mejores Prácticas

​Gestión de Flujos

​Gestión de URLs de Documentos

​Manejo de Webhooks

​Procesamiento Asíncrono

​Troubleshooting

​Documento no se descarga

​Webhook no recibido

Resumen del Flujo

Resumen del Proceso

Paso 0: Crear el Flujo de Validación

Respuesta de Creación de Flujo

Paso 1: Crear la Verificación

Respuesta Exitosa

Paso 2: Agregar Documentos para Validación

Respuesta del Add Items

Paso 3: Esperar la Validación

Configurar Webhooks

Notificación de Completado

Paso 4: Obtener Resultados de Validación

Respuesta con Resultados Completos

Mejores Prácticas

Gestión de Flujos

Gestión de URLs de Documentos

Manejo de Webhooks

Procesamiento Asíncrono

Troubleshooting

Documento no se descarga

Webhook no recibido