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

# Raportit

> Vie kertaluonteinen skannausraportti tai ajasta toistuvat raporttisähköpostit.

> [!NOTE]
>
> GetQR API on beetavaiheessa, ja se on käytettävissä valituissa työtiloissa. Yksityiskohdat voivat muuttua ennen yleistä julkaisua.

Raportit kokoavat skannaukset QR-koodeittain päättyneeltä päivältä, viikolta tai kuukaudelta. Vie raportti heti tai ajasta raportti, joka lähetetään sähköpostitse säännöllisesti.

| Metodi | Polku | Kuvaus |
| - | - | - |
| `POST` | `/api/v1/reports` | [Vie raportti](#vie-raportti) |
| `GET` | `/api/v1/reports/schedules` | [Listaa ajastetut raportit](#listaa-ajastetut-raportit) |
| `POST` | `/api/v1/reports/schedules` | [Ajasta raportti](#ajasta-raportti) |
| `PATCH` | `/api/v1/reports/schedules/{id}` | [Päivitä ajastettu raportti](#päivitä-ajastettu-raportti) |
| `DELETE` | `/api/v1/reports/schedules/{id}` | [Poista ajastettu raportti](#poista-ajastettu-raportti) |

## Otsakkeet

**Authorization** `string` *required*

`Bearer` ja sen perässä API-avaimesi. Katso [Todennus](https://docs.getqr.com/fi/api/authentication.md).

**Content-Type** `string`

`application/json`. Pakollinen `POST`- ja `PATCH`-pyynnöissä.

## Kattavuus

Sekä kertaluonteiset että ajastetut raportit ottavat kentän `scope`:

| `scope` | Kattaa | `qrIds` |
| - | - | - |
| `all` | Työtilasi QR-koodit | Jätä pois |
| `selected` | Valitut QR-koodit | Yksi tai useampi tunnus |
| `single` | Täsmälleen yksi QR-koodi | Täsmälleen yksi tunnus |

Raportissa on enintään 50 QR-koodia. Arvolla `all` nämä ovat viimeksi luodut aktiiviset QR-koodit; keskeytetyt koodit jätetään pois. Arvoilla `selected` ja `single` keskeytetyt koodit otetaan mukaan. QR-koodeilla, joilla ei ole lyhytlinkkiä, ei ole skannauksia, ja ne ohitetaan.

## Jakso

Jakso on aina viimeisin päättynyt jakso, joten raportti ei koskaan sisällä kuluvan päivän keskeneräisiä tietoja. Sen rajat ovat keskiyöllä raportin aikavyöhykkeellä.

| `period` tai `frequency` | Kattaa |
| - | - |
| `daily` | Edellinen päivä |
| `weekly` | Edellinen viikko maanantaista sunnuntaihin |
| `monthly` | Edellinen kalenterikuukausi |

## Vie raportti

`POST /api/v1/reports`

Muodostaa raportin viimeisimmältä päättyneeltä jaksolta ja palauttaa sen vastauksessa.

**scope** `string` *required*

`all`, `selected` tai `single`. Katso [Kattavuus](#kattavuus).

**period** `string` *required*

`daily`, `weekly` tai `monthly`. Katso [Jakso](#jakso).

**format** `string` *required*

`json` palauttaa raportin vastauksen rungossa. `csv` ja `pdf` palauttavat ladattavan tiedoston.

**qrIds** `string[]`

Mukaan otettavat QR-koodit. Pakollinen arvoille `selected` (yksi tai useampi tunnus) ja `single` (täsmälleen yksi tunnus). Jätä pois arvolla `all`.

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

IANA-aikavyöhyke, jonka mukaan jakson rajat kohdistetaan, esimerkiksi `America/New_York`. Tuntematon aikavyöhyke palauttaa `422`.

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

PDF:n kieli, esimerkiksi `en` tai `de`. Tukematon arvo vaihtuu englanniksi. `csv` ja `json` ohittavat sen.

**name** `string`

PDF:ssä näkyvä otsikko, enintään 40 merkkiä. `csv` ja `json` ohittavat sen.

### JSON-vastaus

**periodStart** `string`

Jakson ensimmäinen päivä, `YYYY-MM-DD`.

**periodEnd** `string`

Jakson jälkeinen ensimmäinen päivä, `YYYY-MM-DD`. Jakso päättyy tämän päivän alussa keskiyöllä.

**qrs** `object[]`

Yksi merkintä QR-koodia kohti.

**properties**

**qrId** `string`

QR-koodin tunnus.

**name** `string`

QR-koodin nimi tai `Untitled QR`.

**type** `string`

QR-koodin tyyppi, esimerkiksi `website`.

**totalScans** `integer`

Skannaukset jaksolla yhteensä.

**uniqueScans** `integer`

Yksilölliset skannaukset jaksolla.

**topGeography** `string`

Maakoodi, josta on eniten skannauksia, tai `—`, jos skannauksia ei ole.

**topDevice** `string`

Laite, jolla on eniten skannauksia, tai `—`.

**topOs** `string`

Käyttöjärjestelmä, jolla on eniten skannauksia, tai `—`.

**topBrowser** `string`

Selain, jolla on eniten skannauksia, tai `—`.

### CSV- ja PDF-vastaukset

Runko on tiedosto. `Content-Disposition` nimeää sen jakson mukaan, esimerkiksi `report-2026-08-10_2026-08-17.csv`. CSV-tiedostossa on yksi rivi QR-koodia kohti, ja sen sarakkeet ovat `QR ID`, `QR name`, `QR type`, `Total scans`, `Unique scans`, `Top geography`, `Top device`, `Top OS` ja `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"
    }
  ]
}
```

## Ajastetun raportin objekti

Ajastettu raportti lähetetään sähköpostitse sen luoneelle tilille keskiyöllä raportin aikavyöhykkeellä.

**id** `string`

Ajastetun raportin tunnus.

**name** `string | null`

Nimi, joka näkyy sähköpostin aiheessa ja hallintapaneelissa.

**frequency** `string`

`daily`, `weekly` tai `monthly`.

**scope** `string`

`all`, `selected` tai `single`.

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

QR-koodit, jotka raportti kattaa arvoilla `selected` ja `single`. `null`, jos tunnuksia ei lähetetty.

**filters** `null`

Aina `null`. Varattu.

**includePdf** `boolean`

Liitetäänkö sähköpostiin PDF.

**status** `string`

`active` tai `paused`.

**timezone** `string`

IANA-aikavyöhyke, jonka mukaan lähetysaika ja jakso kohdistetaan.

**locale** `string`

Sähköpostin ja PDF:n kieli.

**nextRunAt** `string`

Milloin seuraava sähköposti lähtee, ISO 8601: seuraava keskiyö (`daily`), seuraava maanantai (`weekly`) tai seuraavan kuun 1. päivä (`monthly`) raportin aikavyöhykkeellä.

**lastRunAt** `string | null`

Milloin viimeisin sähköposti lähetettiin, ISO 8601.

**createdAt** `string`

Luontipäivä, ISO 8601.

**updatedAt** `string`

Viimeisimmän päivityksen päivä, ISO 8601.

## Listaa ajastetut raportit

`GET /api/v1/reports/schedules`

Palauttaa työtilasi ajastetut raportit, myös muiden jäsenten luomat, uusimmat ensin. Lista on sivutettu: katso [Sivutus](https://docs.getqr.com/fi/api/introduction.md#sivutus).

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

Palautettava sivu, 1 tai suurempi.

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

Tuloksia sivua kohti, 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 }
}
```

## Ajasta raportti

`POST /api/v1/reports/schedules`

Luo raportin, joka lähetetään sähköpostitse säännöllisesti. `nextRunAt` lasketaan toistuvuuden ja aikavyöhykkeen perusteella.

> [!NOTE]
>
> QR-koodi voi kuulua vain yhteen ajastettuun raporttiin kutakin toistuvuutta kohti. Päällekkäinen ajastus palauttaa `409 conflict`.

Raportti, jonka kattavuus on `all`, menee päällekkäin kaikkien muiden saman toistuvuuden raporttien kanssa. Myös keskeytetyt raportit lasketaan.

**frequency** `string` *required*

Kuinka usein raportti lähetetään: `daily`, `weekly` tai `monthly`. Määrittää myös sen kattaman jakson. Katso [Jakso](#jakso).

**scope** `string` *required*

`all`, `selected` tai `single`. Katso [Kattavuus](#kattavuus).

**timezone** `string` *required*

IANA-aikavyöhyke, jonka mukaan lähetysaika ja jakso kohdistetaan, esimerkiksi `America/New_York`. Tuntematon aikavyöhyke palauttaa `422`.

**locale** `string` *required*

Sähköpostin ja PDF:n kieli, esimerkiksi `en` tai `de`. Tukematon arvo vaihtuu englanniksi. PDF-tiedostot kielillä `zh`, `ja`, `ko` ja `ar` muodostetaan englanniksi.

**qrIds** `string[]`

Mukaan otettavat QR-koodit. Pakollinen arvoille `selected` (yksi tai useampi tunnus) ja `single` (täsmälleen yksi tunnus). Jokaisen tunnuksen on oltava työtilasi QR-koodi, muuten pyyntö palauttaa `404`.

**name** `string`

Nimi, joka näkyy sähköpostin aiheessa ja hallintapaneelissa, enintään 40 merkkiä.

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

Liitä sähköpostiin raportin PDF-versio.

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

## Päivitä ajastettu raportti

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

Muuttaa ajastettua raporttia tai keskeyttää ja jatkaa sitä. Lähetä vain ne kentät, joita haluat muuttaa, vähintään yksi. Toistuvuuden tai aikavyöhykkeen muuttaminen tai keskeytetyn raportin jatkaminen laskee `nextRunAt`-arvon uudelleen. Yksi raportti toistuvuutta kohti -sääntö on edelleen voimassa, joten päällekkäinen muutos palauttaa `409`.

**id** `string` *required*

Ajastetun raportin tunnus. Ota se listauksen tai luonnin vastauksesta.

**status** `string`

`paused` pysäyttää sähköpostit poistamatta ajastusta. `active` jatkaa niitä.

**name** `string`

Nimi, enintään 40 merkkiä.

**frequency** `string`

`daily`, `weekly` tai `monthly`.

**scope** `string`

`all`, `selected` tai `single`.

**qrIds** `string[]`

Mukaan otettavat QR-koodit. Jokaisen tunnuksen on oltava työtilasi QR-koodi.

**includePdf** `boolean`

Liitä sähköpostiin PDF.

**timezone** `string`

IANA-aikavyöhyke.

**locale** `string`

Sähköpostin ja PDF:n kieli.

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

## Poista ajastettu raportti

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

Poistaa ajastuksen ja lopettaa kaikki tulevat sähköpostit.

> [!WARNING]
>
> Ajastetun raportin poistoa ei voi perua.

**id** `string` *required*

Ajastetun raportin tunnus.

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

## Yleisiä ongelmia

> [accordion] 404 raporttia vietäessä
>
> Kattavuudella `selected` tai `single` mikään `qrIds`-tunnuksista ei vastannut työtilasi QR-koodia, jolla on lyhytlinkki. Tarkista tunnukset.

> [accordion] 404 "QR not found." raporttia ajastettaessa
>
> Jokin `qrIds`-tunnuksista ei ole työtilasi QR-koodi, tai se on poistettu. Tarkista tunnukset [QR-koodien listauksella](https://docs.getqr.com/fi/api/endpoints/qr-codes.md).

> [accordion] 409 raporttia ajastettaessa
>
> Jokin QR-koodeista kuuluu jo samantoistuvuiseen ajastettuun raporttiin, tai saman toistuvuuden raportti käyttää kattavuutta `all`. Muokkaa tai poista kyseinen raportti tai valitse eri toistuvuus.

> [accordion] 404 "Scheduled report not found."
>
> `id` ei vastaa työtilasi ajastettua raporttia. Ota se kohdasta [Listaa ajastetut raportit](#listaa-ajastetut-raportit).

> [accordion] Raportista puuttuvat tämän päivän skannaukset
>
> Raportit kattavat vain viimeisimmän päättyneen jakson. Käytä [Analytiikkaa](https://docs.getqr.com/fi/api/endpoints/analytics.md) reaaliaikaisiin lukuihin.

## Mitä seuraavaksi

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

> [card] [Ajastetut raportit sovelluksessa](https://docs.getqr.com/fi/analytics/scheduled-reports.md)

> [card] [Raporttien lukeminen](https://docs.getqr.com/fi/analytics/reading-reports.md)

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


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