Subir documentos con carga directa

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.

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:

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.
Subir el documento: Usas la URL proporcionada para subir tu archivo de forma segura.
Confirmar la carga: Notificas a Trébol que el archivo está listo para ser procesado.

Ver el flujo técnico de integración

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.

Ver el diagrama a tamaño completo Ver 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.

curl --fail-with-body -X POST "https://api.gotrebol.com/verifications" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"country":"mx","tag":"upload-example","items":[{"type":"doc_validation","options":{"client_item_type":"ac_mx"}}]}'

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.

{
  "country": "mx",
  "tag": "some-tag-for-my-user",
  "items": [
    {
      "type": "doc_validation",
      "options": { "client_item_type": "ac_mx" }
    }
  ]
}

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:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "items": [
    {
      "id": 29639,
      "item_type": "doc_validation",
      "item_status": "pending",
      "item_options": {
        "upload_url": "https://files.gotrebol.com/uploads/ITEM_ID_original_file?SIGNED_PARAMETERS"
      }
    }
  ]
}

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:

curl --fail-with-body -X PUT "https://api.gotrebol.com/verifications/VERIFICATION_ID/add-items" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"items":[{"type":"ac_mx","options":{}},{"type":"doc_splitter","options":{}}]}'

El cuerpo de esta solicitud es:

{
  "items": [
    { "type": "ac_mx", "options": {} },
    { "type": "doc_splitter", "options": {} }
  ]
}

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:

[
  {
    "id": 29640,
    "item_type": "ac_mx",
    "item_status": "pending",
    "item_options": {
      "upload_url": "https://files.gotrebol.com/uploads/ITEM_ID_original_file?SIGNED_PARAMETERS"
    }
  }
]

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.

curl --fail-with-body -X PUT "https://files.gotrebol.com/uploads/ITEM_ID_original_file?SIGNED_PARAMETERS" \
-H "Content-Type: application/pdf" \
--data-binary @"/ruta/a/tu/documento.pdf"

import { readFile } from "node:fs/promises";
// Replace these values with the complete upload URL and your local file path.
const uploadUrl = "https://files.gotrebol.com/uploads/ITEM_ID_original_file?SIGNED_PARAMETERS";
const filePath = "/ruta/a/tu/documento.pdf";
const response = await fetch(uploadUrl, {
  method: "PUT",
  headers: { "Content-Type": "application/pdf" },
  body: await readFile(filePath),
});
if (!response.ok) throw new Error(`Upload failed: ${response.status}`);

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:

# Replace this value with the complete item_options.upload_url.
UPLOAD_URL="https://files.gotrebol.com/uploads/ITEM_ID_original_file?SIGNED_PARAMETERS"
# Replace document.b64 with your file containing only the Base64 string.
openssl base64 -d -A -in document.b64 | curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @-

// Replace this value with the complete item_options.upload_url.
const uploadUrl = "https://files.gotrebol.com/uploads/ITEM_ID_original_file?SIGNED_PARAMETERS";
// Replace this value with the complete Base64 document, without a data URI prefix.
const documentBase64 = "YOUR_DOCUMENT_BASE64";
const response = await fetch(uploadUrl, {
  method: "PUT",
  headers: { "Content-Type": "application/pdf" },
  body: Buffer.from(documentBase64, "base64"),
});
if (!response.ok) throw new Error(`Upload failed: ${response.status}`);

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:

{
  "options": {
    "uploaded_file": true
  }
}

# Replace YOUR_API_KEY and ITEM_ID with your API key and the returned item id.
curl --fail-with-body -X PUT "https://api.gotrebol.com/verification-items/ITEM_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"options":{"uploaded_file":true}}'

// Replace these values with your API key and the returned item id.
const apiKey = "YOUR_API_KEY";
const itemId = "ITEM_ID";
const response = await fetch(`https://api.gotrebol.com/verification-items/${itemId}`, {
  method: "PUT",
  headers: { "x-api-key": apiKey, "Content-Type": "application/json" },
  body: JSON.stringify({ options: { uploaded_file: true } }),
});
if (!response.ok) throw new Error(`Confirmation failed: ${response.status}`);
console.log(await response.json());

La respuesta 200 contiene el item y el indicador de procesamiento:

{
  "item": {
    "id": 29639,
    "item_type": "doc_validation",
    "item_status": "pending"
  },
  "triggeredSideEffects": true
}

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.

Intro al API de Trébol

Guías por caso de uso

Subir documentos con carga directa

La experiencia de carga

Paso 1: Crear la verificación sin `file_url`

Paso 2: Subir el documento

Si tu sistema almacena el documento en Base64

Paso 3: Confirmar y procesar el archivo

​La experiencia de carga

​Paso 1: Crear la verificación sin file_url

​Paso 2: Subir el documento

​Si tu sistema almacena el documento en Base64

​Paso 3: Confirmar y procesar el archivo

La experiencia de carga

Paso 1: Crear la verificación sin `file_url`

Paso 2: Subir el documento

Si tu sistema almacena el documento en Base64

Paso 3: Confirmar y procesar el archivo