> ## Documentation Index
> Fetch the complete documentation index at: https://gotrebol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Subir documentos con carga directa

> Cómo subir documentos directamente a Trébol cuando no tienes una URL de descarga accesible.

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.

<Info>
  Este flujo de carga directa aplica a las 3 formas de procesamiento: items
  `generic` (clasificación), `doc_validation` (validación) o tipo directo
  (extracción, ej. `ac_mx`).
</Info>

El proceso consta de tres pasos:

1. **Crear la verificación**: 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.

***

## 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`

**Diferencia clave:** en el payload simplemente no incluyes `file_url`. El resto es idéntico al de cualquier verificación — aplica para las 3 formas de procesamiento; solo cambia el `type` del item según elijas [clasificación](/docs/guia-devs/crear-verificaciones/via-api/forma-clasificacion), [validación](/docs/guia-devs/crear-verificaciones/via-api/forma-validacion) o [extracción](/docs/guia-devs/crear-verificaciones/via-api/forma-extraccion).

```json theme={"dark"}
{
  "country": "mx",
  "tag": "some-tag-for-my-user",
  "items": [
    {
      "type": "generic"
    }
  ]
}
```

Trébol responderá con un `verification_id` y una lista de `items`, cada uno con su propio `id` y una `upload_url` única. La estructura de la respuesta es la misma sin importar el `type` del item.

```json theme={"dark"}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "items": [
    {
      "id": 29639,
      "type": "generic",
      "status": "pending",
      "options": {
        "upload_url": "https://s3-upload-url.trebol.com/some-presigned-url"
      }
    }
  ]
}
```

Guarda el `id` del item — lo necesitas en el Paso 3.

Ver detalle del endpoint y atributos en [Crear una verificación](/docs/guia-devs/crear-verificaciones/via-api/crear-verificacion).

***

## Paso 2: Subir el documento

Con la `upload_url` recibida, sube el documento correspondiente mediante una solicitud `PUT`.

<Warning>
  La `upload_url` es de un solo uso y expira después de 5 minutos.
</Warning>

**Endpoint:** `PUT` a la `upload_url` del `item`.

**Headers:**

* `Content-Type`: El tipo MIME del archivo (ej. `application/pdf`, `image/jpeg`).

**Body:**
El contenido binario del archivo.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X PUT "https://s3-upload-url.trebol.com/some-presigned-url" \
  -H "Content-Type: application/pdf" \
  --data-binary @"/ruta/a/tu/documento.pdf"
  ```
</CodeGroup>

Una carga exitosa devolverá un código de estado `200 OK`.

***

## 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}`

<Note>
  El `item_id` para este endpoint es el `id` del `item` que recibiste en la
  respuesta del **Paso 1**.
</Note>

**Body:**

```json theme={"dark"}
{
  "options": {
    "uploaded_file": true
  }
}
```

Después de este paso, el estado del `item` cambiará y Trébol comenzará el proceso de extracción de datos. Debes repetir los pasos 2 y 3 para cada `item` que requiera una carga directa.