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

# Criar Compartilhamento Blob

> Crie um link de compartilhamento com POST /v1/shares: válido por até 30 dias, revogável, com limite opcional de downloads e, no Pro e no Enterprise, senha.

<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 Criar Compartilhamento gera um link (`https://files.squarecloud.dev/s/...`) para entregar um arquivo a pessoas: um cliente, uma equipe, um testador. Ele funciona com arquivos públicos e privados, dura até 30 dias, pode ser revogado a qualquer momento e pode limitar quantas vezes o arquivo é baixado. No **Pro e no Enterprise**, ele também pode pedir uma senha. Exige o escopo `blob:write`.

Abrir o link baixa o arquivo. Um link protegido por senha mostra antes uma página pedindo a senha, no idioma do visitante. O link fica atrelado ao id atual do arquivo: excluir, mover ou mudar a visibilidade do arquivo faz o link responder `404` na hora, sem gastar um download. Veja [Links e compartilhamento](/pt-br/blob-reference/links-and-sharing) para comparar com os links temporários.

<ParamField body="object" type="string" required>
  O id do arquivo a compartilhar.
</ParamField>

<ParamField body="expires_in" type="number" default="86400">
  Por quanto tempo o link dura, de 60 a 2592000 segundos (30 dias).
</ParamField>

<ParamField body="max_downloads" type="number">
  Quantos downloads o link permite, de 1 a 10000. Depois de esgotado, ele responde `410`. Sem ele, não há limite.
</ParamField>

<ParamField body="password" type="string">
  Uma senha de 8 a 128 caracteres que o visitante precisa digitar antes de baixar. Somente Pro e Enterprise.
</ParamField>

<Warning>Para um arquivo **público**, o link redireciona para a URL pública permanente dele, que qualquer pessoa que abrir o link pode continuar usando. A senha, o limite de downloads e a expiração só protegem de verdade arquivos **privados**.</Warning>

### Limites

<Note>
  * 30 links por minuto (`RATE_LIMITED`, 429), e até 1000 links ativos por conta (`TOO_MANY_SHARES`, 409).
  * Cada link aceita 120 visitas por minuto por IP. Senhas erradas são limitadas por IP e por link.
  * O download de um arquivo privado passa por um link temporário: 60 requisições por minuto por IP, mais o limite geral da sua conta. Para entregar um arquivo a muitas pessoas, torne-o público.
</Note>

### Resposta

Responde `201 Created`.

<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="id" type="string">
      O id do compartilhamento. Use-o com o [Excluir Compartilhamento](/pt-br/blob-reference/endpoint/shares-delete).
    </ResponseField>

    <ResponseField name="url" type="string">
      O link a entregar.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601">
      Quando o link expira.
    </ResponseField>

    <ResponseField name="max_downloads" type="number | null">
      O limite de downloads, ou `null`.
    </ResponseField>

    <ResponseField name="password" type="boolean">
      Se o link pede uma senha.
    </ResponseField>

    <ResponseField name="object" type="string">
      O id do arquivo compartilhado.
    </ResponseField>

    <ResponseField name="object_is_public" type="boolean">
      `true` quando o arquivo é público: qualquer pessoa com a URL pública ainda consegue baixá-lo, então revogar, limitar ou proteger o compartilhamento não restringe o acesso ao próprio arquivo.
    </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>

### Erros

| Código                  | HTTP | Quando                                                  |
| ----------------------- | ---- | ------------------------------------------------------- |
| `INVALID_OBJECT`        | 400  | `object` está ausente, malformado ou não é seu.         |
| `INVALID_EXPIRES_IN`    | 400  | `expires_in` não é um inteiro de 60 a 2592000.          |
| `INVALID_MAX_DOWNLOADS` | 400  | `max_downloads` não é um inteiro de 1 a 10000.          |
| `INVALID_PASSWORD`      | 400  | A senha não tem de 8 a 128 caracteres.                  |
| `UPGRADE_REQUIRED`      | 403  | Senhas exigem Pro ou Enterprise.                        |
| `OBJECT_NOT_FOUND`      | 404  | O arquivo não existe.                                   |
| `TOO_MANY_SHARES`       | 409  | A conta tem 1000 links ativos. Revogue alguns primeiro. |
| `RATE_LIMITED`          | 429  | Mais de 30 links em um minuto.                          |