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

# Reporty

> Exportujte jednorázový report o skenování nebo naplánujte pravidelné e-maily s reporty.

> [!NOTE]
>
> GetQR API je v beta verzi a je dostupné pro vybrané pracovní prostory. Do obecného vydání se podrobnosti mohou změnit.

Reporty shrnují skenování jednotlivých QR kódů za uzavřený den, týden nebo měsíc. Report můžete exportovat hned, nebo naplánovat report, který se bude pravidelně posílat e-mailem.

| Metoda | Cesta | Popis |
| - | - | - |
| `POST` | `/api/v1/reports` | [Export reportu](#export-reportu) |
| `GET` | `/api/v1/reports/schedules` | [Výpis plánovaných reportů](#výpis-plánovaných-reportů) |
| `POST` | `/api/v1/reports/schedules` | [Naplánování reportu](#naplánování-reportu) |
| `PATCH` | `/api/v1/reports/schedules/{id}` | [Úprava plánovaného reportu](#úprava-plánovaného-reportu) |
| `DELETE` | `/api/v1/reports/schedules/{id}` | [Smazání plánovaného reportu](#smazání-plánovaného-reportu) |

## Hlavičky

**Authorization** `string` *required*

`Bearer` následovaný vaším API klíčem. Viz [Ověřování](https://docs.getqr.com/cs/api/authentication.md).

**Content-Type** `string`

`application/json`. Povinné u požadavků `POST` a `PATCH`.

## Rozsah

Jednorázové i plánované reporty přijímají `scope`:

| `scope` | Pokrývá | `qrIds` |
| - | - | - |
| `all` | QR kódy ve vašem pracovním prostoru | Vynechte |
| `selected` | Vybranou skupinu QR kódů | Jedno nebo více ID |
| `single` | Právě jeden QR kód | Právě jedno ID |

Report obsahuje nejvýše 50 QR kódů. S `all` jde o naposledy vytvořené aktivní QR kódy; pozastavené kódy se vynechají. Se `selected` a `single` se pozastavené kódy zahrnou. QR kódy bez krátkého odkazu nemají žádná skenování a přeskočí se.

## Období

Období je vždy poslední uzavřené, takže report nikdy neobsahuje neúplná data dnešního dne. Jeho hranice jsou o půlnoci v časovém pásmu reportu.

| `period` nebo `frequency` | Pokrývá |
| - | - |
| `daily` | Předchozí den |
| `weekly` | Předchozí týden od pondělí do neděle |
| `monthly` | Předchozí kalendářní měsíc |

## Export reportu

`POST /api/v1/reports`

Sestaví report za poslední uzavřené období a vrátí ho v odpovědi.

**scope** `string` *required*

`all`, `selected` nebo `single`. Viz [Rozsah](#rozsah).

**period** `string` *required*

`daily`, `weekly` nebo `monthly`. Viz [Období](#období).

**format** `string` *required*

`json` vrátí report v těle odpovědi. `csv` a `pdf` vrátí soubor ke stažení.

**qrIds** `string[]`

QR kódy, které má report pokrýt. Povinné pro `selected` (jedno nebo více ID) a `single` (právě jedno ID). Pro `all` vynechte.

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

Časové pásmo IANA, podle kterého se řídí hranice období, například `America/New_York`. Neznámé časové pásmo vrátí `422`.

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

Jazyk PDF, například `en` nebo `de`. Nepodporovaná hodnota se nahradí angličtinou. U `csv` a `json` se ignoruje.

**name** `string`

Název zobrazený v PDF, nejvýše 40 znaků. U `csv` a `json` se ignoruje.

### Odpověď JSON

**periodStart** `string`

První den období, `YYYY-MM-DD`.

**periodEnd** `string`

První den po skončení období, `YYYY-MM-DD`. Období končí o půlnoci na začátku tohoto dne.

**qrs** `object[]`

Jedna položka na QR kód.

**properties**

**qrId** `string`

ID QR kódu.

**name** `string`

Název QR kódu, nebo `Untitled QR`.

**type** `string`

Typ QR kódu, například `website`.

**totalScans** `integer`

Celkový počet skenování v období.

**uniqueScans** `integer`

Unikátní skenování v období.

**topGeography** `string`

Kód země s nejvíce skenováními, nebo `—`, pokud skenování nejsou.

**topDevice** `string`

Zařízení s nejvíce skenováními, nebo `—`.

**topOs** `string`

Operační systém s nejvíce skenováními, nebo `—`.

**topBrowser** `string`

Prohlížeč s nejvíce skenováními, nebo `—`.

### Odpovědi CSV a PDF

Tělem je soubor. `Content-Disposition` ho pojmenuje podle období, například `report-2026-08-10_2026-08-17.csv`. CSV má jeden řádek na QR kód se sloupci `QR ID`, `QR name`, `QR type`, `Total scans`, `Unique scans`, `Top geography`, `Top device`, `Top OS` a `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"
    }
  ]
}
```

## Objekt plánovaného reportu

Plánovaný report se posílá e-mailem na účet, který ho vytvořil, o půlnoci v jeho časovém pásmu.

**id** `string`

ID plánovaného reportu.

**name** `string | null`

Popisek zobrazený v předmětu e-mailu a v dashboardu.

**frequency** `string`

`daily`, `weekly` nebo `monthly`.

**scope** `string`

`all`, `selected` nebo `single`.

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

QR kódy, které report pokrývá s rozsahy `selected` a `single`. `null`, pokud nebyla poslána žádná ID.

**filters** `null`

Vždy `null`. Vyhrazeno.

**includePdf** `boolean`

Zda je k e-mailu přiloženo PDF.

**status** `string`

`active` nebo `paused`.

**timezone** `string`

Časové pásmo IANA, podle kterého se řídí čas odeslání a období.

**locale** `string`

Jazyk e-mailu a PDF.

**nextRunAt** `string`

Kdy se má odeslat další e-mail, ISO 8601: příští půlnoc (`daily`), příští pondělí (`weekly`) nebo 1. den příštího měsíce (`monthly`) v časovém pásmu reportu.

**lastRunAt** `string | null`

Kdy byl odeslán poslední e-mail, ISO 8601.

**createdAt** `string`

Datum vytvoření, ISO 8601.

**updatedAt** `string`

Datum poslední úpravy, ISO 8601.

## Výpis plánovaných reportů

`GET /api/v1/reports/schedules`

Vrací plánované reporty vašeho pracovního prostoru, včetně těch, které vytvořili ostatní členové, od nejnovějších. Seznam je stránkovaný: viz [Stránkování](https://docs.getqr.com/cs/api/introduction.md#stránkování).

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

Stránka, která se má vrátit, 1 nebo vyšší.

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

Počet výsledků na stránku, 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 }
}
```

## Naplánování reportu

`POST /api/v1/reports/schedules`

Vytvoří report, který se pravidelně posílá e-mailem. `nextRunAt` se vypočítá z frekvence a časového pásma.

> [!NOTE]
>
> QR kód může patřit jen do jednoho plánovaného reportu na každou frekvenci. Překrývající se plán vrátí `409 conflict`.

Report s rozsahem `all` se překrývá se všemi ostatními reporty se stejnou frekvencí. Počítají se i pozastavené reporty.

**frequency** `string` *required*

Jak často se report posílá: `daily`, `weekly` nebo `monthly`. Určuje také období, které pokrývá. Viz [Období](#období).

**scope** `string` *required*

`all`, `selected` nebo `single`. Viz [Rozsah](#rozsah).

**timezone** `string` *required*

Časové pásmo IANA, podle kterého se řídí čas odeslání a období, například `America/New_York`. Neznámé časové pásmo vrátí `422`.

**locale** `string` *required*

Jazyk e-mailu a PDF, například `en` nebo `de`. Nepodporovaná hodnota se nahradí angličtinou. PDF v jazycích `zh`, `ja`, `ko` a `ar` se vykreslí anglicky.

**qrIds** `string[]`

QR kódy, které má report pokrýt. Povinné pro `selected` (jedno nebo více ID) a `single` (právě jedno ID). Každé ID musí patřit QR kódu ve vašem pracovním prostoru, jinak požadavek vrátí `404`.

**name** `string`

Popisek zobrazený v předmětu e-mailu a v dashboardu, nejvýše 40 znaků.

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

Přiloží k e-mailu verzi reportu v PDF.

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

## Úprava plánovaného reportu

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

Změní plánovaný report, nebo ho pozastaví a obnoví. Pošlete jen pole, která chcete změnit, alespoň jedno. Změna frekvence nebo časového pásma a obnovení pozastaveného reportu přepočítají `nextRunAt`. Pravidlo jednoho reportu na frekvenci stále platí, takže překrývající se změna vrátí `409`.

**id** `string` *required*

ID plánovaného reportu. Najdete ho v odpovědi výpisu nebo vytvoření.

**status** `string`

`paused` zastaví e-maily, aniž by smazal plán. `active` je obnoví.

**name** `string`

Popisek, nejvýše 40 znaků.

**frequency** `string`

`daily`, `weekly` nebo `monthly`.

**scope** `string`

`all`, `selected` nebo `single`.

**qrIds** `string[]`

QR kódy, které má report pokrýt. Každé ID musí patřit QR kódu ve vašem pracovním prostoru.

**includePdf** `boolean`

Přiloží k e-mailu PDF.

**timezone** `string`

Časové pásmo IANA.

**locale** `string`

Jazyk e-mailu a 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"
}
```

## Smazání plánovaného reportu

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

Smaže plán a zastaví všechny další e-maily.

> [!WARNING]
>
> Smazání plánovaného reportu nelze vrátit zpět.

**id** `string` *required*

ID plánovaného reportu.

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

## Časté problémy

> [accordion] 404 při exportu reportu
>
> S rozsahem `selected` nebo `single` neodpovídalo žádné z `qrIds` QR kódu s krátkým odkazem ve vašem pracovním prostoru. Zkontrolujte ID.

> [accordion] 404 "QR not found." při plánování reportu
>
> Některé z `qrIds` nepatří QR kódu ve vašem pracovním prostoru, nebo byl kód smazán. Zkontrolujte ID pomocí [výpisu QR kódů](https://docs.getqr.com/cs/api/endpoints/qr-codes.md).

> [accordion] 409 při plánování reportu
>
> Některý z QR kódů už patří do plánovaného reportu se stejnou frekvencí, nebo report s touto frekvencí používá rozsah `all`. Upravte nebo smažte tento report, nebo zvolte jinou frekvenci.

> [accordion] 404 "Scheduled report not found."
>
> `id` neodpovídá žádnému plánovanému reportu ve vašem pracovním prostoru. Převezměte ho z [výpisu plánovaných reportů](#výpis-plánovaných-reportů).

> [accordion] V reportu chybí dnešní skenování
>
> Reporty pokrývají jen poslední uzavřené období. Pro aktuální čísla použijte [Analytiku](https://docs.getqr.com/cs/api/endpoints/analytics.md).

## Co dál

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

> [card] [Plánované přehledy v aplikaci](https://docs.getqr.com/cs/analytics/scheduled-reports.md)

> [card] [Čtení přehledů](https://docs.getqr.com/cs/analytics/reading-reports.md)

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


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