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

# Raporty

> Eksportuj jednorazowy raport skanowań lub zaplanuj cykliczne raporty e-mailem.

> [!NOTE]
>
> API GetQR jest w wersji beta i jest dostępne dla wybranych obszarów roboczych. Szczegóły mogą się zmienić przed ogólną premierą.

Raporty podsumowują skanowania każdego kodu QR za zakończony dzień, tydzień lub miesiąc. Wyeksportuj raport od razu albo zaplanuj raport wysyłany regularnie e-mailem.

| Metoda | Ścieżka | Opis |
| - | - | - |
| `POST` | `/api/v1/reports` | [Eksport raportu](#eksport-raportu) |
| `GET` | `/api/v1/reports/schedules` | [Lista zaplanowanych raportów](#lista-zaplanowanych-raportów) |
| `POST` | `/api/v1/reports/schedules` | [Planowanie raportu](#planowanie-raportu) |
| `PATCH` | `/api/v1/reports/schedules/{id}` | [Aktualizacja zaplanowanego raportu](#aktualizacja-zaplanowanego-raportu) |
| `DELETE` | `/api/v1/reports/schedules/{id}` | [Usuwanie zaplanowanego raportu](#usuwanie-zaplanowanego-raportu) |

## Nagłówki

**Authorization** `string` *required*

`Bearer`, a po nim Twój klucz API. Zobacz [Uwierzytelnianie](https://docs.getqr.com/pl/api/authentication.md).

**Content-Type** `string`

`application/json`. Wymagany w żądaniach `POST` i `PATCH`.

## Zakres

Raporty jednorazowe i zaplanowane przyjmują `scope`:

| `scope` | Obejmuje | `qrIds` |
| - | - | - |
| `all` | Kody QR w Twoim obszarze roboczym | Pomiń |
| `selected` | Wybrany zestaw kodów QR | Co najmniej jedno ID |
| `single` | Dokładnie jeden kod QR | Dokładnie jedno ID |

Raport obejmuje najwyżej 50 kodów QR. Przy `all` są to ostatnio utworzone aktywne kody QR, a wstrzymane kody są pomijane. Przy `selected` i `single` wstrzymane kody są uwzględniane. Kody QR bez krótkiego linku nie mają skanowań i są pomijane.

## Okres

Okres jest zawsze ostatnim zakończonym okresem, więc raport nigdy nie zawiera niepełnych danych z dzisiejszego dnia. Jego granice to północ w strefie czasowej raportu.

| `period` lub `frequency` | Obejmuje |
| - | - |
| `daily` | Poprzedni dzień |
| `weekly` | Poprzedni tydzień, od poniedziałku do niedzieli |
| `monthly` | Poprzedni miesiąc kalendarzowy |

## Eksport raportu

`POST /api/v1/reports`

Tworzy raport za ostatni zakończony okres i zwraca go w odpowiedzi.

**scope** `string` *required*

`all`, `selected` lub `single`. Zobacz [Zakres](#zakres).

**period** `string` *required*

`daily`, `weekly` lub `monthly`. Zobacz [Okres](#okres).

**format** `string` *required*

`json` zwraca raport w treści odpowiedzi. `csv` i `pdf` zwracają plik do pobrania.

**qrIds** `string[]`

Kody QR do objęcia raportem. Wymagane dla `selected` (co najmniej jedno ID) i `single` (dokładnie jedno ID). Pomiń je przy `all`.

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

Strefa czasowa IANA, do której wyrównywane są granice okresu, np. `America/New_York`. Nieznana strefa czasowa zwraca `422`.

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

Język pliku PDF, np. `en` lub `de`. Nieobsługiwana wartość powoduje użycie angielskiego. Ignorowany przez `csv` i `json`.

**name** `string`

Tytuł wyświetlany w pliku PDF, do 40 znaków. Ignorowany przez `csv` i `json`.

### Odpowiedź JSON

**periodStart** `string`

Pierwszy dzień okresu, `YYYY-MM-DD`.

**periodEnd** `string`

Pierwszy dzień po okresie, `YYYY-MM-DD`. Okres kończy się o północy na początku tego dnia.

**qrs** `object[]`

Jeden wpis na kod QR.

**properties**

**qrId** `string`

ID kodu QR.

**name** `string`

Tytuł kodu QR lub `Untitled QR`.

**type** `string`

Typ kodu QR, np. `website`.

**totalScans** `integer`

Łączna liczba skanowań w okresie.

**uniqueScans** `integer`

Liczba unikalnych skanowań w okresie.

**topGeography** `string`

Kod kraju z największą liczbą skanowań lub `—`, gdy nie ma skanowań.

**topDevice** `string`

Urządzenie z największą liczbą skanowań lub `—`.

**topOs** `string`

System operacyjny z największą liczbą skanowań lub `—`.

**topBrowser** `string`

Przeglądarka z największą liczbą skanowań lub `—`.

### Odpowiedzi CSV i PDF

Treścią odpowiedzi jest plik. Nagłówek `Content-Disposition` nadaje mu nazwę od okresu, np. `report-2026-08-10_2026-08-17.csv`. Plik CSV ma jeden wiersz na kod QR z kolumnami `QR ID`, `QR name`, `QR type`, `Total scans`, `Unique scans`, `Top geography`, `Top device`, `Top OS` i `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"
    }
  ]
}
```

## Obiekt zaplanowanego raportu

Zaplanowany raport jest wysyłany e-mailem na konto, które go utworzyło, o północy w jego strefie czasowej.

**id** `string`

ID zaplanowanego raportu.

**name** `string | null`

Etykieta wyświetlana w temacie e-maila i w panelu.

**frequency** `string`

`daily`, `weekly` lub `monthly`.

**scope** `string`

`all`, `selected` lub `single`.

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

Kody QR objęte raportem przy zakresach `selected` i `single`. `null`, gdy nie wysłano żadnych ID.

**filters** `null`

Zawsze `null`. Zarezerwowane.

**includePdf** `boolean`

Czy do e-maila jest dołączany plik PDF.

**status** `string`

`active` lub `paused`.

**timezone** `string`

Strefa czasowa IANA, do której wyrównywane są godzina wysyłki i okres.

**locale** `string`

Język e-maila i pliku PDF.

**nextRunAt** `string`

Termin następnego e-maila, ISO 8601: najbliższa północ (`daily`), najbliższy poniedziałek (`weekly`) lub 1. dzień następnego miesiąca (`monthly`), w strefie czasowej raportu.

**lastRunAt** `string | null`

Kiedy wysłano ostatni e-mail, ISO 8601.

**createdAt** `string`

Data utworzenia, ISO 8601.

**updatedAt** `string`

Data ostatniej aktualizacji, ISO 8601.

## Lista zaplanowanych raportów

`GET /api/v1/reports/schedules`

Zwraca zaplanowane raporty Twojego obszaru roboczego, w tym utworzone przez innych członków, od najnowszych. Lista jest paginowana: zobacz [Paginacja](https://docs.getqr.com/pl/api/introduction.md#paginacja).

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

Strona do zwrócenia, 1 lub więcej.

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

Liczba wyników na stronę, od 1 do 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 }
}
```

## Planowanie raportu

`POST /api/v1/reports/schedules`

Tworzy raport wysyłany regularnie e-mailem. `nextRunAt` jest wyliczane na podstawie częstotliwości i strefy czasowej.

> [!NOTE]
>
> Kod QR może należeć tylko do jednego zaplanowanego raportu o danej częstotliwości. Nakładający się harmonogram zwraca `409 conflict`.

Raport z zakresem `all` nakłada się na każdy inny raport o tej samej częstotliwości. Wstrzymane raporty też się liczą.

**frequency** `string` *required*

Jak często raport jest wysyłany: `daily`, `weekly` lub `monthly`. Określa też okres, który obejmuje. Zobacz [Okres](#okres).

**scope** `string` *required*

`all`, `selected` lub `single`. Zobacz [Zakres](#zakres).

**timezone** `string` *required*

Strefa czasowa IANA, do której wyrównywane są godzina wysyłki i okres, np. `America/New_York`. Nieznana strefa czasowa zwraca `422`.

**locale** `string` *required*

Język e-maila i pliku PDF, np. `en` lub `de`. Nieobsługiwana wartość powoduje użycie angielskiego. Pliki PDF w językach `zh`, `ja`, `ko` i `ar` są generowane po angielsku.

**qrIds** `string[]`

Kody QR do objęcia raportem. Wymagane dla `selected` (co najmniej jedno ID) i `single` (dokładnie jedno ID). Każde ID musi być kodem QR z Twojego obszaru roboczego, inaczej żądanie zwraca `404`.

**name** `string`

Etykieta wyświetlana w temacie e-maila i w panelu, do 40 znaków.

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

Dołącza do e-maila wersję raportu w formacie 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"
}
```

## Aktualizacja zaplanowanego raportu

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

Zmienia zaplanowany raport albo go wstrzymuje i wznawia. Wysyłaj tylko pola, które chcesz zmienić, co najmniej jedno. Zmiana częstotliwości lub strefy czasowej albo wznowienie wstrzymanego raportu przelicza `nextRunAt`. Reguła jednego raportu na częstotliwość nadal obowiązuje, więc nakładająca się zmiana zwraca `409`.

**id** `string` *required*

ID zaplanowanego raportu. Weź je z odpowiedzi listy lub tworzenia.

**status** `string`

`paused` zatrzymuje e-maile bez usuwania harmonogramu. `active` je wznawia.

**name** `string`

Etykieta, do 40 znaków.

**frequency** `string`

`daily`, `weekly` lub `monthly`.

**scope** `string`

`all`, `selected` lub `single`.

**qrIds** `string[]`

Kody QR do objęcia raportem. Każde ID musi być kodem QR z Twojego obszaru roboczego.

**includePdf** `boolean`

Dołącza do e-maila plik PDF.

**timezone** `string`

Strefa czasowa IANA.

**locale** `string`

Język e-maila i pliku 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"
}
```

## Usuwanie zaplanowanego raportu

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

Usuwa harmonogram i zatrzymuje wszystkie kolejne e-maile.

> [!WARNING]
>
> Usunięcia zaplanowanego raportu nie można cofnąć.

**id** `string` *required*

ID zaplanowanego raportu.

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

## Typowe problemy

> [accordion] 404 przy eksporcie raportu
>
> Przy zakresie `selected` lub `single` żadne z `qrIds` nie pasuje do kodu QR z krótkim linkiem w Twoim obszarze roboczym. Sprawdź ID.

> [accordion] 404 "QR not found." przy planowaniu raportu
>
> Jedno z `qrIds` nie jest kodem QR w Twoim obszarze roboczym albo zostało usunięte. Sprawdź ID za pomocą [listy kodów QR](https://docs.getqr.com/pl/api/endpoints/qr-codes.md).

> [accordion] 409 przy planowaniu raportu
>
> Jeden z kodów QR należy już do zaplanowanego raportu o tej samej częstotliwości albo raport o tej częstotliwości używa zakresu `all`. Edytuj lub usuń tamten raport albo wybierz inną częstotliwość.

> [accordion] 404 "Scheduled report not found."
>
> `id` nie odpowiada żadnemu zaplanowanemu raportowi w Twoim obszarze roboczym. Weź je z [listy zaplanowanych raportów](#lista-zaplanowanych-raportów).

> [accordion] W raporcie brakuje dzisiejszych skanowań
>
> Raporty obejmują tylko ostatni zakończony okres. Aktualne liczby znajdziesz w [Analityce](https://docs.getqr.com/pl/api/endpoints/analytics.md).

## Co dalej

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

> [card] [Raporty zaplanowane w aplikacji](https://docs.getqr.com/pl/analytics/scheduled-reports.md)

> [card] [Odczytywanie raportów](https://docs.getqr.com/pl/analytics/reading-reports.md)

> [card] [Błędy](https://docs.getqr.com/pl/api/errors.md)


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