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

# Guia rápido da API do Blob Storage

> Envie e baixe o seu primeiro arquivo com a API do Blob Storage: a URL base da v1, o header Authorization, um upload com curl, a resposta e um link de download.

O Blob Storage guarda os seus arquivos, entrega os públicos por uma CDN e gera links para os privados. Esta página leva você de uma chave de API até um arquivo enviado e um link de download, com `curl`. O armazenamento está incluído em todo plano: veja [Blob Storage](/pt-br/services/blob) para planos, preços e perguntas frequentes.

## URL base

Todo endpoint desta referência é relativo a:

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

## Autenticação

O Blob Storage aceita as mesmas chaves de API da [API da Square Cloud](/pt-br/api-reference/introduction), no header `Authorization`. A chave precisa do escopo `blob:write` para enviar e de `blob:read` para listar e baixar, e não pode ser restrita a aplicações específicas. Crie uma nas [configurações de segurança da sua conta](https://squarecloud.app/pt-br/account/security) e guarde-a em uma variável de ambiente:

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

Mais sobre escopos e tokens de upload em [Autenticação](/pt-br/blob-reference/authentication).

## Enviar um arquivo

O [Envio de Objeto](/pt-br/blob-reference/endpoint/post) recebe o arquivo como `multipart/form-data` e o nome dele, sem extensão, na 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
  }
}
```

O arquivo é público por padrão: a `url` funciona na hora em um navegador ou em uma tag `<img>`. Guarde o `id` exatamente como vem, porque todas as outras rotas o recebem.

Uma única requisição aceita arquivos de 512 bytes a 100 MB. Arquivos maiores, até 10 GiB, passam pelo [upload em partes](/pt-br/blob-reference/endpoint/chunked-init) ou pelo [gateway S3](/pt-br/blob-reference/s3-compatibility).

## Enviar um arquivo privado

Adicione `private=true` e o arquivo fica sem URL pública (`url` é `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'
```

## Baixar um arquivo

Um arquivo público é baixado pela `url` dele. Para um privado, o [Download de Objeto](/pt-br/blob-reference/endpoint/download) assina um link temporário que funciona sem credenciais e redireciona para ele, então o `curl -L` salva o arquivo:

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

Troque `<id>` pelo `id` do upload. Adicione `redirect=false` para receber o link em JSON e repassá-lo a outra pessoa. Para links que você pode revogar ou proteger com senha, crie um [link de compartilhamento](/pt-br/blob-reference/endpoint/shares-create).

## Listar e excluir arquivos

A [Lista de Objetos](/pt-br/blob-reference/endpoint/list) retorna os seus arquivos página por página:

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

O [Excluir Objetos](/pt-br/blob-reference/endpoint/delete) remove um arquivo, ou até 100 em uma requisição:

```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>" }'
```

## Quando algo falha

Os erros vêm como `{ "status": "error", "code": "..." }`. Os que você tem mais chance de encontrar primeiro:

| Código | HTTP | Solução |
| - | - | - |
| `ACCESS_DENIED` | 401 | A chave está ausente ou não foi reconhecida. Confira o header `Authorization`. |
| `PERMISSION_DENIED` | 401 | A conta não tem um plano ativo, então não pode enviar arquivos. |
| `MISSING_SCOPE` | 403 | A chave não tem `blob:write` ou `blob:read`. Crie uma chave com esse escopo. |
| `RESOURCE_NOT_ALLOWED` | 403 | A chave está restrita a aplicações. Use uma chave sem essa restrição. |
| `FILE_TOO_LARGE` | 413 | O arquivo passa de 100 MB. Use o upload em partes. |

Todos os códigos estão em [Erros](/pt-br/blob-reference/errors).

## Próximos passos

<CardGroup cols={2}>
  <Card title="SDK do Blob" icon="js" href="/pt-br/sdks/blob/client">
    Envie e gerencie arquivos pelo JavaScript, e o upload em partes feito automaticamente.
  </Card>

  <Card title="Compatibilidade com S3" icon="bucket" href="/pt-br/blob-reference/s3-compatibility">
    Use aws-cli, boto3, rclone ou qualquer SDK da AWS.
  </Card>

  <Card title="Links e compartilhamento" icon="share-nodes" href="/pt-br/blob-reference/links-and-sharing">
    Links temporários, links de compartilhamento e quando usar cada um.
  </Card>

  <Card title="Upload pelo navegador" icon="upload" href="/pt-br/blob-reference/endpoint/upload-tokens">
    Deixe visitantes enviarem arquivos sem expor a sua chave de API.
  </Card>
</CardGroup>