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

# 보고서

> 일회성 스캔 보고서를 내보내거나 정기 보고서 이메일을 예약하세요.

> [!NOTE]
>
> GetQR API는 베타 버전이며 일부 워크스페이스에서만 사용할 수 있습니다. 정식 출시 전에 세부 사항이 변경될 수 있습니다.

보고서는 지난 하루, 한 주 또는 한 달 동안의 스캔을 QR 코드별로 요약합니다. 바로 내보내거나, 정기적으로 이메일로 받을 보고서를 예약할 수 있습니다.

| 메서드 | 경로 | 설명 |
| - | - | - |
| `POST` | `/api/v1/reports` | [보고서 내보내기](#보고서-내보내기) |
| `GET` | `/api/v1/reports/schedules` | [예약 보고서 목록 조회](#예약-보고서-목록-조회) |
| `POST` | `/api/v1/reports/schedules` | [보고서 예약](#보고서-예약) |
| `PATCH` | `/api/v1/reports/schedules/{id}` | [예약 보고서 업데이트](#예약-보고서-업데이트) |
| `DELETE` | `/api/v1/reports/schedules/{id}` | [예약 보고서 삭제](#예약-보고서-삭제) |

## 헤더

**Authorization** `string` *required*

`Bearer` 뒤에 API 키를 붙입니다. [인증](https://docs.getqr.com/ko/api/authentication.md)을 참조하세요.

**Content-Type** `string`

`application/json`. `POST`와 `PATCH` 요청에서는 필수입니다.

## 범위

일회성 보고서와 예약 보고서 모두 `scope`를 받습니다.

| `scope` | 범위 | `qrIds` |
| - | - | - |
| `all` | 워크스페이스의 QR 코드 | 생략 |
| `selected` | 선택한 QR 코드 | ID 하나 이상 |
| `single` | QR 코드 정확히 하나 | ID 정확히 하나 |

보고서에는 QR 코드가 최대 50개까지 포함됩니다. `all`이면 가장 최근에 만든 활성 QR 코드가 포함되며, 일시 중지된 코드는 제외됩니다. `selected`와 `single`이면 일시 중지된 코드도 포함됩니다. 단축 링크가 없는 QR 코드는 스캔이 없으므로 건너뜁니다.

## 기간

기간은 항상 가장 최근에 끝난 기간이므로, 보고서에 오늘의 일부 데이터가 포함되는 일은 없습니다. 기간의 경계는 보고서 시간대 기준 자정입니다.

| `period` 또는 `frequency` | 범위 |
| - | - |
| `daily` | 전날 |
| `weekly` | 지난주(월요일\~일요일) |
| `monthly` | 지난달 |

## 보고서 내보내기

`POST /api/v1/reports`

가장 최근에 끝난 기간의 보고서를 만들어 응답으로 반환합니다.

**scope** `string` *required*

`all`, `selected`, `single`. [범위](#범위)를 참조하세요.

**period** `string` *required*

`daily`, `weekly`, `monthly`. [기간](#기간)을 참조하세요.

**format** `string` *required*

`json`은 보고서를 응답 본문으로 반환합니다. `csv`와 `pdf`는 파일 다운로드를 반환합니다.

**qrIds** `string[]`

대상 QR 코드입니다. `selected`(ID 하나 이상)와 `single`(ID 정확히 하나)에서는 필수입니다. `all`에서는 생략하세요.

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

기간 경계의 기준이 되는 IANA 시간대입니다. 예: `America/New_York`. 알 수 없는 시간대는 `422`를 반환합니다.

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

PDF의 언어입니다. 예: `en` 또는 `de`. 지원하지 않는 값은 영어로 대체됩니다. `csv`와 `json`에서는 무시됩니다.

**name** `string`

PDF에 표시되는 제목으로, 최대 40자입니다. `csv`와 `json`에서는 무시됩니다.

### JSON 응답

**periodStart** `string`

기간의 첫날(`YYYY-MM-DD`)입니다.

**periodEnd** `string`

기간 다음 날(`YYYY-MM-DD`)입니다. 기간은 이날이 시작되는 자정에 끝납니다.

**qrs** `object[]`

QR 코드마다 하나의 항목입니다.

**properties**

**qrId** `string`

QR 코드의 ID입니다.

**name** `string`

QR 코드의 제목 또는 `Untitled QR`입니다.

**type** `string`

QR 코드 유형입니다. 예: `website`.

**totalScans** `integer`

기간 내 전체 스캔 수입니다.

**uniqueScans** `integer`

기간 내 고유 스캔 수입니다.

**topGeography** `string`

스캔이 가장 많은 국가 코드이며, 스캔이 없으면 `—`입니다.

**topDevice** `string`

스캔이 가장 많은 기기 또는 `—`입니다.

**topOs** `string`

스캔이 가장 많은 운영체제 또는 `—`입니다.

**topBrowser** `string`

스캔이 가장 많은 브라우저 또는 `—`입니다.

### CSV와 PDF 응답

본문은 파일입니다. `Content-Disposition`은 기간에 따라 파일 이름을 지정합니다. 예: `report-2026-08-10_2026-08-17.csv`. CSV는 QR 코드마다 한 행이며, 열은 `QR ID`, `QR name`, `QR type`, `Total scans`, `Unique scans`, `Top geography`, `Top device`, `Top OS`, `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"
    }
  ]
}
```

## 예약 보고서 객체

예약 보고서는 해당 시간대 기준 자정에 보고서를 만든 계정으로 이메일 발송됩니다.

**id** `string`

예약 보고서의 ID입니다.

**name** `string | null`

이메일 제목과 대시보드에 표시되는 이름입니다.

**frequency** `string`

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

**scope** `string`

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

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

`selected`와 `single` 범위에서 보고서가 다루는 QR 코드입니다. ID를 보내지 않았으면 `null`입니다.

**filters** `null`

항상 `null`입니다. 향후 사용을 위해 예약된 필드입니다.

**includePdf** `boolean`

이메일에 PDF가 첨부되는지 여부입니다.

**status** `string`

`active` 또는 `paused`.

**timezone** `string`

발송 시각과 기간의 기준이 되는 IANA 시간대입니다.

**locale** `string`

이메일과 PDF의 언어입니다.

**nextRunAt** `string`

다음 이메일 발송 예정 시각(ISO 8601)입니다. 보고서 시간대 기준으로 다음 자정(`daily`), 다음 월요일(`weekly`), 다음 달 1일(`monthly`)입니다.

**lastRunAt** `string | null`

마지막 이메일 발송 시각(ISO 8601)입니다.

**createdAt** `string`

생성 일시(ISO 8601)입니다.

**updatedAt** `string`

마지막 업데이트 일시(ISO 8601)입니다.

## 예약 보고서 목록 조회

`GET /api/v1/reports/schedules`

다른 멤버가 만든 것을 포함하여 워크스페이스의 예약 보고서를 최신순으로 반환합니다. 목록은 페이지로 나뉩니다. [페이지네이션](https://docs.getqr.com/ko/api/introduction.md#페이지네이션)을 참조하세요.

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

반환할 페이지로, 1 이상입니다.

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

페이지당 결과 수로, 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 }
}
```

## 보고서 예약

`POST /api/v1/reports/schedules`

정기적으로 이메일 발송되는 보고서를 만듭니다. `nextRunAt`은 빈도와 시간대로 계산됩니다.

> [!NOTE]
>
> QR 코드 하나는 빈도마다 하나의 예약 보고서에만 포함될 수 있습니다. 겹치는 일정은 `409 conflict`를 반환합니다.

`all` 범위의 보고서는 같은 빈도의 다른 모든 보고서와 겹칩니다. 일시 중지된 보고서도 포함됩니다.

**frequency** `string` *required*

보고서 발송 빈도: `daily`, `weekly`, `monthly`. 보고서가 다루는 기간도 이 값으로 정해집니다. [기간](#기간)을 참조하세요.

**scope** `string` *required*

`all`, `selected`, `single`. [범위](#범위)를 참조하세요.

**timezone** `string` *required*

발송 시각과 기간의 기준이 되는 IANA 시간대입니다. 예: `America/New_York`. 알 수 없는 시간대는 `422`를 반환합니다.

**locale** `string` *required*

이메일과 PDF의 언어입니다. 예: `en` 또는 `de`. 지원하지 않는 값은 영어로 대체됩니다. `zh`, `ja`, `ko`, `ar`의 PDF는 영어로 렌더링됩니다.

**qrIds** `string[]`

대상 QR 코드입니다. `selected`(ID 하나 이상)와 `single`(ID 정확히 하나)에서는 필수입니다. 모든 ID는 워크스페이스의 QR 코드여야 하며, 그렇지 않으면 `404`를 반환합니다.

**name** `string`

이메일 제목과 대시보드에 표시되는 이름으로, 최대 40자입니다.

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

보고서의 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"
}
```

## 예약 보고서 업데이트

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

예약 보고서를 변경하거나 일시 중지 또는 재개합니다. 변경할 필드만 하나 이상 보내세요. 빈도나 시간대를 바꾸거나 일시 중지된 보고서를 재개하면 `nextRunAt`이 다시 계산됩니다. 빈도마다 보고서 하나라는 규칙은 계속 적용되므로 겹치는 변경은 `409`를 반환합니다.

**id** `string` *required*

예약 보고서의 ID입니다. 목록 조회 또는 생성 응답에서 가져오세요.

**status** `string`

`paused`는 일정을 삭제하지 않고 이메일 발송을 중지합니다. `active`는 발송을 재개합니다.

**name** `string`

이름으로, 최대 40자입니다.

**frequency** `string`

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

**scope** `string`

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

**qrIds** `string[]`

대상 QR 코드입니다. 모든 ID는 워크스페이스의 QR 코드여야 합니다.

**includePdf** `boolean`

이메일에 PDF를 첨부합니다.

**timezone** `string`

IANA 시간대입니다.

**locale** `string`

이메일과 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"
}
```

## 예약 보고서 삭제

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

일정을 삭제하고 이후의 모든 이메일 발송을 중지합니다.

> [!WARNING]
>
> 예약 보고서 삭제는 되돌릴 수 없습니다.

**id** `string` *required*

예약 보고서의 ID입니다.

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

## 자주 발생하는 문제

> [accordion] 보고서를 내보낼 때 404가 반환됩니다
>
> `selected` 또는 `single` 범위에서 `qrIds` 중 어느 것도 워크스페이스에서 단축 링크가 있는 QR 코드와 일치하지 않았습니다. ID를 확인하세요.

> [accordion] 보고서 예약 시 404 "QR not found."
>
> `qrIds` 중 하나가 워크스페이스의 QR 코드가 아니거나 삭제되었습니다. [QR 코드 목록 조회](https://docs.getqr.com/ko/api/endpoints/qr-codes.md)로 ID를 확인하세요.

> [accordion] 보고서를 예약할 때 409가 반환됩니다
>
> QR 코드 중 하나가 이미 같은 빈도의 예약 보고서에 포함되어 있거나, 해당 빈도의 보고서가 `all` 범위를 사용합니다. 그 보고서를 수정하거나 삭제하거나, 다른 빈도를 선택하세요.

> [accordion] 404 "Scheduled report not found."
>
> 해당 `id`가 워크스페이스의 예약 보고서와 일치하지 않습니다. [예약 보고서 목록 조회](#예약-보고서-목록-조회)에서 가져오세요.

> [accordion] 보고서에 오늘 스캔이 빠져 있습니다
>
> 보고서는 가장 최근에 끝난 기간만 다룹니다. 실시간 수치는 [분석](https://docs.getqr.com/ko/api/endpoints/analytics.md)을 사용하세요.

## 다음 단계

> [card] [분석](https://docs.getqr.com/ko/api/endpoints/analytics.md)

> [card] [앱의 예약 보고서](https://docs.getqr.com/ko/analytics/scheduled-reports.md)

> [card] [보고서 읽기](https://docs.getqr.com/ko/analytics/reading-reports.md)

> [card] [오류](https://docs.getqr.com/ko/api/errors.md)


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