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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Subir archivos directamente

> Sube archivos al almacenamiento de Whop con subidas prefirmadas de una sola parte y multiparte

Las subidas a Whop van **directamente al almacenamiento**. Cuando llamas a [Create File](https://docs.whop.com/es/api-reference/files/create-file.md), Whop no recibe tus bytes a través de la API. En su lugar, crea un registro de archivo y te devuelve una **URL de subida prefirmada** a la que tú mismo envías los bytes con `PUT`. El archivo se puede usar en cuanto esos bytes llegan al almacenamiento de Whop.

Este es el flujo de dos pasos sin procesar que hay detrás de los métodos `files.create` y `files.retrieve` del SDK. Recurre a él cuando subas desde el navegador (para que los bytes nunca pasen por tu servidor) o trabajes en un lenguaje sin SDK. También es la forma de enviar archivos lo bastante grandes como para necesitar una subida multiparte.

> [!NOTE]
>
> Los endpoints `/files` requieren la versión de la API `2026-08-21-1` o posterior. Cada solicitud de abajo la fija con la cabecera `Api-Version-Date`. Consulta [Versiones de la API](https://docs.whop.com/es/developer/api/versioning.md).

## El ciclo de vida de una subida

Cada subida consta de tres pasos, tanto si es de una parte como de muchas:

1. **Crea** el registro del archivo → Whop devuelve un destino prefirmado y el archivo empieza como `pending`.
2. **Sube** los bytes directamente a las URL prefirmadas.
3. **Consulta periódicamente** [Retrieve File](https://docs.whop.com/es/api-reference/files/retrieve-file.md) hasta que `upload_status` sea `ready`; entonces `url` y `size` se rellenan y el ID del archivo se puede adjuntar en cualquier lugar donde Whop acepte un documento.

Los campos `url` y `size` de un archivo siguen siendo `null` hasta que termina el procesamiento. `upload_status` pasa por `pending` → `processing` → `ready` (o `failed`).

## Subida de una sola parte

Usa un único `PUT` para cualquier archivo de menos de unos cientos de megabytes.

**1. Crea el archivo**

Envía el `filename` y, opcionalmente, una `visibility` (`private` de forma predeterminada). La `upload_url` de la respuesta es adonde van los bytes, y `upload_headers` son las cabeceras que debes enviar con ellos.

```bash theme={null}
curl https://api.whop.com/api/v1/files \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-08-21-1" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "terms.pdf", "visibility": "private" }'
```

```json theme={null}
{
  "object": "file",
  "id": "file_XXXXXXXX",
  "filename": "terms.pdf",
  "content_type": "application/pdf",
  "size": null,
  "url": null,
  "removed_by_moderation": false,
  "upload_status": "pending",
  "visibility": "private",
  "created_at": "2026-08-21T18:24:00.000Z",
  "width": null,
  "height": null,
  "blurhash": null,
  "duration_seconds": null,
  "waveform_url": null,
  "upload_url": "https://upload.whop.com/uploads/...&signature=...",
  "upload_headers": { "Content-Type": "application/pdf" },
  "multipart_upload_id": null,
  "multipart_upload_urls": null,
  "multipart_chunk_size": null
}
```

**2. Sube los bytes**

Envía con `PUT` el contenido del archivo a `upload_url`, incluidas todas las cabeceras de `upload_headers`. Esta solicitud va directamente al almacenamiento de archivos de Whop, **no** a `api.whop.com`, y no lleva ninguna cabecera `Authorization` de Whop: las credenciales van incluidas en la URL prefirmada.

```bash theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @terms.pdf
```

> [!WARNING]
>
> La URL prefirmada caduca una hora después de emitirse. Crea el archivo justo antes de subirlo y solicita uno nuevo si un `PUT` falla con `403` tras una larga espera. Las URL de las partes multiparte caducan antes, a los 15 minutos.

**3. Consulta hasta que esté listo**

Obtén el archivo por su ID hasta que `upload_status` pase a `ready`. El campo `url` contiene entonces un enlace de descarga: una URL permanente de la red de distribución de contenido cuando el archivo es `public`, o una URL firmada que caduca cuando es `private`.

```bash theme={null}
curl https://api.whop.com/api/v1/files/file_XXXXXXXX \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-08-21-1"
```

```json theme={null}
{
  "object": "file",
  "id": "file_XXXXXXXX",
  "filename": "terms.pdf",
  "content_type": "application/pdf",
  "size": 82345,
  "url": "https://files.whop.com/...&signature=...",
  "removed_by_moderation": false,
  "upload_status": "ready",
  "visibility": "private",
  "created_at": "2026-08-21T18:24:00.000Z",
  "width": null,
  "height": null,
  "blurhash": null,
  "duration_seconds": null,
  "waveform_url": null
}
```

## Subida multiparte

Para archivos grandes, sube por partes. Whop devuelve una URL prefirmada por parte. Las subes (opcionalmente en paralelo) y luego le indicas a Whop que las ensamble.

La subida multiparte es **obligatoria por encima de 5 GB**, ya que una sola solicitud de subida no puede superar ese tamaño. También es buena idea por encima de unos 100 MB, donde una subida larga es frágil. El archivo debe ser mayor de 5 MB, ya que todas las partes excepto la última deben tener al menos 5 MB.

**1. Crea el archivo con multiparte habilitado**

Pasa `multipart: true` y el `byte_size` total para que Whop sepa cuántas URL de partes prefirmadas devolver. La respuesta lleva un `multipart_upload_id`, una `url` prefirmada por cada `part_number` y el `multipart_chunk_size` (en bytes) que debe tener cada parte excepto la última.

```bash theme={null}
curl https://api.whop.com/api/v1/files \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-08-21-1" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "release.mp4", "visibility": "private", "multipart": true, "byte_size": 12582912 }'
```

```json theme={null}
{
  "object": "file",
  "id": "file_XXXXXXXX",
  "filename": "release.mp4",
  "content_type": "video/mp4",
  "size": null,
  "url": null,
  "removed_by_moderation": false,
  "upload_status": "pending",
  "visibility": "private",
  "created_at": "2026-08-21T18:24:00.000Z",
  "width": null,
  "height": null,
  "blurhash": null,
  "duration_seconds": null,
  "waveform_url": null,
  "upload_url": null,
  "upload_headers": {},
  "multipart_upload_id": "2~aBcD1234...",
  "multipart_upload_urls": [
    { "part_number": 1, "url": "https://upload.whop.com/...&part_number=1&signature=..." },
    { "part_number": 2, "url": "https://upload.whop.com/...&part_number=2&signature=..." },
    { "part_number": 3, "url": "https://upload.whop.com/...&part_number=3&signature=..." }
  ],
  "multipart_chunk_size": 5242880
}
```

> [!NOTE]
>
> Las subidas multiparte admiten como máximo **10.000 partes** de 5 MB cada una, unos 50 GB. Un `byte_size` que necesitaría más partes se rechaza con un `400`.

**2. Sube cada parte y guarda su ETag**

Divide el archivo en fragmentos de `multipart_chunk_size` bytes (la última parte puede ser más pequeña) y envía con `PUT` cada fragmento a la `url` de la parte correspondiente. Cada respuesta de subida devuelve una **cabecera `ETag`**; guárdala junto al `part_number`, ya que necesitarás ambos para terminar.

```javascript theme={null}
import { readFile } from "node:fs/promises";

const bytes = await readFile("./release.mp4");
const chunkSize = created.multipart_chunk_size;

const parts = await Promise.all(
  created.multipart_upload_urls.map(async ({ part_number, url }) => {
    const start = (part_number - 1) * chunkSize;
    const chunk = bytes.subarray(start, start + chunkSize);

    const res = await fetch(url, { method: "PUT", body: chunk });
    if (!res.ok) throw new Error(`Part ${part_number} failed: ${res.status}`);

    // The ETag header comes back quoted, e.g. "\"abc123\"" — send it as-is.
    return { part_number, etag: res.headers.get("etag") };
  }),
);
```

**3. Completa la subida**

Devuelve el `multipart_upload_id` y el `part_number` + `etag` de cada parte a [Complete File Multipart Upload](https://docs.whop.com/es/api-reference/files/complete-file-multipart-upload.md). Whop ensambla las partes en el archivo final.

```bash theme={null}
curl https://api.whop.com/api/v1/files/file_XXXXXXXX/complete \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-08-21-1" \
  -H "Content-Type: application/json" \
  -d '{
    "multipart_upload_id": "2~aBcD1234...",
    "multipart_parts": [
      { "part_number": 1, "etag": "\"5eb63bbbe01eeed093cb22bb8f5acdc3\"" },
      { "part_number": 2, "etag": "\"9e107d9d372bb6826bd81d3542a419d6\"" },
      { "part_number": 3, "etag": "\"e4d909c290d0fb1ca068ffaddf22cbd0\"" }
    ]
  }'
```

> [!WARNING]
>
> Todas las partes deben aparecer, en orden, con el `ETag` exacto devuelto al subirlas. Un `multipart_upload_id` desconocido o un `ETag` que no coincide devuelve un `400`: vuelve a subir la parte problemática y completa la subida de nuevo.

**4. Consulta hasta que esté listo**

Al igual que con las subidas de una sola parte, obtén el archivo hasta que `upload_status` sea `ready`. Entonces el ID estará listo para adjuntarse.

## Elegir una visibilidad

`visibility` se establece al crear el archivo y no se puede cambiar después:

| Visibilidad | `url` que obtienes | Úsala para |
| - | - | - |
| `private` (predeterminada) | URL firmada que caduca | Documentos legales, pruebas de disputas, archivos subidos por usuarios |
| `public` | URL permanente y sin firmar de la red de distribución de contenido | Imágenes de productos, miniaturas, imagen de marca, recursos de marketing |

Los archivos públicos se almacenan en caché en la CDN de Whop y no se pueden revocar, así que mantén el valor predeterminado `private` para todo lo que sea sensible. Consulta [Subir archivos](https://docs.whop.com/es/developer/guides/upload-files.md#accessing-private-files) para obtener más información.

## Usar un archivo subido

Cuando un archivo esté `ready`, pasa su `id` en cualquier lugar donde Whop acepte un documento, por ejemplo las pruebas de una [disputa](https://docs.whop.com/es/api-reference/disputes/dispute) o los documentos legales de una cuenta.

## Próximos pasos

> [card] [Subir archivos (SDK)](https://docs.whop.com/es/developer/guides/upload-files.md)
>
> Cómo envuelven este flujo los métodos `files.create` y `files.retrieve` del SDK.

> [card] [Create File](https://docs.whop.com/es/api-reference/files/create-file.md)
>
> Referencia completa de la solicitud y la respuesta del endpoint de creación.

> [card] [Complete File Multipart Upload](https://docs.whop.com/es/api-reference/files/complete-file-multipart-upload.md)
>
> Referencia para ensamblar las partes multiparte.

> [card] [Versiones de la API](https://docs.whop.com/es/developer/api/versioning.md)
>
> Por qué importa la cabecera `Api-Version-Date` y cómo fijarla.


## Related topics

- [Subir archivos](https://docs.whop.com/es/developer/guides/upload-files.md)
- [API de archivos](https://docs.whop.com/es/api-reference/files/file.md)
- [Archivo](https://docs.whop.com/es/api-reference/legacy/files/file.md)
