보고서

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

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

{
  "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"
    }
  ]
}

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

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

{
  "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"
    }
  ]
}

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}`	예약 보고서 삭제

헤더

string

필수

Bearer 뒤에 API 키를 붙입니다. 인증을 참조하세요.

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 가장 최근에 끝난 기간의 보고서를 만들어 응답으로 반환합니다.

string

필수

all, selected, single. 범위를 참조하세요.

string

필수

daily, weekly, monthly. 기간을 참조하세요.

string

필수

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

string[]

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

string

기본값:"UTC"

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

string

기본값:"en"

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

string

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

JSON 응답

string

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

string

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

object[]

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

표시 properties

string

QR 코드의 ID입니다.

string

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

string

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

integer

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

integer

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

string

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

string

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

string

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

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입니다.

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

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

{
  "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"
    }
  ]
}

예약 보고서 객체

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

string

예약 보고서의 ID입니다.

string | null

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

string

daily, weekly, monthly.

string

all, selected, single.

string[] | null

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

null

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

boolean

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

string

active 또는 paused.

string

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

string

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

string

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

string | null

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

string

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

string

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

예약 보고서 목록 조회

GET /api/v1/reports/schedules 다른 멤버가 만든 것을 포함하여 워크스페이스의 예약 보고서를 최신순으로 반환합니다. 목록은 페이지로 나뉩니다. 페이지네이션을 참조하세요.

integer

기본값:"1"

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

integer

기본값:"100"

페이지당 결과 수로, 1~100입니다.

curl "https://getqr.com/api/v1/reports/schedules?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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은 빈도와 시간대로 계산됩니다.

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

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

string

필수

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

string

필수

all, selected, single. 범위를 참조하세요.

string

필수

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

string

필수

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

string[]

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

string

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

boolean

기본값:"false"

보고서의 PDF 버전을 이메일에 첨부합니다.

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

{
  "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를 반환합니다.

string

필수

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

string

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

string

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

string

daily, weekly, monthly.

string

all, selected, single.

string[]

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

boolean

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

string

IANA 시간대입니다.

string

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

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

{
  "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} 일정을 삭제하고 이후의 모든 이메일 발송을 중지합니다.

예약 보고서 삭제는 되돌릴 수 없습니다.

string

필수

예약 보고서의 ID입니다.

curl -X DELETE "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{ "id": "clx8f2k9a0001qk0c8vhd3xyz", "deleted": true }

자주 발생하는 문제

보고서를 내보낼 때 404가 반환됩니다

selected 또는 single 범위에서 qrIds 중 어느 것도 워크스페이스에서 단축 링크가 있는 QR 코드와 일치하지 않았습니다. ID를 확인하세요.

보고서 예약 시 404 "QR not found."

qrIds 중 하나가 워크스페이스의 QR 코드가 아니거나 삭제되었습니다. QR 코드 목록 조회로 ID를 확인하세요.

보고서를 예약할 때 409가 반환됩니다

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

404 "Scheduled report not found."

해당 id가 워크스페이스의 예약 보고서와 일치하지 않습니다. 예약 보고서 목록 조회에서 가져오세요.

보고서에 오늘 스캔이 빠져 있습니다

보고서는 가장 최근에 끝난 기간만 다룹니다. 실시간 수치는 분석을 사용하세요.

API

헤더

범위

기간

보고서 내보내기

JSON 응답

CSV와 PDF 응답

예약 보고서 객체

예약 보고서 목록 조회

보고서 예약

예약 보고서 업데이트

예약 보고서 삭제

자주 발생하는 문제

다음 단계

분석

앱의 예약 보고서

보고서 읽기

오류

​헤더

​범위

​기간

​보고서 내보내기

​JSON 응답

​CSV와 PDF 응답

​예약 보고서 객체

​예약 보고서 목록 조회

​보고서 예약

​예약 보고서 업데이트

​예약 보고서 삭제

​자주 발생하는 문제

​다음 단계

분석

앱의 예약 보고서

보고서 읽기

오류

헤더

범위

기간

보고서 내보내기

JSON 응답

CSV와 PDF 응답

예약 보고서 객체

예약 보고서 목록 조회

보고서 예약

예약 보고서 업데이트

예약 보고서 삭제

자주 발생하는 문제

다음 단계