Skip to main content
Este flujo te permite crear una verificación sin proporcionar una file_url al inicio. En su lugar, Trébol te dará una URL para que subas el documento directamente. Este método es útil si los documentos se generan dinámicamente o se encuentran en un almacenamiento privado.

La experiencia de carga

Inicia la verificación, envía los documentos y confirma la carga. Trébol procesa cada documento según el tipo de ítem y entrega los resultados a tu aplicación. Flujo de carga: iniciar la verificación, enviar documentos, confirmar la carga y recibir resultados. Flujo de carga: iniciar la verificación, enviar documentos, confirmar la carga y recibir resultados. Ver el diagrama a tamaño completo Ver el diagrama a tamaño completo
Este flujo aplica a generic (clasificación), doc_validation (validación), tipos directos de extracción (por ejemplo, ac_mx, csf_mx, person_id, bank_statement o property_deed) y doc_splitter (separación de documentos). También aplica a los tipos personalizados cit_... habilitados para tu cuenta. Los items de consulta, como siger o rues, mantienen sus parámetros de consulta y no reciben una URL de carga.
Si la verificación usa options.require_files_for_generic_items: true, los items generic sin file_url se excluyen al crearla y no reciben una URL de carga. Esta restricción existente no aplica a doc_validation ni a los otros tipos de documento. Para usar carga directa con generic, envía options.require_files_for_generic_items: false al crear la verificación.
El proceso consta de tres pasos:
  1. Crear la verificación o agregar items: Envías la solicitud inicial a Trébol para registrar la verificación y recibir una URL de carga.
  2. Subir el documento: Usas la URL proporcionada para subir tu archivo de forma segura.
  3. Confirmar la carga: Notificas a Trébol que el archivo está listo para ser procesado.
El diagrama muestra los intercambios entre tu aplicación, la API de Trébol y el almacenamiento de archivos. El procesamiento empieza después de confirmar la carga, no al terminar de subir el archivo.Secuencia técnica: solicitar una URL de carga, subir el archivo, confirmar con uploaded_file y recibir el resultado por webhook o consultar el ítem.Secuencia técnica: solicitar una URL de carga, subir el archivo, confirmar con uploaded_file y recibir el resultado por webhook o consultar el ítem.Ver el diagrama a tamaño completoVer el diagrama a tamaño completo

Paso 1: Crear la verificación sin file_url

