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

# Blob Create Share

> Crea un enlace compartido con POST /v1/shares: válido hasta 30 días, revocable, con límite de descargas opcional y, en Pro y Enterprise, una contraseña.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  La clave de API de tu cuenta. Puedes encontrarla en la [configuración de tu cuenta](https://squarecloud.app/es/account/security).
</ParamField>

Create Share crea un enlace (`https://files.squarecloud.dev/s/...`) para entregar un archivo a personas: un cliente, un equipo, un tester. Funciona con archivos públicos y privados, dura hasta 30 días, se puede revocar en cualquier momento y puede limitar cuántas veces se descarga el archivo. En **Pro y Enterprise** también puede pedir una contraseña. Requiere el scope `blob:write`.

Abrir el enlace descarga el archivo. Un enlace protegido con contraseña muestra primero una página que pide la contraseña, en el idioma del visitante. El enlace está ligado al id actual del archivo: eliminar, mover o cambiar la visibilidad del archivo hace que responda `404` de inmediato, sin gastar una descarga. Consulta [Enlaces y uso compartido](/es/blob-reference/links-and-sharing) para ver cómo se compara con los enlaces temporales.

<ParamField body="object" type="string" required>
  El id del archivo a compartir.
</ParamField>

<ParamField body="expires_in" type="number" default="86400">
  Cuánto dura el enlace, de 60 a 2592000 segundos (30 días).
</ParamField>

<ParamField body="max_downloads" type="number">
  Cuántas descargas permite el enlace, de 1 a 10000. Una vez agotadas, responde `410`. Sin este campo, no hay límite.
</ParamField>

<ParamField body="password" type="string">
  Una contraseña de 8 a 128 caracteres que el visitante debe escribir antes de descargar. Solo Pro y Enterprise.
</ParamField>

<Warning>Para un archivo **público**, el enlace redirige a su URL pública permanente, que cualquiera que lo abra puede seguir usando. La contraseña, el límite de descargas y la expiración solo protegen de verdad los archivos **privados**.</Warning>

### Límites

<Note>
  * 30 enlaces por minuto (`RATE_LIMITED`, 429), y hasta 1000 enlaces activos por cuenta (`TOO_MANY_SHARES`, 409).
  * Cada enlace acepta 120 visitas por minuto por IP. Las contraseñas incorrectas están limitadas por IP y por enlace.
  * La descarga de un archivo privado pasa por un enlace temporal: 60 solicitudes por minuto por IP, más el límite general de tu cuenta. Para entregar un archivo a muchas personas, hazlo público.
</Note>

### Respuesta

Responde `201 Created`.

<ResponseField name="status" type="string">
  "success" si tuvo éxito, "error" si no.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Alternar objeto">
    <ResponseField name="id" type="string">
      El id del enlace compartido. Úsalo con [Delete Share](/es/blob-reference/endpoint/shares-delete).
    </ResponseField>

    <ResponseField name="url" type="string">
      El enlace que entregar.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601">
      Cuándo expira el enlace.
    </ResponseField>

    <ResponseField name="max_downloads" type="number | null">
      El límite de descargas, o `null`.
    </ResponseField>

    <ResponseField name="password" type="boolean">
      Si el enlace pide una contraseña.
    </ResponseField>

    <ResponseField name="object" type="string">
      El id del archivo compartido.
    </ResponseField>

    <ResponseField name="object_is_public" type="boolean">
      `true` cuando el archivo es público: cualquiera con su URL pública puede seguir descargándolo, así que revocar, limitar o proteger el enlace compartido no restringe el acceso al archivo en sí.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://blob.squarecloud.app/v1/shares' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
      "expires_in": 604800,
      "max_downloads": 5
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://blob.squarecloud.app/v1/shares', {
    method: 'POST',
    headers: {
      Authorization: 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      object: 'prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf',
      expires_in: 7 * 24 * 60 * 60,
      max_downloads: 5,
    }),
  });
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "id": "q8Zr2LwX7nT0vKc4Hs1YbA",
      "url": "https://files.squarecloud.dev/s/q8Zr2LwX7nT0vKc4Hs1YbA",
      "expires_at": "2026-10-02T12:00:00.000Z",
      "max_downloads": 5,
      "password": false,
      "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
      "object_is_public": false
    }
  }
  ```
</ResponseExample>

### Errores

| Código                  | HTTP | Cuándo                                                        |
| ----------------------- | ---- | ------------------------------------------------------------- |
| `INVALID_OBJECT`        | 400  | `object` falta, está mal formado o no es tuyo.                |
| `INVALID_EXPIRES_IN`    | 400  | `expires_in` no es un entero de 60 a 2592000.                 |
| `INVALID_MAX_DOWNLOADS` | 400  | `max_downloads` no es un entero de 1 a 10000.                 |
| `INVALID_PASSWORD`      | 400  | La contraseña no tiene de 8 a 128 caracteres.                 |
| `UPGRADE_REQUIRED`      | 403  | Las contraseñas requieren Pro o Enterprise.                   |
| `OBJECT_NOT_FOUND`      | 404  | El archivo no existe.                                         |
| `TOO_MANY_SHARES`       | 409  | La cuenta tiene 1000 enlaces activos. Revoca algunos primero. |
| `RATE_LIMITED`          | 429  | Más de 30 enlaces en un minuto.                               |