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

# Guida rapida all'API di Blob Storage

> Carica e scarica il tuo primo file con l'API di Blob Storage: URL base v1, header Authorization, un upload con curl, la risposta e un link di download.

Blob Storage conserva i tuoi file, serve quelli pubblici da una CDN e fornisce link a quelli privati. Questa pagina ti porta da una chiave API a un file caricato e a un link di download, con `curl`. Lo storage è incluso in ogni piano: consulta [Blob Storage](/it/services/blob) per piani, prezzi e FAQ.

## URL base

Ogni endpoint di questa reference è relativo a:

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

## Autenticazione

Blob Storage accetta le stesse chiavi API dell'[API di Square Cloud](/it/api-reference/introduction), nell'header `Authorization`. La chiave ha bisogno dello scope `blob:write` per caricare e di `blob:read` per elencare e scaricare, e non può essere limitata ad applicazioni specifiche. Creane una nelle [impostazioni di sicurezza del tuo account](https://squarecloud.app/it/account/security) e conservala in una variabile d'ambiente:

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

Scope e upload token sono spiegati in [Autenticazione](/it/blob-reference/authentication).

## Carica un file

[Object Post](/it/blob-reference/endpoint/post) accetta il file come `multipart/form-data` e il suo nome, senza estensione, nella 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
  }
}
```

Il file è pubblico per impostazione predefinita: `url` funziona subito in un browser o in un tag `<img>`. Salva l'`id` così come arriva, perché tutte le altre route lo richiedono.

Una singola richiesta accetta file da 512 byte a 100 MB. I file più grandi, fino a 10 GiB, passano per l'[upload chunked](/it/blob-reference/endpoint/chunked-init) o per il [gateway S3](/it/blob-reference/s3-compatibility).

## Carica un file privato

Aggiungi `private=true` e il file non avrà un URL pubblico (`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'
```

## Scarica un file

Un file pubblico si scarica dal suo `url`. Per uno privato, [Object Download](/it/blob-reference/endpoint/download) firma un link temporaneo che funziona senza credenziali e reindirizza lì, quindi `curl -L` salva il file:

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

Sostituisci `<id>` con l'`id` dell'upload. Aggiungi `redirect=false` per ricevere il link in JSON e passarlo a qualcun altro. Per link che puoi revocare o proteggere con una password, crea un [link di condivisione](/it/blob-reference/endpoint/shares-create).

## Elenca ed elimina file

[Object List](/it/blob-reference/endpoint/list) restituisce i tuoi file pagina per pagina:

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

[Objects Delete](/it/blob-reference/endpoint/delete) rimuove un file, o fino a 100 in una sola richiesta:

```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 qualcosa va storto

Gli errori arrivano come `{ "status": "error", "code": "..." }`. Quelli che incontrerai più probabilmente all'inizio:

| Codice | HTTP | Soluzione |
| - | - | - |
| `ACCESS_DENIED` | 401 | La chiave è mancante o non viene riconosciuta. Controlla l'header `Authorization`. |
| `PERMISSION_DENIED` | 401 | L'account non ha un piano attivo, quindi non può caricare file. |
| `MISSING_SCOPE` | 403 | La chiave non ha `blob:write` o `blob:read`. Crea una chiave con quello scope. |
| `RESOURCE_NOT_ALLOWED` | 403 | La chiave è limitata ad alcune applicazioni. Usa una chiave senza questa restrizione. |
| `FILE_TOO_LARGE` | 413 | Il file supera i 100 MB. Usa l'upload chunked. |

Tutti i codici sono in [Errori](/it/blob-reference/errors).

## Prossimi passi

<CardGroup cols={2}>
  <Card title="SDK Blob" icon="js" href="/it/sdks/blob/client">
    Carica e gestisci file da JavaScript, con gli upload chunked gestiti per te.
  </Card>

  <Card title="Compatibilità S3" icon="bucket" href="/it/blob-reference/s3-compatibility">
    Usa aws-cli, boto3, rclone o qualsiasi SDK AWS.
  </Card>

  <Card title="Link e condivisione" icon="share-nodes" href="/it/blob-reference/links-and-sharing">
    Link temporanei, link di condivisione e quando usare ciascuno.
  </Card>

  <Card title="Upload dal browser" icon="upload" href="/it/blob-reference/endpoint/upload-tokens">
    Permetti ai visitatori di caricare file senza esporre la tua chiave API.
  </Card>
</CardGroup>