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

# Report

> Esporta un report delle scansioni una tantum o pianifica l'invio periodico di report via email.

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

I report riepilogano le scansioni per ogni QR code relative a un giorno, una settimana o un mese concluso. Esportane uno subito, oppure pianifica un report da ricevere via email a intervalli regolari.

| Metodo | Percorso | Descrizione |
| - | - | - |
| `POST` | `/api/v1/reports` | [Esporta un report](#esporta-un-report) |
| `GET` | `/api/v1/reports/schedules` | [Elenca i report programmati](#elenca-i-report-programmati) |
| `POST` | `/api/v1/reports/schedules` | [Pianifica un report](#pianifica-un-report) |
| `PATCH` | `/api/v1/reports/schedules/{id}` | [Aggiorna un report programmato](#aggiorna-un-report-programmato) |
| `DELETE` | `/api/v1/reports/schedules/{id}` | [Elimina un report programmato](#elimina-un-report-programmato) |

## Header

**Authorization** `string` *required*

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

**Content-Type** `string`

`application/json`. Obbligatorio nelle richieste `POST` e `PATCH`.

## Ambito

Sia i report una tantum sia quelli programmati accettano uno `scope`:

| `scope` | Copre | `qrIds` |
| - | - | - |
| `all` | I QR code del tuo workspace | Ometti |
| `selected` | Un insieme di QR code scelti | Uno o più ID |
| `single` | Esattamente un QR code | Esattamente un ID |

Un report elenca al massimo 50 QR code. Con `all`, sono i QR code attivi creati più di recente; i codici in pausa sono esclusi. Con `selected` e `single`, i codici in pausa sono inclusi. I QR code senza link breve non hanno scansioni e vengono saltati.

## Periodo

Il periodo è sempre l'ultimo concluso, quindi un report non include mai i dati parziali di oggi. I suoi limiti sono la mezzanotte nel fuso orario del report.

| `period` o `frequency` | Copre |
| - | - |
| `daily` | Il giorno precedente |
| `weekly` | La settimana precedente, da lunedì a domenica |
| `monthly` | Il mese solare precedente |

## Esporta un report

`POST /api/v1/reports`

Genera un report per l'ultimo periodo concluso e lo restituisce nella risposta.

**scope** `string` *required*

`all`, `selected` o `single`. Consulta [Ambito](#ambito).

**period** `string` *required*

`daily`, `weekly` o `monthly`. Consulta [Periodo](#periodo).

**format** `string` *required*

`json` restituisce il report nel corpo della risposta. `csv` e `pdf` restituiscono un file da scaricare.

**qrIds** `string[]`

QR code da includere. Obbligatorio per `selected` (uno o più ID) e `single` (esattamente un ID). Omettilo per `all`.

**timezone** `string` (default: UTC)

Fuso orario IANA a cui sono allineati i limiti del periodo, ad esempio `America/New_York`. Un fuso orario sconosciuto restituisce `422`.

**locale** `string` (default: en)

Lingua del PDF, ad esempio `en` o `de`. Un valore non supportato torna all'inglese. Ignorato da `csv` e `json`.

**name** `string`

Titolo mostrato sul PDF, fino a 40 caratteri. Ignorato da `csv` e `json`.

### Risposta JSON

**periodStart** `string`

Primo giorno del periodo, `YYYY-MM-DD`.

**periodEnd** `string`

Primo giorno dopo il periodo, `YYYY-MM-DD`. Il periodo termina alla mezzanotte all'inizio di questo giorno.

**qrs** `object[]`

Una voce per ogni QR code.

**properties**

**qrId** `string`

ID del QR code.

**name** `string`

Titolo del QR code, oppure `Untitled QR`.

**type** `string`

Tipo di QR code, ad esempio `website`.

**totalScans** `integer`

Scansioni totali nel periodo.

**uniqueScans** `integer`

Scansioni uniche nel periodo.

**topGeography** `string`

Codice del paese con più scansioni, oppure `—` senza scansioni.

**topDevice** `string`

Dispositivo con più scansioni, oppure `—`.

**topOs** `string`

Sistema operativo con più scansioni, oppure `—`.

**topBrowser** `string`

Browser con più scansioni, oppure `—`.

### Risposte CSV e PDF

Il corpo è il file. `Content-Disposition` gli dà un nome basato sul periodo, ad esempio `report-2026-08-10_2026-08-17.csv`. Il CSV ha una riga per QR code con le colonne `QR ID`, `QR name`, `QR type`, `Total scans`, `Unique scans`, `Top geography`, `Top device`, `Top OS` e `Top browser`.

```bash JSON theme={null}
curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "period": "weekly",
    "format": "json",
    "timezone": "America/New_York"
  }'
```

```bash PDF theme={null}
curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "all", "period": "monthly", "format": "pdf", "locale": "de" }' \
  --output report.pdf
```

```json 200 theme={null}
{
  "periodStart": "2026-08-10",
  "periodEnd": "2026-08-17",
  "qrs": [
    {
      "qrId": "clw3n7t1x0002ab0d5mqe8pkr",
      "name": "Landing page",
      "type": "website",
      "totalScans": 128,
      "uniqueScans": 96,
      "topGeography": "US",
      "topDevice": "Mobile",
      "topOs": "iOS",
      "topBrowser": "Safari"
    }
  ]
}
```

## L'oggetto report programmato

Un report programmato viene inviato via email all'account che lo ha creato, a mezzanotte nel suo fuso orario.

**id** `string`

ID del report programmato.

**name** `string | null`

Etichetta mostrata nell'oggetto dell'email e nella dashboard.

**frequency** `string`

`daily`, `weekly` o `monthly`.

**scope** `string`

`all`, `selected` o `single`.

**qrIds** `string[] | null`

QR code inclusi nel report con gli ambiti `selected` e `single`. `null` se non sono stati inviati ID.

**filters** `null`

Sempre `null`. Riservato.

**includePdf** `boolean`

Indica se all'email è allegato un PDF.

**status** `string`

`active` o `paused`.

**timezone** `string`

Fuso orario IANA a cui sono allineati l'orario di invio e il periodo.

**locale** `string`

Lingua dell'email e del PDF.

**nextRunAt** `string`

Quando è previsto il prossimo invio, ISO 8601: la prossima mezzanotte (`daily`), il prossimo lunedì (`weekly`) o il 1° del mese successivo (`monthly`), nel fuso orario del report.

**lastRunAt** `string | null`

Quando è stata inviata l'ultima email, ISO 8601.

**createdAt** `string`

Data di creazione, ISO 8601.

**updatedAt** `string`

Data dell'ultimo aggiornamento, ISO 8601.

## Elenca i report programmati

`GET /api/v1/reports/schedules`

Restituisce i report programmati del tuo workspace, compresi quelli creati da altri membri, dal più recente. L'elenco è paginato: consulta [Paginazione](https://docs.getqr.com/it/api/introduction.md#paginazione).

**page** `integer` (default: 1)

Pagina da restituire, 1 o superiore.

**pageSize** `integer` (default: 100)

Risultati per pagina, da 1 a 100.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/reports/schedules?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "clx8f2k9a0001qk0c8vhd3xyz",
      "name": "Weekly campaign digest",
      "frequency": "weekly",
      "scope": "selected",
      "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr", "clw3n7t1x0004ab0d9rzu2wfh"],
      "filters": null,
      "includePdf": true,
      "status": "active",
      "timezone": "America/New_York",
      "locale": "en",
      "nextRunAt": "2026-08-10T04:00:00.000Z",
      "lastRunAt": "2026-08-03T04:00:12.000Z",
      "createdAt": "2026-07-01T12:34:56.000Z",
      "updatedAt": "2026-07-28T09:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}
```

## Pianifica un report

`POST /api/v1/reports/schedules`

Crea un report che viene inviato via email a intervalli regolari. `nextRunAt` viene calcolato in base alla frequenza e al fuso orario.

> [!NOTE]
>
> Un QR code può appartenere a un solo report programmato per frequenza. Una pianificazione sovrapposta restituisce `409 conflict`.

Un report con ambito `all` si sovrappone a tutti gli altri report con la stessa frequenza. Anche i report in pausa contano.

**frequency** `string` *required*

Ogni quanto viene inviato il report: `daily`, `weekly` o `monthly`. Stabilisce anche il periodo coperto. Consulta [Periodo](#periodo).

**scope** `string` *required*

`all`, `selected` o `single`. Consulta [Ambito](#ambito).

**timezone** `string` *required*

Fuso orario IANA a cui sono allineati l'orario di invio e il periodo, ad esempio `America/New_York`. Un fuso orario sconosciuto restituisce `422`.

**locale** `string` *required*

Lingua dell'email e del PDF, ad esempio `en` o `de`. Un valore non supportato torna all'inglese. I PDF in `zh`, `ja`, `ko` e `ar` vengono generati in inglese.

**qrIds** `string[]`

QR code da includere. Obbligatorio per `selected` (uno o più ID) e `single` (esattamente un ID). Ogni ID deve corrispondere a un QR code del tuo workspace, altrimenti la richiesta restituisce `404`.

**name** `string`

Etichetta mostrata nell'oggetto dell'email e nella dashboard, fino a 40 caratteri.

**includePdf** `boolean` (default: false)

Allega all'email una versione PDF del report.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/reports/schedules" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly campaign digest",
    "frequency": "weekly",
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "includePdf": true,
    "timezone": "America/New_York",
    "locale": "en"
  }'
```

```json 200 theme={null}
{
  "id": "clx8f2k9a0001qk0c8vhd3xyz",
  "name": "Weekly campaign digest",
  "frequency": "weekly",
  "scope": "selected",
  "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
  "filters": null,
  "includePdf": true,
  "status": "active",
  "timezone": "America/New_York",
  "locale": "en",
  "nextRunAt": "2026-08-10T04:00:00.000Z",
  "lastRunAt": null,
  "createdAt": "2026-08-03T12:34:56.000Z",
  "updatedAt": "2026-08-03T12:34:56.000Z"
}
```

## Aggiorna un report programmato

`PATCH /api/v1/reports/schedules/{id}`

Modifica un report programmato, oppure lo mette in pausa e lo riprende. Invia solo i campi che vuoi modificare, almeno uno. Cambiare la frequenza o il fuso orario, oppure riprendere un report in pausa, ricalcola `nextRunAt`. La regola di un report per frequenza resta valida, quindi una modifica che crea una sovrapposizione restituisce `409`.

**id** `string` *required*

ID del report programmato. Prendilo dalla risposta dell'elenco o della creazione.

**status** `string`

`paused` interrompe le email senza eliminare la pianificazione. `active` le riprende.

**name** `string`

Etichetta, fino a 40 caratteri.

**frequency** `string`

`daily`, `weekly` o `monthly`.

**scope** `string`

`all`, `selected` o `single`.

**qrIds** `string[]`

QR code da includere. Ogni ID deve corrispondere a un QR code del tuo workspace.

**includePdf** `boolean`

Allega un PDF all'email.

**timezone** `string`

Fuso orario IANA.

**locale** `string`

Lingua dell'email e del PDF.

```bash cURL theme={null}
curl -X PATCH "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly campaign digest",
    "frequency": "monthly",
    "status": "active"
  }'
```

```json 200 theme={null}
{
  "id": "clx8f2k9a0001qk0c8vhd3xyz",
  "name": "Monthly campaign digest",
  "frequency": "monthly",
  "scope": "selected",
  "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
  "filters": null,
  "includePdf": true,
  "status": "active",
  "timezone": "America/New_York",
  "locale": "en",
  "nextRunAt": "2026-09-01T04:00:00.000Z",
  "lastRunAt": "2026-08-03T04:00:12.000Z",
  "createdAt": "2026-07-01T12:34:56.000Z",
  "updatedAt": "2026-08-05T10:15:00.000Z"
}
```

## Elimina un report programmato

`DELETE /api/v1/reports/schedules/{id}`

Elimina la pianificazione e interrompe tutti gli invii successivi.

> [!WARNING]
>
> L'eliminazione di un report programmato non può essere annullata.

**id** `string` *required*

ID del report programmato.

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{ "id": "clx8f2k9a0001qk0c8vhd3xyz", "deleted": true }
```

## Problemi comuni

> [accordion] 404 durante l'esportazione di un report
>
> Con l'ambito `selected` o `single`, nessuno dei `qrIds` corrisponde a un QR code con link breve nel tuo workspace. Controlla gli ID.

> [accordion] 404 "QR not found." durante la pianificazione di un report
>
> Uno dei `qrIds` non è un QR code del tuo workspace, oppure è stato eliminato. Controlla gli ID con [Elenca i QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md).

> [accordion] 409 durante la pianificazione di un report
>
> Uno dei QR code appartiene già a un report programmato con la stessa frequenza, oppure un report con quella frequenza usa l'ambito `all`. Modifica o elimina quel report, oppure scegli una frequenza diversa.

> [accordion] 404 "Scheduled report not found."
>
> L'`id` non corrisponde a un report programmato del tuo workspace. Prendilo da [Elenca i report programmati](#elenca-i-report-programmati).

> [accordion] Nel report mancano le scansioni di oggi
>
> I report coprono solo l'ultimo periodo concluso. Usa [Statistiche](https://docs.getqr.com/it/api/endpoints/analytics.md) per i dati in tempo reale.

## Passaggi successivi

> [card] [Statistiche](https://docs.getqr.com/it/api/endpoints/analytics.md)

> [card] [Report programmati nell'app](https://docs.getqr.com/it/analytics/scheduled-reports.md)

> [card] [Leggere i report](https://docs.getqr.com/it/analytics/reading-reports.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.