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

# Introduzione all'API

> Gestisci QR code, template, statistiche e report dal tuo codice.

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

L'API di GetQR è un'API REST per le stesse operazioni che fai nella dashboard: creare e aggiornare QR code, scaricarne le immagini, leggere le statistiche delle scansioni ed esportare report. Autenticati con la chiave API del tuo account e chiama gli endpoint versionati sotto `/api/v1`.

## Cosa puoi fare

> [card] [QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md)
>
> Crea, elenca, aggiorna, metti in pausa, duplica, elimina e scarica QR code.

> [card] [Statistiche](https://docs.getqr.com/it/api/endpoints/analytics.md)
>
> Totali e suddivisioni delle scansioni per un singolo QR code o per l'intero workspace.

> [card] [Report](https://docs.getqr.com/it/api/endpoints/reports.md)
>
> Esporta un report una tantum o pianifica l'invio periodico di report via email.

> [card] [Template](https://docs.getqr.com/it/api/endpoints/templates.md)
>
> Salva i design e applicali ai nuovi QR code.

> [card] [Creazioni di QR in blocco](https://docs.getqr.com/it/api/endpoints/bulk-qr-creations.md)
>
> Crea fino a 100 QR code in una volta da JSON o da un file CSV.

> [card] [File](https://docs.getqr.com/it/api/endpoints/files.md)
>
> Carica PDF, immagini, video e loghi per i tuoi QR code.

> [card] [Stato](https://docs.getqr.com/it/api/endpoints/health.md)
>
> Verifica che l'API sia attiva. Non serve una chiave API.

## Guide

> [card] [Tipi di QR](https://docs.getqr.com/it/api/guides/qr-types.md)
>
> Il formato dei dati per ciascuno dei 16 tipi di QR.

> [card] [Personalizzazione](https://docs.getqr.com/it/api/guides/customization.md)
>
> Stili dei punti, angoli, colori, cornici e loghi.

> [card] [Regole di accesso](https://docs.getqr.com/it/api/guides/access-rules.md)
>
> Pianificazioni, limiti di scansioni, password, pausa ed eliminazione.

## URL di base

Tutti gli endpoint si trovano sotto un unico URL di base:

```text theme={null}
https://getqr.com/api/v1
```

## Versioni

La versione dell'API fa parte del percorso: tutti gli endpoint si trovano sotto `/api/v1/`.

* Le modifiche incompatibili escono con un nuovo prefisso di versione, ad esempio `/api/v2/`, e `/api/v1/` continua a funzionare.
* Le aggiunte compatibili, come nuovi campi facoltativi o nuovi endpoint, possono comparire all'interno di v1. Ignora i campi della risposta che il tuo codice non riconosce.

## Guida rapida

**1. Ottieni la tua chiave API**

Genera o visualizza la tua chiave nelle impostazioni dell'account. Consulta [Autenticazione](https://docs.getqr.com/it/api/authentication.md).

**2. Verifica che l'API sia raggiungibile**

```bash theme={null}
curl https://getqr.com/api/v1/health
```

La risposta è `{ "status": "ok", "version": "v1" }`.

**3. Crea il tuo primo QR code**

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-qr-0001" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page"
  }'
```

L'API risponde `201` con il nuovo QR code, inclusi il suo `id` e il suo `shortLink`.

**4. Scarica l'immagine**

```bash theme={null}
curl "https://getqr.com/api/v1/qrs/{qrId}/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png
```

## Richieste e risposte

* **Formato.** Invia il corpo delle richieste in JSON con `Content-Type: application/json`. Fa eccezione il caricamento CSV per la [creazione in blocco](https://docs.getqr.com/it/api/endpoints/bulk-qr-creations.md), che usa `multipart/form-data`.
* **Risposte.** Le risposte sono in JSON. I download, come le immagini dei QR e gli archivi ZIP delle creazioni in blocco, restituiscono direttamente il file.
* **Date.** Le date sono stringhe ISO 8601 in UTC, ad esempio `2026-08-01T10:00:00.000Z`.
* **Parametri di query.** I parametri booleani accettano le stringhe `true` o `false`.
* **Aggiornamenti parziali.** Gli endpoint `PATCH` modificano solo i campi che invii.
* **Dati riservati.** Le risposte non includono mai password o identificativi interni. Un QR code protetto da password indica solo `passwordProtected: true`.
* **Workspace.** Ogni richiesta viene eseguita nel workspace a cui appartiene la tua chiave API. Non devi indicare l'ID del workspace. Consulta [Accesso e ruoli](https://docs.getqr.com/it/api/authentication.md#accesso-e-ruoli).
* **Errori.** Le richieste non riuscite restituiscono un oggetto `error` con un `code` stabile. Consulta [Errori](https://docs.getqr.com/it/api/errors.md).

## Paginazione

Gli endpoint di elenco (QR code, template e report programmati) accettano due parametri di query:

| Parametro | Descrizione |
| - | - |
| `page` | Pagina da restituire. Predefinito `1`. |
| `pageSize` | Risultati per pagina, fino a `100`. Predefinito `100`. |

Rispondono con un array `data` e un oggetto `pagination`:

```json theme={null}
{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}
```

| Campo | Descrizione |
| - | - |
| `page` | La pagina che hai ricevuto. |
| `pageSize` | La dimensione di pagina che hai ricevuto. |
| `total` | Numero di risultati su tutte le pagine. |
| `hasMore` | `true` finché c'è un'altra pagina da leggere. |

Richiedi la pagina successiva finché `hasMore` è `true`. Un `pageSize` superiore a `100` restituisce [`422`](https://docs.getqr.com/it/api/errors#errori-di-validazione).

## Idempotenza

Dopo un errore di rete potresti non sapere se una richiesta è andata a buon fine. Per ripetere in sicurezza [Crea un QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md#crea-un-qr-code), invia un header `Idempotency-Key` con un valore univoco a tua scelta:

```bash theme={null}
-H "Idempotency-Key: order-4821-qr"
```

* Se ripeti la richiesta con la stessa chiave entro 24 ore, ricevi la risposta originale invece di creare un secondo QR code.
* L'header di risposta `x-idempotent-replay` vale `true` per una risposta riproposta e `false` per una nuova.
* Se la prima richiesta con quella chiave è ancora in corso, l'API risponde `409 conflict`. Riprova quando è terminata.
* Se riusi una chiave con un corpo della richiesta diverso, l'API risponde `422 unprocessable_entity`.
* Senza l'header, un corpo della richiesta identico inviato entro 30 secondi viene considerato un duplicato.

Le creazioni in blocco usano invece un campo `idempotencyKey` nel corpo della richiesta. Consulta [Creazioni di QR in blocco](https://docs.getqr.com/it/api/endpoints/bulk-qr-creations.md).

## Limiti di frequenza

Ogni chiave API può inviare fino a 600 richieste al minuto. Consulta [Limiti di frequenza](https://docs.getqr.com/it/api/rate-limits.md).

## In arrivo

I pacchetti pronti per la stampa sono previsti in una versione successiva.

## Passaggi successivi

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

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


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