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

# Rapports

> Exportez un rapport de scans ponctuel ou programmez l'envoi régulier de rapports par e-mail.

> [!NOTE]
>
> L'API GetQR est en version bêta et réservée à certains espaces de travail. Certains détails peuvent changer avant la disponibilité générale.

Les rapports résument les scans par QR code pour un jour, une semaine ou un mois terminé. Exportez-en un immédiatement, ou programmez un rapport envoyé régulièrement par e-mail.

| Méthode | Chemin | Description |
| - | - | - |
| `POST` | `/api/v1/reports` | [Exporter un rapport](#exporter-un-rapport) |
| `GET` | `/api/v1/reports/schedules` | [Lister les rapports programmés](#lister-les-rapports-programmés) |
| `POST` | `/api/v1/reports/schedules` | [Programmer un rapport](#programmer-un-rapport) |
| `PATCH` | `/api/v1/reports/schedules/{id}` | [Modifier un rapport programmé](#modifier-un-rapport-programmé) |
| `DELETE` | `/api/v1/reports/schedules/{id}` | [Supprimer un rapport programmé](#supprimer-un-rapport-programmé) |

## En-têtes

**Authorization** `string` *required*

`Bearer` suivi de votre clé API. Consultez [Authentification](https://docs.getqr.com/fr/api/authentication.md).

**Content-Type** `string`

`application/json`. Obligatoire pour les requêtes `POST` et `PATCH`.

## Périmètre

Les rapports ponctuels et programmés acceptent tous deux un `scope` :

| `scope` | Périmètre | `qrIds` |
| - | - | - |
| `all` | Les QR codes de votre espace de travail | À omettre |
| `selected` | Un ensemble choisi de QR codes | Un ou plusieurs ID |
| `single` | Un seul QR code | Exactement un ID |

Un rapport liste au maximum 50 QR codes. Avec `all`, il s'agit des QR codes actifs les plus récemment créés ; les codes en pause sont exclus. Avec `selected` et `single`, les codes en pause sont inclus. Les QR codes sans lien court n'ont pas de scans et sont ignorés.

## Période

La période est toujours la dernière période terminée : un rapport n'inclut donc jamais les données partielles du jour. Ses limites sont à minuit dans le fuseau horaire du rapport.

| `period` ou `frequency` | Période couverte |
| - | - |
| `daily` | La veille |
| `weekly` | La semaine précédente, du lundi au dimanche |
| `monthly` | Le mois civil précédent |

## Exporter un rapport

`POST /api/v1/reports`

Génère un rapport pour la dernière période terminée et le renvoie dans la réponse.

**scope** `string` *required*

`all`, `selected` ou `single`. Consultez [Périmètre](#périmètre).

**period** `string` *required*

`daily`, `weekly` ou `monthly`. Consultez [Période](#période).

**format** `string` *required*

`json` renvoie le rapport dans le corps de la réponse. `csv` et `pdf` renvoient un fichier à télécharger.

**qrIds** `string[]`

QR codes à couvrir. Obligatoire pour `selected` (un ou plusieurs ID) et `single` (exactement un ID). À omettre pour `all`.

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

Fuseau horaire IANA sur lequel les limites de la période sont alignées, par exemple `America/New_York`. Un fuseau horaire inconnu renvoie `422`.

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

Langue du PDF, par exemple `en` ou `de`. Une valeur non prise en charge bascule sur l'anglais. Ignoré par `csv` et `json`.

**name** `string`

Titre affiché sur le PDF, jusqu'à 40 caractères. Ignoré par `csv` et `json`.

### Réponse JSON

**periodStart** `string`

Premier jour de la période, `YYYY-MM-DD`.

**periodEnd** `string`

Premier jour après la période, `YYYY-MM-DD`. La période se termine à minuit, au début de ce jour.

**qrs** `object[]`

Une entrée par QR code.

**properties**

**qrId** `string`

ID du QR code.

**name** `string`

Titre du QR code, ou `Untitled QR`.

**type** `string`

Type du QR code, par exemple `website`.

**totalScans** `integer`

Total des scans sur la période.

**uniqueScans** `integer`

Scans uniques sur la période.

**topGeography** `string`

Code du pays avec le plus de scans, ou `—` en l'absence de scans.

**topDevice** `string`

Appareil avec le plus de scans, ou `—`.

**topOs** `string`

Système d'exploitation avec le plus de scans, ou `—`.

**topBrowser** `string`

Navigateur avec le plus de scans, ou `—`.

### Réponses CSV et PDF

Le corps est le fichier. `Content-Disposition` le nomme d'après la période, par exemple `report-2026-08-10_2026-08-17.csv`. Le CSV contient une ligne par QR code avec les colonnes `QR ID`, `QR name`, `QR type`, `Total scans`, `Unique scans`, `Top geography`, `Top device`, `Top OS` et `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'objet rapport programmé

Un rapport programmé est envoyé par e-mail au compte qui l'a créé, à minuit dans son fuseau horaire.

**id** `string`

ID du rapport programmé.

**name** `string | null`

Libellé affiché dans l'objet de l'e-mail et dans le tableau de bord.

**frequency** `string`

`daily`, `weekly` ou `monthly`.

**scope** `string`

`all`, `selected` ou `single`.

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

QR codes couverts par le rapport avec les périmètres `selected` et `single`. `null` si aucun ID n'a été envoyé.

**filters** `null`

Toujours `null`. Réservé.

**includePdf** `boolean`

Indique si un PDF est joint à l'e-mail.

**status** `string`

`active` ou `paused`.

**timezone** `string`

Fuseau horaire IANA sur lequel l'heure d'envoi et la période sont alignées.

**locale** `string`

Langue de l'e-mail et du PDF.

**nextRunAt** `string`

Date du prochain envoi, ISO 8601 : le prochain minuit (`daily`), le lundi suivant (`weekly`) ou le 1er du mois suivant (`monthly`), dans le fuseau horaire du rapport.

**lastRunAt** `string | null`

Date du dernier envoi, ISO 8601.

**createdAt** `string`

Date de création, ISO 8601.

**updatedAt** `string`

Date de dernière mise à jour, ISO 8601.

## Lister les rapports programmés

`GET /api/v1/reports/schedules`

Renvoie les rapports programmés de votre espace de travail, y compris ceux créés par d'autres membres, du plus récent au plus ancien. La liste est paginée : consultez [Pagination](https://docs.getqr.com/fr/api/introduction.md#pagination).

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

Page à renvoyer, 1 ou plus.

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

Résultats par page, de 1 à 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 }
}
```

## Programmer un rapport

`POST /api/v1/reports/schedules`

Crée un rapport envoyé régulièrement par e-mail. `nextRunAt` est calculé à partir de la fréquence et du fuseau horaire.

> [!NOTE]
>
> Un QR code ne peut appartenir qu'à un seul rapport programmé par fréquence. Une programmation qui en chevauche une autre renvoie `409 conflict`.

Un rapport avec le périmètre `all` chevauche tous les autres rapports de même fréquence. Les rapports en pause comptent aussi.

**frequency** `string` *required*

Fréquence d'envoi du rapport : `daily`, `weekly` ou `monthly`. Détermine aussi la période couverte. Consultez [Période](#période).

**scope** `string` *required*

`all`, `selected` ou `single`. Consultez [Périmètre](#périmètre).

**timezone** `string` *required*

Fuseau horaire IANA sur lequel l'heure d'envoi et la période sont alignées, par exemple `America/New_York`. Un fuseau horaire inconnu renvoie `422`.

**locale** `string` *required*

Langue de l'e-mail et du PDF, par exemple `en` ou `de`. Une valeur non prise en charge bascule sur l'anglais. Les PDF en `zh`, `ja`, `ko` et `ar` sont générés en anglais.

**qrIds** `string[]`

QR codes à couvrir. Obligatoire pour `selected` (un ou plusieurs ID) et `single` (exactement un ID). Chaque ID doit correspondre à un QR code de votre espace de travail, sinon la requête renvoie `404`.

**name** `string`

Libellé affiché dans l'objet de l'e-mail et dans le tableau de bord, jusqu'à 40 caractères.

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

Joindre une version PDF du rapport à l'e-mail.

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

## Modifier un rapport programmé

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

Modifie un rapport programmé, ou le met en pause et le reprend. N'envoyez que les champs à modifier, au moins un. Changer la fréquence ou le fuseau horaire, ou reprendre un rapport en pause, recalcule `nextRunAt`. La règle d'un rapport par fréquence s'applique toujours : une modification qui crée un chevauchement renvoie donc `409`.

**id** `string` *required*

ID du rapport programmé. Récupérez-le dans la réponse de liste ou de création.

**status** `string`

`paused` arrête les e-mails sans supprimer la programmation. `active` les reprend.

**name** `string`

Libellé, jusqu'à 40 caractères.

**frequency** `string`

`daily`, `weekly` ou `monthly`.

**scope** `string`

`all`, `selected` ou `single`.

**qrIds** `string[]`

QR codes à couvrir. Chaque ID doit correspondre à un QR code de votre espace de travail.

**includePdf** `boolean`

Joindre un PDF à l'e-mail.

**timezone** `string`

Fuseau horaire IANA.

**locale** `string`

Langue de l'e-mail et du 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"
}
```

## Supprimer un rapport programmé

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

Supprime la programmation et arrête tous les envois suivants.

> [!WARNING]
>
> La suppression d'un rapport programmé est irréversible.

**id** `string` *required*

ID du rapport programmé.

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

## Problèmes courants

> [accordion] 404 lors de l'export d'un rapport
>
> Avec le périmètre `selected` ou `single`, aucun des `qrIds` ne correspond à un QR code avec lien court dans votre espace de travail. Vérifiez les ID.

> [accordion] 404 « QR not found. » lors de la programmation d'un rapport
>
> L'un des `qrIds` n'est pas un QR code de votre espace de travail, ou il a été supprimé. Vérifiez les ID avec [Lister les QR codes](https://docs.getqr.com/fr/api/endpoints/qr-codes.md).

> [accordion] 409 lors de la programmation d'un rapport
>
> L'un des QR codes appartient déjà à un rapport programmé de même fréquence, ou un rapport de cette fréquence utilise le périmètre `all`. Modifiez ou supprimez ce rapport, ou choisissez une autre fréquence.

> [accordion] 404 "Scheduled report not found."
>
> L'`id` ne correspond à aucun rapport programmé de votre espace de travail. Récupérez-le avec [Lister les rapports programmés](#lister-les-rapports-programmés).

> [accordion] Il manque les scans du jour dans le rapport
>
> Les rapports ne couvrent que la dernière période terminée. Utilisez [Statistiques](https://docs.getqr.com/fr/api/endpoints/analytics.md) pour les chiffres en temps réel.

## Et ensuite

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

> [card] [Rapports programmés dans l'application](https://docs.getqr.com/fr/analytics/scheduled-reports.md)

> [card] [Lire vos rapports](https://docs.getqr.com/fr/analytics/reading-reports.md)

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


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