Crea la verificación como lo harías normalmente, pero omite el atributo file_url en las opciones del item. Trébol detecta que el archivo no está disponible y devuelve una upload_url única por item para que subas el archivo directamente. Endpoint: POST /verifications Usa la URL base de la API y la API key de tu ambiente. Los ejemplos siguientes usan producción (https://api.gotrebol.com); reemplaza YOUR_API_KEY por tu clave. Consulta Errores de la API si recibes una respuesta de error.
Omite file_url y conserva las demás opciones requeridas por el tipo. En particular, doc_validation sigue requiriendo options.client_item_type. Un item sin archivo permanece en estado pending hasta que completes la carga y la confirmes.
Trébol responde con el id de la verificación y una lista de items. Cada item de documento tiene su propio id y item_options.upload_url:
Guarda el id del item — lo necesitas en el Paso 3. En los requests usas type y options; en las respuestas estos campos se llaman item_type e item_options. Las URLs de los ejemplos son ilustrativas: usa siempre la URL completa que recibas. Para agregar documentos a una verificación existente, usa PUT /verifications/{id}/add-items con el mismo arreglo items, sin country ni tag. Reemplaza VERIFICATION_ID por el ID de la verificación:
El cuerpo de esta solicitud es:
Este endpoint devuelve directamente un arreglo de items, cada uno con su id y item_options.upload_url. Sigue los pasos 2 y 3 para cada archivo. Los items cc_co_ops que incluyen options.nit conservan su flujo de consulta existente. Este tipo también admite documentos; la opción nit selecciona la consulta y evita que el item espere una carga manual. Por ejemplo, la respuesta de add-items es un arreglo:
Ver detalle del endpoint y atributos en Crear una verificación.

Paso 2: Subir el documento

Con la upload_url recibida, sube el documento correspondiente mediante una solicitud PUT.
La URL es temporal: usa el valor completo recibido, incluidos sus parámetros de firma. Actualmente expira después de una hora. Si expira, consulta GET /verification-items/{id} para obtener una nueva item_options.upload_url. La URL no se invalida automáticamente después de un PUT; confirma la carga cuando hayas terminado de subir el archivo.
Endpoint: PUT a la upload_url del item. Esta URL ya está firmada: no envíes x-api-key al servidor de archivos. Headers:
  • Content-Type: El tipo MIME del archivo (ej. application/pdf, image/jpeg).
Body: El contenido binario del archivo.
Una carga exitosa devolverá un código de estado 200 OK.

Si tu sistema almacena el documento en Base64

Decodifica la cadena en tu cliente y envía los bytes resultantes a upload_url. El cuerpo del PUT es el archivo binario; una cadena Base64 enviada como texto no se convierte automáticamente en un documento. Por ejemplo, en Node.js:
documentBase64 debe contener solamente el contenido codificado, sin el prefijo data:application/pdf;base64,. Confirma la carga únicamente después de un PUT exitoso. Usa el mismo formato y límites de archivo que en el flujo habitual.

Paso 3: Confirmar y procesar el archivo

Una vez que el archivo se ha subido, debes notificar a Trébol que el documento está listo para ser procesado. Esto se hace enviando una solicitud PUT al endpoint del item específico, usando su id. Endpoint: PUT /verification-items/{item_id}
Usa el valor de items[].id recibido al crear la verificación, o el id del item del arreglo devuelto por add-items.
Body:
La respuesta 200 contiene el item y el indicador de procesamiento:
La API verifica que el archivo exista y solicita el procesamiento correspondiente al tipo del item: clasificación, validación, extracción o separación. La respuesta incluye item y triggeredSideEffects: true; el procesamiento es asíncrono y el item puede seguir en pending al responder. Consulta su estado o espera los webhooks de Trébol para conocer el resultado. Si el archivo todavía no existe, la confirmación devuelve 404 con el mensaje S3 object not found y no inicia el procesamiento. La confirmación comprueba la existencia del objeto; la validación del contenido ocurre durante el procesamiento. Tras ese 404, sube el archivo y vuelve a confirmar. Si la URL expiró, consulta el item para obtener una URL nueva antes de repetir el PUT del archivo. Repite los pasos 2 y 3 para cada item que requiera una carga directa.

PDF protegido con contraseña

Si el PDF que subes tiene contraseña, envíala en options.file_password al confirmar la carga. Trébol abre el documento con esa contraseña, procesa una copia sin contraseña y conserva el archivo original cifrado. La contraseña aplica a ese item únicamente y debe tener entre 1 y 128 caracteres. Trébol la almacena cifrada en la base de datos y no la devuelve en respuestas ni webhooks. Sustituye ITEM_ID y YOUR_API_KEY por el ID del item y tu API key, y clave-del-pdf por la contraseña del archivo.
También puedes enviar file_password en las opciones del item al crearlo (paso 1) y Trébol la usará cuando confirmes la carga. Si envías file_password en el PUT sin uploaded_file: true ni file_url, la API responde 400 con code: invalid_item_options_file_password. La opción es opcional: si el PDF no tiene contraseña, omítela y el flujo habitual no cambia. Si envías file_password, debe ser texto no vacío de 1 a 128 caracteres. Un valor vacío, null, un número o un texto demasiado largo produce 400 con code: invalid_item_options_file_password, incluso si el PDF no tiene contraseña. Para archivos que no son PDF, una contraseña con formato válido no se usa. Enviar uploaded_file: false con file_password y sin file_url también produce ese 400: no confirma la carga ni aporta una URL para procesar. Por ejemplo, el cuerpo de la respuesta de PUT /verification-items/{id} es:
Este error HTTP rechaza la solicitud antes del procesamiento. Es distinto de item_error: invalid_file_password, que aparece si la contraseña no abre el PDF. Resultados posibles al procesar:

PDF desde una URL

Para crear un item con file_url, envía la contraseña en sus mismas opciones, tanto en POST /verifications como en PUT /verifications/{verification-id}/add-items. La opción aplica a los tipos documentales indicados al inicio de esta guía, incluido doc_validation. Este ejemplo usa generic para clasificar el PDF automáticamente y lo agrega a una verificación existente. Sustituye VERIFICATION_ID, YOUR_API_KEY, la URL del documento y su contraseña. La URL debe seguir disponible durante al menos 5 minutos.

Reintentar con la contraseña correcta

Usa el mismo ITEM_ID y envía PUT /verification-items/{id}:
  • Carga directa: vuelve a enviar uploaded_file: true junto con la contraseña correcta, como en el primer ejemplo. Si el archivo ya no está disponible en el almacenamiento de carga, súbelo de nuevo antes de confirmar.
  • URL descargable: es obligatorio reenviar file_url junto con la contraseña correcta en la misma solicitud, aunque el item ya tenga una URL guardada. Enviar solo file_password produce 400. No necesitas uploaded_file: true ni crear otro item. Si la URL expiró, genera una nueva.
Este ejemplo reintenta desde una URL. Sustituye ITEM_ID, YOUR_API_KEY, la URL del documento y la contraseña correcta.
Trébol reinicia el procesamiento del item y limpia el error del intento anterior. Consulta el item o espera el webhook para conocer el resultado.