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

# Rapoarte

> Exportați un raport de scanări unic sau programați e-mailuri periodice cu rapoarte.

> [!NOTE]
>
> API-ul GetQR este în versiune beta și este disponibil pentru anumite spații de lucru. Detaliile se pot schimba înainte de lansarea generală.

Rapoartele rezumă scanările fiecărui cod QR pentru o zi, o săptămână sau o lună încheiată. Exportați imediat un raport sau programați un raport trimis periodic prin e-mail.

| Metodă | Cale | Descriere |
| - | - | - |
| `POST` | `/api/v1/reports` | [Exportarea unui raport](#exportarea-unui-raport) |
| `GET` | `/api/v1/reports/schedules` | [Listarea rapoartelor programate](#listarea-rapoartelor-programate) |
| `POST` | `/api/v1/reports/schedules` | [Programarea unui raport](#programarea-unui-raport) |
| `PATCH` | `/api/v1/reports/schedules/{id}` | [Actualizarea unui raport programat](#actualizarea-unui-raport-programat) |
| `DELETE` | `/api/v1/reports/schedules/{id}` | [Ștergerea unui raport programat](#ștergerea-unui-raport-programat) |

## Anteturi

**Authorization** `string` *required*

`Bearer` urmat de cheia dvs. API. Consultați [Autentificare](https://docs.getqr.com/ro/api/authentication.md).

**Content-Type** `string`

`application/json`. Obligatoriu pentru cererile `POST` și `PATCH`.

## Domeniu

Atât rapoartele unice, cât și cele programate primesc un `scope`:

| `scope` | Acoperă | `qrIds` |
| - | - | - |
| `all` | Codurile QR din spațiul dvs. de lucru | Omiteți |
| `selected` | Un set ales de coduri QR | Unul sau mai multe ID-uri |
| `single` | Exact un cod QR | Exact un ID |

Un raport include cel mult 50 de coduri QR. Cu `all`, acestea sunt codurile QR active create cel mai recent; codurile puse în pauză sunt excluse. Cu `selected` și `single`, codurile puse în pauză sunt incluse. Codurile QR fără link scurt nu au scanări și sunt omise.

## Perioadă

Perioada este întotdeauna ultima perioadă încheiată, așa că un raport nu include niciodată datele parțiale de azi. Limitele ei sunt la miezul nopții, în fusul orar al raportului.

| `period` sau `frequency` | Acoperă |
| - | - |
| `daily` | Ziua anterioară |
| `weekly` | Săptămâna anterioară, de luni până duminică |
| `monthly` | Luna calendaristică anterioară |

## Exportarea unui raport

`POST /api/v1/reports`

Generează un raport pentru ultima perioadă încheiată și îl returnează în răspuns.

**scope** `string` *required*

`all`, `selected` sau `single`. Consultați [Domeniu](#domeniu).

**period** `string` *required*

`daily`, `weekly` sau `monthly`. Consultați [Perioadă](#perioadă).

**format** `string` *required*

`json` returnează raportul în corpul răspunsului. `csv` și `pdf` returnează un fișier de descărcat.

**qrIds** `string[]`

Codurile QR incluse. Obligatoriu pentru `selected` (unul sau mai multe ID-uri) și `single` (exact un ID). Omiteți-l pentru `all`.

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

Fusul orar IANA după care se aliniază limitele perioadei, de exemplu `America/New_York`. Un fus orar necunoscut returnează `422`.

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

Limba PDF-ului, de exemplu `en` sau `de`. O valoare neacceptată revine la engleză. Ignorat de `csv` și `json`.

**name** `string`

Titlul afișat pe PDF, până la 40 de caractere. Ignorat de `csv` și `json`.

### Răspunsul JSON

**periodStart** `string`

Prima zi a perioadei, `YYYY-MM-DD`.

**periodEnd** `string`

Prima zi de după perioadă, `YYYY-MM-DD`. Perioada se încheie la miezul nopții, la începutul acestei zile.

**qrs** `object[]`

Câte o intrare pentru fiecare cod QR.

**properties**

**qrId** `string`

ID-ul codului QR.

**name** `string`

Titlul codului QR sau `Untitled QR`.

**type** `string`

Tipul codului QR, de exemplu `website`.

**totalScans** `integer`

Totalul scanărilor din perioadă.

**uniqueScans** `integer`

Scanările unice din perioadă.

**topGeography** `string`

Codul țării cu cele mai multe scanări sau `—` dacă nu există scanări.

**topDevice** `string`

Dispozitivul cu cele mai multe scanări sau `—`.

**topOs** `string`

Sistemul de operare cu cele mai multe scanări sau `—`.

**topBrowser** `string`

Browserul cu cele mai multe scanări sau `—`.

### Răspunsuri CSV și PDF

Corpul este fișierul. `Content-Disposition` îl denumește după perioadă, de exemplu `report-2026-08-10_2026-08-17.csv`. Fișierul CSV are câte un rând pentru fiecare cod QR, cu coloanele `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"
    }
  ]
}
```

## Obiectul raport programat

Un raport programat este trimis prin e-mail contului care l-a creat, la miezul nopții în fusul său orar.

**id** `string`

ID-ul raportului programat.

**name** `string | null`

Eticheta afișată în subiectul e-mailului și în panou.

**frequency** `string`

`daily`, `weekly` sau `monthly`.

**scope** `string`

`all`, `selected` sau `single`.

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

Codurile QR incluse în raport cu domeniile `selected` și `single`. `null` când nu au fost trimise ID-uri.

**filters** `null`

Întotdeauna `null`. Rezervat.

**includePdf** `boolean`

Dacă la e-mail este atașat un PDF.

**status** `string`

`active` sau `paused`.

**timezone** `string`

Fusul orar IANA după care se aliniază ora de trimitere și perioada.

**locale** `string`

Limba e-mailului și a PDF-ului.

**nextRunAt** `string`

Când este programat următorul e-mail, ISO 8601: următorul miez al nopții (`daily`), următoarea zi de luni (`weekly`) sau data de 1 a lunii următoare (`monthly`), în fusul orar al raportului.

**lastRunAt** `string | null`

Când a fost trimis ultimul e-mail, ISO 8601.

**createdAt** `string`

Data creării, ISO 8601.

**updatedAt** `string`

Data ultimei actualizări, ISO 8601.

## Listarea rapoartelor programate

`GET /api/v1/reports/schedules`

Returnează rapoartele programate ale spațiului dvs. de lucru, inclusiv cele create de alți membri, cele mai noi primele. Lista este paginată: consultați [Paginare](https://docs.getqr.com/ro/api/introduction.md#paginare).

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

Pagina returnată, 1 sau mai mult.

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

Rezultate pe pagină, de la 1 la 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 }
}
```

## Programarea unui raport

`POST /api/v1/reports/schedules`

Creează un raport care este trimis periodic prin e-mail. `nextRunAt` se calculează pe baza frecvenței și a fusului orar.

> [!NOTE]
>
> Un cod QR poate face parte dintr-un singur raport programat pentru fiecare frecvență. O programare care se suprapune returnează `409 conflict`.

Un raport cu domeniul `all` se suprapune cu orice alt raport cu aceeași frecvență. Rapoartele puse în pauză se iau și ele în calcul.

**frequency** `string` *required*

Cât de des este trimis raportul: `daily`, `weekly` sau `monthly`. Stabilește și perioada acoperită. Consultați [Perioadă](#perioadă).

**scope** `string` *required*

`all`, `selected` sau `single`. Consultați [Domeniu](#domeniu).

**timezone** `string` *required*

Fusul orar IANA după care se aliniază ora de trimitere și perioada, de exemplu `America/New_York`. Un fus orar necunoscut returnează `422`.

**locale** `string` *required*

Limba e-mailului și a PDF-ului, de exemplu `en` sau `de`. O valoare neacceptată revine la engleză. PDF-urile în `zh`, `ja`, `ko` și `ar` sunt generate în engleză.

**qrIds** `string[]`

Codurile QR incluse. Obligatoriu pentru `selected` (unul sau mai multe ID-uri) și `single` (exact un ID). Fiecare ID trebuie să fie al unui cod QR din spațiul dvs. de lucru, altfel cererea returnează `404`.

**name** `string`

Eticheta afișată în subiectul e-mailului și în panou, până la 40 de caractere.

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

Atașează la e-mail o versiune PDF a raportului.

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

## Actualizarea unui raport programat

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

Modifică un raport programat sau îl pune în pauză și îl reia. Trimiteți doar câmpurile pe care vreți să le modificați, cel puțin unul. Schimbarea frecvenței sau a fusului orar ori reluarea unui raport pus în pauză recalculează `nextRunAt`. Regula unui singur raport pentru fiecare frecvență se aplică în continuare, așa că o modificare care se suprapune returnează `409`.

**id** `string` *required*

ID-ul raportului programat. Preluați-l din răspunsul listei sau al creării.

**status** `string`

`paused` oprește e-mailurile fără a șterge programarea. `active` le reia.

**name** `string`

Eticheta, până la 40 de caractere.

**frequency** `string`

`daily`, `weekly` sau `monthly`.

**scope** `string`

`all`, `selected` sau `single`.

**qrIds** `string[]`

Codurile QR incluse. Fiecare ID trebuie să fie al unui cod QR din spațiul dvs. de lucru.

**includePdf** `boolean`

Atașează un PDF la e-mail.

**timezone** `string`

Fusul orar IANA.

**locale** `string`

Limba e-mailului și a PDF-ului.

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

## Ștergerea unui raport programat

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

Șterge programarea și oprește toate e-mailurile viitoare.

> [!WARNING]
>
> Ștergerea unui raport programat nu poate fi anulată.

**id** `string` *required*

ID-ul raportului programat.

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

## Probleme frecvente

> [accordion] 404 la exportarea unui raport
>
> Cu domeniul `selected` sau `single`, niciunul dintre `qrIds` nu corespunde unui cod QR cu link scurt din spațiul dvs. de lucru. Verificați ID-urile.

> [accordion] 404 "QR not found." la programarea unui raport
>
> Unul dintre `qrIds` nu este un cod QR din spațiul dvs. de lucru sau a fost șters. Verificați ID-urile cu [Listarea codurilor QR](https://docs.getqr.com/ro/api/endpoints/qr-codes.md).

> [accordion] 409 la programarea unui raport
>
> Unul dintre codurile QR face deja parte dintr-un raport programat cu aceeași frecvență sau un raport cu acea frecvență folosește domeniul `all`. Editați sau ștergeți acel raport ori alegeți o altă frecvență.

> [accordion] 404 "Scheduled report not found."
>
> `id` nu corespunde unui raport programat din spațiul dvs. de lucru. Preluați-l din [Listarea rapoartelor programate](#listarea-rapoartelor-programate).

> [accordion] Raportul nu include scanările de azi
>
> Rapoartele acoperă doar ultima perioadă încheiată. Folosiți [Statistici](https://docs.getqr.com/ro/api/endpoints/analytics.md) pentru cifre în timp real.

## Ce urmează

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

> [card] [Rapoarte programate în aplicație](https://docs.getqr.com/ro/analytics/scheduled-reports.md)

> [card] [Citiți rapoartele](https://docs.getqr.com/ro/analytics/reading-reports.md)

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


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