> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File

> Carica PDF, immagini, video e loghi per i tuoi QR code.

> [!NOTE]
>
> L'API di GetQR è in beta ed è disponibile per alcuni workspace selezionati. I dettagli possono cambiare prima del rilascio generale.

I QR code PDF, Image e Video puntano a un file, e anche un logo personalizzato è un file. Il caricamento avviene in due passaggi: registra il file per ottenere un URL, poi invia i byte a quell'URL.

| Metodo | Percorso | Descrizione |
| - | - | - |
| `POST` | `/api/v1/files` | [Registra il caricamento di un file](#registra-il-caricamento-di-un-file) |

## Carica un file

**1. Registra il file**

Chiama [Registra il caricamento di un file](#registra-il-caricamento-di-un-file) con `target`, `contentType` e `size` del file. Il `target` determina i tipi di contenuto accettati e il limite di dimensione. Ricevi un `fileId` e un `uploadUrl`.

**2. Invia il file**

Invia il file con una richiesta `PUT` a `uploadUrl`. I suoi `Content-Type` e `Content-Length` devono corrispondere esattamente al `contentType` e alla `size` registrati: qualsiasi altro valore viene rifiutato. L'URL è prefirmato, quindi non aggiungere la chiave API. Scade dopo 10 minuti.

```bash theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @menu.pdf
```

**3. Usa l'ID del file**

Passa `fileId` quando [crei un QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md):

* Come `fileId` per un QR code `pdf`, `image` o `video`. Caricalo con il target corrispondente.
* Come `fileId` per l'immagine del profilo di un QR code `vcard`, `social`, `multilink` o `event`. Caricalo con il target `logo`.
* Come `logoOptions.fileId`, con `logoOptions.type` impostato su `uploaded`, per un logo personalizzato. Caricalo con il target `logo`. Consulta [Personalizzazione](https://docs.getqr.com/it/api/guides/customization.md).

## Limiti

| `target` | Tipi di contenuto accettati | Dimensione massima |
| - | - | - |
| `pdf` | `application/pdf` | 20 MB (20.971.520 byte) |
| `image` | `image/*` | 5 MB (5.242.880 byte) |
| `video` | `video/*` | 50 MB (52.428.800 byte) |
| `logo` | `image/*` | 5 MB (5.242.880 byte) |

* **Tipo MIME semplice.** Invia un solo tipo e sottotipo in minuscolo, come `image/png`. Parametri come `;charset=` ed elenchi vengono rifiutati.
* **Niente SVG.** I tipi basati su XML come `image/svg+xml` non sono accettati. Carica un'immagine raster come `image/png` o `image/jpeg`.

## Header

**Authorization** `string` *required*

`Bearer` seguito dalla tua chiave API. Consulta [Autenticazione](https://docs.getqr.com/it/api/authentication.md).

**Content-Type** `string` *required*

`application/json`.

## Registra il caricamento di un file

`POST /api/v1/files`

Registra un file e restituisce un URL prefirmato su cui caricarlo. Questa chiamata non carica il file.

**target** `string` *required*

A cosa serve il file: `pdf`, `image`, `video` o `logo`. Determina i tipi di contenuto accettati e il limite di dimensione. Consulta [Limiti](#limiti).

**contentType** `string` *required*

Tipo MIME del file, ad esempio `application/pdf`, senza parametri. La richiesta di caricamento deve inviare esattamente questo `Content-Type`.

**size** `integer` *required*

Dimensione esatta del file in byte, un numero intero positivo. Viene confrontata con il limite del target. La richiesta di caricamento deve inviare esattamente questo `Content-Length`.

**name** `string`

Nome originale del file, fino a 255 caratteri. Conservato per essere mostrato nella dashboard. Un percorso con `/` o `\` viene rifiutato.

**fileId** `string`

ID da passare come `fileId` o `logoOptions.fileId`.

**uploadUrl** `string`

URL prefirmato a cui inviare il file con `PUT`.

**expiresIn** `integer`

Secondi prima della scadenza di `uploadUrl`: `600`.

**method** `string`

Metodo HTTP per il caricamento: `PUT`.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/files" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "pdf",
    "contentType": "application/pdf",
    "size": 248000,
    "name": "menu.pdf"
  }'
```

```json 200 theme={null}
{
  "fileId": "file_7bQ2xR9mKp",
  "uploadUrl": "https://storage.getqr.com/qrs-content/pdf/file_7bQ2xR9mKp?X-Amz-...",
  "expiresIn": 600,
  "method": "PUT"
}
```

## Problemi comuni

> [accordion] 422 "Content type … is not allowed for target"
>
> Il tipo di contenuto non corrisponde al target. Ad esempio, `pdf` accetta solo `application/pdf`. Consulta [Limiti](#limiti).

> [accordion] 422 "must be a single lowercase type/subtype"
>
> Invia il tipo di contenuto in minuscolo e senza parametri: `image/png`, non `Image/PNG` o `image/png; charset=utf-8`.

> [accordion] 422 "File is too large for target"
>
> La `size` dichiarata supera il limite del target. Comprimi il file prima di registrarlo.

> [accordion] Il caricamento su uploadUrl non riesce
>
> L'URL scade 10 minuti dopo la registrazione del file, e la richiesta deve inviare esattamente i `Content-Type` e `Content-Length` registrati. Registra di nuovo il file per ottenere un nuovo URL.

> [accordion] 422 "is registered but its content was never uploaded" durante la creazione di un QR code
>
> Hai registrato il file ma la `PUT` su `uploadUrl` non è stata completata. Carica il file, poi crea il QR code.

> [accordion] 422 "was uploaded to …" durante la creazione di un QR code
>
> Il file è stato registrato con un target diverso, ad esempio un file `image` usato per un QR code `pdf`. Registra un nuovo caricamento con il target corrispondente.

> [accordion] 404 "File … was not found" durante la creazione di un QR code
>
> Il `fileId` non esiste. Prendilo dalla risposta di [Registra il caricamento di un file](#registra-il-caricamento-di-un-file).

## Passaggi successivi

> [card] [QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md)

> [card] [Tipi di QR](https://docs.getqr.com/it/api/guides/qr-types.md)

> [card] [Personalizzazione](https://docs.getqr.com/it/api/guides/customization.md)

> [card] [Errori](https://docs.getqr.com/it/api/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.