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

# Inicio rápido de la API de Blob Storage

> Sube y descarga tu primer archivo con la API de Blob Storage: URL base v1, encabezado Authorization, una subida con curl, su respuesta y un enlace de descarga.

Blob Storage guarda tus archivos, sirve los públicos desde una CDN y genera enlaces para los privados. Esta página te lleva de una clave de API a un archivo subido y un enlace de descarga, con `curl`. El almacenamiento está incluido en todos los planes: consulta [Blob Storage](/es/services/blob) para ver los planes, los precios y las preguntas frecuentes.

## URL base

Todos los endpoints de esta referencia son relativos a:

```bash theme={"system"}
https://blob.squarecloud.app/v1
```

## Autenticación

Blob Storage acepta las mismas claves de API que la [API de Square Cloud](/es/api-reference/introduction), en el encabezado `Authorization`. La clave necesita el scope `blob:write` para subir y `blob:read` para listar y descargar, y no puede estar restringida a aplicaciones concretas. Crea una en la [configuración de seguridad de tu cuenta](https://squarecloud.app/es/account/security) y guárdala en una variable de entorno:

```bash theme={"system"}
export SQUARECLOUD_API_KEY="your-api-key"
```

Más sobre scopes y tokens de subida en [Autenticación](/es/blob-reference/authentication).

## Subir un archivo

[Object Post](/es/blob-reference/endpoint/post) recibe el archivo como `multipart/form-data` y su nombre, sin extensión, en la query:

```bash theme={"system"}
curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./logo.png'
```

```json theme={"system"}
{
  "status": "success",
  "response": {
    "id": "pub/3155597145698959364/images/logo.png",
    "private": false,
    "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo.png",
    "size": 416230,
    "name": "logo",
    "prefix": "images",
    "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
    "replaced": false
  }
}
```

El archivo es público por defecto: `url` funciona de inmediato en un navegador o en una etiqueta `<img>`. Guarda el `id` tal como llega, ya que todas las demás rutas lo usan.

Una sola solicitud acepta archivos de 512 bytes a 100 MB. Los archivos más grandes, de hasta 10 GiB, pasan por la [subida por partes](/es/blob-reference/endpoint/chunked-init) o por el [gateway S3](/es/blob-reference/s3-compatibility).

## Subir un archivo privado

Añade `private=true` y el archivo no tendrá URL pública (`url` es `null`):

```bash theme={"system"}
curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=invoice&prefix=invoices&private=true' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./invoice.pdf'
```

## Descargar un archivo

Un archivo público se descarga desde su `url`. Para uno privado, [Object Download](/es/blob-reference/endpoint/download) firma un enlace temporal que funciona sin credenciales y redirige a él, así que `curl -L` guarda el archivo:

```bash theme={"system"}
curl -L --output invoice.pdf \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=<id>' \
  --header "Authorization: $SQUARECLOUD_API_KEY"
```

Reemplaza `<id>` por el `id` de la subida. Añade `redirect=false` para recibir el enlace como JSON y pasárselo a otra persona. Para enlaces que puedas revocar o proteger con contraseña, crea un [enlace compartido](/es/blob-reference/endpoint/shares-create).

## Listar y eliminar archivos

[Object List](/es/blob-reference/endpoint/list) devuelve tus archivos página por página:

```bash theme={"system"}
curl --url 'https://blob.squarecloud.app/v1/objects?prefix=images/' \
  --header "Authorization: $SQUARECLOUD_API_KEY"
```

[Objects Delete](/es/blob-reference/endpoint/delete) elimina un archivo, o hasta 100 en una sola solicitud:

```bash theme={"system"}
curl --request DELETE \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "object": "<id>" }'
```

## Cuando algo falla

Los errores llegan como `{ "status": "error", "code": "..." }`. Los que probablemente encuentres primero:

| Código | HTTP | Solución |
| - | - | - |
| `ACCESS_DENIED` | 401 | La clave falta o no se reconoce. Revisa el encabezado `Authorization`. |
| `PERMISSION_DENIED` | 401 | La cuenta no tiene un plan activo, así que no puede subir archivos. |
| `MISSING_SCOPE` | 403 | La clave no tiene `blob:write` o `blob:read`. Crea una clave con ese scope. |
| `RESOURCE_NOT_ALLOWED` | 403 | La clave está restringida a aplicaciones. Usa una clave sin esa restricción. |
| `FILE_TOO_LARGE` | 413 | El archivo supera los 100 MB. Usa la subida por partes. |

Todos los códigos están en [Errores](/es/blob-reference/errors).

## Próximos pasos

<CardGroup cols={2}>
  <Card title="SDK de Blob" icon="js" href="/es/sdks/blob/client">
    Sube y gestiona archivos desde JavaScript, con las subidas por partes resueltas por ti.
  </Card>

  <Card title="Compatibilidad con S3" icon="bucket" href="/es/blob-reference/s3-compatibility">
    Usa aws-cli, boto3, rclone o cualquier SDK de AWS.
  </Card>

  <Card title="Enlaces y compartición" icon="share-nodes" href="/es/blob-reference/links-and-sharing">
    Enlaces temporales, enlaces compartidos y cuándo usar cada uno.
  </Card>

  <Card title="Subir desde el navegador" icon="upload" href="/es/blob-reference/endpoint/upload-tokens">
    Permite que tus visitantes suban archivos sin exponer tu clave de API.
  </Card>
</CardGroup>