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

# Download de Objeto Blob

> Obtenha um link de download para qualquer arquivo com GET /v1/objects/download: um link temporário de até 24 horas para arquivos privados, ou a URL pública.

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

O Download de Objeto te dá um link para ler um arquivo. Para um arquivo **privado**, ele assina um link temporário, válido de 60 segundos a 24 horas, que funciona sem nenhuma credencial. Para um arquivo **público**, ele retorna a URL pública. Por padrão ele responde com um redirecionamento `302`, então você pode apontar um navegador ou `curl -L` diretamente para ele; `redirect=false` retorna o link como JSON. Exige o escopo `blob:read`.

Links temporários (`https://files.squarecloud.dev/d/...`) não podem ser revogados, suportam `Range` e requisições condicionais, e deixam de funcionar quando expiram ou quando o arquivo é excluído, movido ou muda de visibilidade. Para links que você pode revogar, limitar ou proteger com senha, use um [link de compartilhamento](/pt-br/blob-reference/endpoint/shares-create). Veja [Links e compartilhamento](/pt-br/blob-reference/links-and-sharing).

<ParamField query="object" type="string" required>
  O id do arquivo.
</ParamField>

<ParamField query="expires" type="number" default="3600">
  Por quanto tempo o link temporário dura, de 60 a 86400 segundos (24 horas).
</ParamField>

<ParamField query="redirect" type="boolean" default="true">
  `false` retorna o link como JSON em vez de redirecionar.
</ParamField>

<ParamField query="disposition" type="string">
  `inline` (abre no navegador) ou `attachment` (download). Defini-lo sempre gera um link temporário, mesmo para arquivos públicos.
</ParamField>

<ParamField query="filename" type="string" placeholder="report-september.pdf">
  O nome com que o navegador salva o arquivo. Implica `attachment`, a menos que `disposition` diga o contrário, e sempre gera um link temporário.
</ParamField>

### Limites de taxa

<Note>
  * 60 requisições por minuto nesta rota (`RATE_LIMITED`, 429).
  * Cada link temporário aceita 60 requisições por minuto por IP, além de um limite geral para todos os links da sua conta. Acima disso o link responde `429` em texto simples. Para entregar um arquivo a muitas pessoas, torne-o público: arquivos públicos são servidos pela CDN, sem esse limite. Um link expirado ou inválido responde `404`.
</Note>

### Resposta

Com `redirect=true` (padrão): `302` com o link em `Location` e `Cache-Control: no-store`. Com `redirect=false`:

<ResponseField name="status" type="string">
  "success" se bem-sucedida, "error" caso contrário.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Alternar objeto">
    <ResponseField name="url" type="string">
      O link: um link temporário em `files.squarecloud.dev`, ou a URL pública.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601 | null">
      Quando o link temporário expira, ou `null` para uma URL pública.
    </ResponseField>

    <ResponseField name="private" type="boolean">
      Se o arquivo é privado.
    </ResponseField>

    <ResponseField name="size" type="number">
      O tamanho do arquivo, em bytes.
    </ResponseField>

    <ResponseField name="content_type" type="string">
      O `Content-Type` com que o arquivo é servido.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://blob.squarecloud.app/v1/objects/download?object=prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf&expires=600&redirect=false' \
    --header 'Authorization: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    object: 'prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf',
    expires: '600',
    filename: 'invoice-september.pdf',
    redirect: 'false',
  });

  const res = await fetch(`https://blob.squarecloud.app/v1/objects/download?${params}`, {
    headers: { Authorization: 'YOUR_API_KEY' },
  });
  const { response } = await res.json();
  // hand response.url to the user; it works without credentials for 10 minutes
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "url": "https://files.squarecloud.dev/d/Rb7nKq2WvX9sLp4TzYc1Hm8JdF0gUe6AoNiQ3tVwBk5Sy.Pj3Lx9Qe2Rw7Ty4Uo",
      "expires_at": "2026-09-25T12:10:00.000Z",
      "private": true,
      "size": 88412,
      "content_type": "application/pdf"
    }
  }
  ```
</ResponseExample>

### Erros

| Código                       | HTTP | Quando                                                           |
| ---------------------------- | ---- | ---------------------------------------------------------------- |
| `INVALID_OBJECT`             | 400  | `object` está ausente, malformado ou não é seu.                  |
| `INVALID_DOWNLOAD_EXPIRES`   | 400  | `expires` não é um inteiro de 60 a 86400.                        |
| `INVALID_OBJECT_DISPOSITION` | 400  | `disposition` não é `inline` nem `attachment`.                   |
| `INVALID_FILENAME`           | 400  | `filename` fica vazio depois de remover os caracteres inválidos. |
| `OBJECT_NOT_FOUND`           | 404  | O arquivo não existe.                                            |
| `RATE_LIMITED`               | 429  | Mais de 60 requisições em um minuto.                             |