Criar Compartilhamento Blob

POST

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

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,
  }),
});

{
  "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
  }
}

string

obrigatório

A chave da API para sua conta. Você pode encontrá-la nas configurações da conta.

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 para comparar com os links temporários.

string

obrigatório

O id do arquivo a compartilhar.

number

padrão:"86400"

Por quanto tempo o link dura, de 60 a 2592000 segundos (30 dias).

number

Quantos downloads o link permite, de 1 a 10000. Depois de esgotado, ele responde 410. Sem ele, não há limite.

string

Uma senha de 8 a 128 caracteres que o visitante precisa digitar antes de baixar. Somente Pro e Enterprise.

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.

Limites

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.

Resposta

Responde 201 Created.

string

“success” se bem-sucedida, “error” caso contrário.

object

Mostrar Alternar objeto

string

O id do compartilhamento. Use-o com o Excluir Compartilhamento.

string

O link a entregar.

ISO 8601

Quando o link expira.

number | null

O limite de downloads, ou null.

boolean

Se o link pede uma senha.

string

O id do arquivo compartilhado.

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.

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

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,
  }),
});

{
  "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
  }
}

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.

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

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,
  }),
});

{
  "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
  }
}

Primeiros Passos

Objetos

Uploads em Partes

Conta

Links de Compartilhamento

S3

Criar Compartilhamento Blob

Limites

Resposta

Erros

​Limites

​Resposta

​Erros

Limites

Resposta

Erros