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

# Compartilhamento

> Crie, liste e revogue links de compartilhamento com blob.shares, e escolha entre um compartilhamento e um link de downloadUrl().

Um **compartilhamento** é um link para um objeto que pode **expirar**, ser **revogado**, limitar o **número de downloads** e, nos planos Pro e Enterprise, pedir uma **senha**. Veja [Links e compartilhamento](/pt-br/blob-reference/links-and-sharing) para entender como os links se comportam.

## Compartilhamento ou `downloadUrl()`?

|                     | [`downloadUrl()`](/pt-br/sdks/blob/objects#links-de-download) | `shares.create()`                                               |
| ------------------- | ------------------------------------------------------------- | --------------------------------------------------------------- |
| Objeto público      | URL permanente da CDN (`expires_at: null`)                    | Redireciona para a URL pública permanente (veja o aviso abaixo) |
| Objeto privado      | Link temporário, até 24 horas                                 | Link de compartilhamento, até 30 dias                           |
| Revogável           | **Não**                                                       | Sim, com `shares.revoke()`                                      |
| Limite de downloads | Não                                                           | Sim, `max_downloads`                                            |
| Senha               | Não                                                           | Sim, Pro e Enterprise                                           |

Use `downloadUrl()` para links de curta duração que você mesmo distribui, e um compartilhamento quando precisar revogar o link ou controlar quem faz o download.

## Criando um compartilhamento

```typescript theme={"system"}
const share = await blob.shares.create(id, {
    expires_in: 86400,     // seconds, 60 to 2592000 (default 86400)
    max_downloads: 10,     // 1 to 10000
    password: "secret123", // 8 to 128 characters, Pro and Enterprise
});

console.log(share.url);
```

| Opção           | Tipo     | Descrição                                                                             |
| --------------- | -------- | ------------------------------------------------------------------------------------- |
| `expires_in`    | `number` | Duração do link em segundos, de 60 a 2592000 (30 dias). Padrão 86400.                 |
| `max_downloads` | `number` | De 1 a 10000.                                                                         |
| `password`      | `string` | De 8 a 128 caracteres. Pro e Enterprise; os outros planos recebem `UPGRADE_REQUIRED`. |

O resultado tem `id`, `url`, `expires_at`, `max_downloads`, `password` (se há uma definida), `object` e `object_is_public`.

<Warning>
  Se `object_is_public` for `true`, o link de compartilhamento redireciona para a **URL pública permanente** do objeto: a senha, o limite de downloads e a expiração **não protegem nada**, porque o arquivo continua acessível nessa URL. Torne o objeto privado primeiro e depois compartilhe-o:

  ```typescript theme={"system"}
  const [result] = await blob.update(id, { private: true });
  if (result.ok) {
      id = result.id; // the id changes
      const share = await blob.shares.create(id, { max_downloads: 1 });
  }
  ```
</Warning>

## Listando compartilhamentos

```typescript theme={"system"}
const shares = await blob.shares.list();
```

Retorna um array de compartilhamentos, cada um com `id`, `url`, `object`, `expires_at`, `remaining_downloads`, `password` e `created_at`.

## Revogando um compartilhamento

```typescript theme={"system"}
await blob.shares.revoke(share.id);
```

O link para de funcionar. `revoke()` resolve sem valor, e revogar um compartilhamento que não existe falha com `SHARE_NOT_FOUND`.

<Tip>
  Excluir, mover ou renomear o objeto, ou alterar sua visibilidade, também quebra seus links de compartilhamento: eles apontam para o id antigo. Crie novos compartilhamentos para o novo id.
</Tip>

<Note>
  `shares.create()` e `shares.revoke()` têm uma **única tentativa**. Apenas `shares.list()`, uma leitura, é [tentado novamente](/pt-br/sdks/blob/errors#política-de-novas-tentativas).
</Note>

Referência da API: [Criar compartilhamento](/pt-br/blob-reference/endpoint/shares-create), [Listar compartilhamentos](/pt-br/blob-reference/endpoint/shares-list), [Excluir compartilhamento](/pt-br/blob-reference/endpoint/shares-delete).