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

# QR 코드

> QR 코드를 생성, 목록 조회, 업데이트, 일시 중지, 복제, 삭제, 다운로드하세요.

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

GetQR의 QR 코드는 이미지와, 그 이미지가 거쳐 가는 단축 링크로 이루어집니다. QR 코드를 만들면 단축 링크도 함께 만들어지므로, 코드를 다시 인쇄하지 않고도 나중에 목적지를 바꿀 수 있습니다.

| 메서드 | 경로 | 설명 |
| - | - | - |
| `GET` | `/api/v1/qrs` | [QR 코드 목록 조회](#qr-코드-목록-조회) |
| `POST` | `/api/v1/qrs` | [QR 코드 생성](#qr-코드-생성) |
| `GET` | `/api/v1/qrs/{qrId}` | [QR 코드 조회](#qr-코드-조회) |
| `PATCH` | `/api/v1/qrs/{qrId}` | [QR 코드 업데이트](#qr-코드-업데이트) |
| `PUT` | `/api/v1/qrs/{qrId}` | [일시 중지 상태 설정](#일시-중지-상태-설정) |
| `POST` | `/api/v1/qrs/{qrId}/pause` | [QR 코드 일시 중지](#qr-코드-일시-중지) |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [QR 코드 재활성화](#qr-코드-재활성화) |
| `POST` | `/api/v1/qrs/{qrId}/duplicate` | [QR 코드 복제](#qr-코드-복제) |
| `DELETE` | `/api/v1/qrs/{qrId}` | [QR 코드 삭제](#qr-코드-삭제) |
| `GET` | `/api/v1/qrs/{qrId}/download` | [QR 코드 이미지 다운로드](#qr-코드-이미지-다운로드) |

> [card] [유형별 QR 코드 데이터](https://docs.getqr.com/ko/api/guides/qr-types.md)
>
> 16가지 유형별 `data` 형식.

> [card] [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md)
>
> 점 스타일, 색상, 프레임, 로고.

> [card] [접근 규칙](https://docs.getqr.com/ko/api/guides/access-rules.md)
>
> 일정, 스캔 제한, 비밀번호.

QR 코드의 스캔 통계는 [분석](https://docs.getqr.com/ko/api/endpoints/analytics.md)을 참조하세요.

## QR 코드 객체

[삭제](#qr-코드-삭제)와 [다운로드](#qr-코드-이미지-다운로드)를 제외한 모든 QR 코드 엔드포인트는 이 객체를 반환합니다. 목록 조회는 이 객체의 배열을 반환합니다.

**id** `string`

QR 코드의 고유 ID입니다. 예: `qr_1EPcVfeHZAY2iNoVLsgW2Aqf`.

**qrType** `string`

QR 코드 유형입니다. 예: `website`. 16가지 값 전체는 [유형별 QR 코드 데이터](https://docs.getqr.com/ko/api/guides/qr-types.md)를 참조하세요.

**title** `string | null`

대시보드에 표시되는 QR 코드 이름입니다.

**description** `string | null`

QR 코드에 대한 자유 형식 메모입니다.

**data** `string`

저장된 페이로드입니다. `wifi`, `vcard`, `social`, `multilink`, `event`, `sms`에서는 보낸 페이로드 그대로입니다. 그 밖의 유형에서는 단축 링크이므로 목적지는 `url`에서 읽으세요.

**archived** `boolean`

QR 코드가 일시 중지되면 `true`입니다.

**isStatic** `boolean`

대시보드에서 만든, 단축 링크가 없는 정적 QR 코드이면 `true`입니다. API는 항상 동적 QR 코드를 만듭니다.

**shortLink** `string | null`

전체 단축 링크입니다. 예: `https://getqr.sh/x7Kd2p1`.

**domain** `string | null`

단축 링크의 도메인입니다.

**key** `string | null`

단축 링크의 슬러그입니다.

**keyIsCustom** `boolean`

슬러그를 자동 생성하지 않고 직접 지정했으면 `true`입니다.

**url** `string | null`

단축 링크가 리디렉션하는 목적지입니다.

**ios** `string | null`

`app` QR 코드에서 iOS 방문자의 목적지입니다.

**android** `string | null`

`app` QR 코드에서 Android 방문자의 목적지입니다.

**scans** `integer`

전체 스캔 수입니다.

**access** `object`

접근 규칙입니다. 비밀번호 자체는 반환되지 않습니다. [접근 규칙](https://docs.getqr.com/ko/api/guides/access-rules.md)을 참조하세요.

**properties**

**passwordProtected** `boolean`

방문자가 비밀번호를 입력해야 하는지 여부입니다.

**activeAt** `string | null`

예약된 시작 시각(ISO 8601)입니다.

**pauseAt** `string | null`

예약된 종료 시각(ISO 8601)입니다.

**scanLimit** `integer | null`

최대 스캔 횟수입니다.

**designKind** `string`

읽기 전용입니다. `custom`은 API로 전부 수정할 수 있는 디자인입니다. `branded`와 `ai`는 대시보드에서 만든 Branded design 또는 AI design입니다. API로는 그 이미지를 수정할 수 없지만, 다른 필드를 변경해도 이미지는 유지됩니다.

**design** `object`

저장된 디자인입니다. `styles`, `frameOptions`, `logoOptions`로 구성되며 각각 객체 또는 `null`입니다. 요청 필드와 구조가 같으므로 그대로 다시 보낼 수 있습니다. [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md)을 참조하세요.

**file** `object | null`

`pdf`, `image`, `video` QR 코드의 파일입니다. `id`, `name`, `size`(바이트)로 구성됩니다.

**appName** `string | null`

읽기 전용입니다. 대시보드에서 만든 `app` QR 코드의 표시 이름입니다.

**pdfBundle** `object | null`

읽기 전용입니다. 대시보드에서 만든, 파일이 여러 개인 `pdf` QR 코드입니다. `title`, `layout`, `files`로 구성됩니다.

**imageGallery** `object | null`

읽기 전용입니다. 대시보드에서 만든, 이미지가 여러 개인 `image` QR 코드입니다. `title`, `layout`, `files`로 구성됩니다.

**createdAt** `string`

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

**updatedAt** `string`

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

민감한 정보와 내부 ID(`password`, `userId`, `workspaceId`, `projectId`)는 반환되지 않습니다.

```json theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "description": null,
  "data": "https://getqr.sh/x7Kd2p1",
  "archived": false,
  "isStatic": false,
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "domain": "getqr.sh",
  "key": "x7Kd2p1",
  "keyIsCustom": false,
  "url": "https://example.com",
  "ios": null,
  "android": null,
  "scans": 128,
  "access": {
    "passwordProtected": false,
    "activeAt": null,
    "pauseAt": null,
    "scanLimit": null
  },
  "designKind": "custom",
  "design": {
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" }, … },
    "frameOptions": { "id": "card", "text": "Scan me!", … },
    "logoOptions": { "type": "suggested", "id": "logo-website-3", "scalePercent": 25 }
  },
  "file": null,
  "appName": null,
  "pdfBundle": null,
  "imageGallery": null,
  "createdAt": "2026-08-01T10:00:00.000Z",
  "updatedAt": "2026-08-01T10:00:00.000Z"
}
```

## QR 코드 목록 조회

`GET /api/v1/qrs`

워크스페이스의 QR 코드를 한 페이지씩 반환합니다.

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

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

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

페이지당 QR 코드 수로, 1부터 100까지입니다. 더 큰 값은 거부됩니다.

**search** `string`

QR 코드 제목과 비교합니다. 2자보다 긴 검색어는 저장된 `data`와도 비교합니다. 링크 유형에서는 저장된 `data`가 단축 링크이므로 목적지 URL로는 검색할 수 없습니다.

**sortBy** `string` (default: createdAt)

정렬 기준 필드: `createdAt`, `updatedAt`, `clicks`(전체 스캔 수), `lastClicked`(최근 스캔), `type`. `type`은 항상 내림차순으로 정렬되며 `sortOrder`를 무시합니다.

**sortOrder** `string` (default: desc)

정렬 방향: `asc` 또는 `desc`.

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

일시 중지된 QR 코드도 포함합니다.

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

일시 중지된 QR 코드만 반환합니다. `showArchived`보다 우선합니다.

불리언 매개변수에는 문자열 `true` 또는 `false`를 사용합니다. `pagination.hasMore`가 `true`인 동안 다음 페이지를 요청하세요. [페이지네이션](https://docs.getqr.com/ko/api/introduction.md#페이지네이션)을 참조하세요.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/qrs?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
      "qrType": "website",
      "title": "Landing page",
      "shortLink": "https://getqr.sh/x7Kd2p1",
      "url": "https://example.com",
      "scans": 128,
      "…": "…"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}
```

## QR 코드 생성

`POST /api/v1/qrs`

QR 코드와 단축 링크를 함께 만듭니다. 새 [QR 코드](#qr-코드-객체)와 함께 `201 Created`를 반환합니다.

**Idempotency-Key** `string`

직접 정한 재시도 토큰입니다. 24시간 안에 같은 키로 요청을 반복하면 두 번째 QR 코드를 만들지 않고 원래 응답을 반환합니다. [재시도와 중복](#재시도와-중복)을 참조하세요.

**qrType** `string` *required*

QR 코드가 인코딩하는 내용입니다. `data`의 형식도 이 값으로 정해집니다. `website`, `pdf`, `image`, `video`, `whatsapp`, `social`, `wifi`, `app`, `feedback`, `vcard`, `sms`, `payment`, `location`, `multilink`, `email`, `event` 중 하나입니다.

**data** `string` *required*

유형의 페이로드로, `qrType`에 맞는지 검사됩니다. 빈 문자열이면 검사를 건너뜁니다. 유형별 형식은 [유형별 QR 코드 데이터](https://docs.getqr.com/ko/api/guides/qr-types.md)에 있습니다.

**link** `object`

QR 코드가 거쳐 가는 단축 링크입니다. 선택 사항이며, 생략하면 `link.url`은 `data`를 따릅니다.

**properties**

**url** `string`

단축 링크가 리디렉션하는 목적지입니다. 생략하거나 비워 두면 기본값은 `data`입니다. 둘 다 보냈는데 값이 다르면 `link.url`이 우선합니다. `vcard`, `social`, `multilink`, `event` QR 코드는 항상 호스팅 페이지를 가리키고, `fileId`가 있는 `pdf`, `image`, `video` QR 코드는 항상 파일을 가리킵니다. 허용되는 스킴: `http:`, `https:`, `wifi:`, `mailto:`, `sms:`, `begin:`.

**domain** `string`

단축 링크의 도메인입니다. 워크스페이스의 활성 도메인이어야 합니다. 다른 도메인은 `403`을, 아직 활성화되지 않은 도메인은 `422`를 반환합니다. 기본값은 워크스페이스의 기본 도메인입니다.

**key** `string`

단축 링크 슬러그로, 3\~15자이며 소문자로 저장됩니다. 허용되지 않는 슬러그는 `422`를, 이미 사용 중인 슬러그는 `409`를 반환합니다. 생략하면 7자 무작위 슬러그가 생성됩니다.

**ios** `string | null`

`app` QR 코드에서 iOS 방문자의 목적지 URL입니다.

**android** `string | null`

`app` QR 코드에서 Android 방문자의 목적지 URL입니다.

**title** `string | null`

단축 링크에 저장되는 링크 미리보기 제목(`og:title`)입니다. QR 코드 자체의 `title`과는 다릅니다. 아직 이 값을 표시하는 곳은 없습니다.

**description** `string | null`

단축 링크에 저장되는 링크 미리보기 설명(`og:description`)입니다. 아직 이 값을 표시하는 곳은 없습니다.

**expiresAt, expiredUrl** `—`

이 API에서는 사용할 수 없으며, 둘 중 하나라도 보내면 `422`를 반환합니다. 특정 시각에 QR 코드를 중지하려면 `access.pauseAt`을 사용하세요.

**title** `string`

대시보드에 표시되는 QR 코드 이름입니다. 앞뒤 공백이 제거되며 1\~40자입니다. 생략하면 제목 없는 QR 코드가 됩니다.

**description** `string`

QR 코드에 대한 자유 형식 메모로, 최대 280자입니다.

**fileId** `string`

`pdf`, `image`, `video` QR 코드의 파일로, 일치하는 용도로 업로드한 것입니다. `vcard`, `social`, `multilink`에서는 `logo` 용도로 업로드한 선택적 프로필 이미지입니다. `event`도 받지만, 이벤트 페이지는 커버 이미지를 `data.fileId`에서 읽습니다. 그 밖의 유형은 `422`를 반환합니다. 먼저 [파일](https://docs.getqr.com/ko/api/endpoints/files.md)로 파일을 업로드하세요. [QR 코드에 사용하는 파일](https://docs.getqr.com/ko/api/guides/qr-types.md#qr-코드에-사용하는-파일)을 참조하세요.

**templateId** `string`

새 QR 코드에 디자인을 적용할 [템플릿](https://docs.getqr.com/ko/api/endpoints/templates.md)입니다. 보낸 디자인 필드는 그 위에 병합됩니다. Branded design 또는 AI design 템플릿은 `422`(`art_template_unsupported`)를 반환합니다. 알 수 없는 템플릿이나 다른 워크스페이스의 템플릿은 `404`를 반환합니다.

**styles** `object`

점과 모서리의 모양과 색상입니다. [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md)을 참조하세요.

**frameOptions** `object`

QR 코드를 감싸는 프레임과 행동 유도 문구입니다. [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md)을 참조하세요.

**logoOptions** `object`

중앙의 로고입니다. 추천 로고 또는 `logo` 용도로 업로드한 직접 만든 파일을 사용합니다. 알 수 없는 파일, 업로드가 완료되지 않은 파일, 다른 용도의 파일은 거부됩니다. [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md)을 참조하세요.

**access** `object`

일정, 스캔 제한, 비밀번호 보호입니다. [접근 규칙](https://docs.getqr.com/ko/api/guides/access-rules.md)을 참조하세요.

**properties**

**activeAt** `string | null`

예약된 시작 시각(ISO 8601)입니다.

**pauseAt** `string | null`

예약된 종료 시각(ISO 8601)입니다.

**scanLimit** `integer | null`

최대 스캔 횟수로, 양의 정수입니다.

**password** `string | null`

방문자가 입력해야 하는 비밀번호입니다. 보내면 보호가 켜집니다.

**passwordProtected** `boolean`

저장된 비밀번호를 유지한 채 보호를 끄거나 다시 켭니다.

**archived** `boolean`

QR 코드의 일시 중지 여부입니다. `true`이면 일시 중지된 상태로 만들어지며, 스캔하면 목적지 대신 일시 중지 페이지가 표시됩니다.

알 수 없는 필드는 오류 없이 무시됩니다. [API에서 지원하지 않는 기능](https://docs.getqr.com/ko/api/guides/qr-types.md#api에서-지원하지-않는-기능)을 참조하세요.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: landing-page-2026-08" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page",
    "access": { "scanLimit": 500 }
  }'
```

```json 201 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "data": "https://getqr.sh/x7Kd2p1",
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "url": "https://example.com",
  "scans": 0,
  "access": { "passwordProtected": false, "activeAt": null, "pauseAt": null, "scanLimit": 500 },
  "…": "…"
}
```

### 재시도와 중복

* **키가 있는 경우.** `Idempotency-Key` 헤더가 있으면 24시간 동안 같은 응답이 재생됩니다.
* **키가 없는 경우.** 30초 안에 보낸 동일한 본문은 중복으로 처리됩니다.
* **재생.** 재생된 응답은 저장된 응답을 `x-idempotent-replay: true`와 함께 반환합니다. 새 QR 코드는 `false`를 반환합니다.
* **처리 중.** 첫 번째 요청이 처리 중일 때 들어온 두 번째 요청은 `409 conflict`를 받습니다.
* **실패.** 생성에 실패하면 키가 즉시 해제되므로 같은 키로 다시 시도할 수 있습니다.
* **최선 노력 방식.** 이 보호 장치를 사용할 수 없으면 생성 요청은 보호 없이 처리됩니다.

[멱등성](https://docs.getqr.com/ko/api/introduction.md#멱등성)도 참조하세요.

## QR 코드 조회

`GET /api/v1/qrs/{qrId}`

[QR 코드](#qr-코드-객체)를 단축 링크, 접근 규칙, 디자인, 그리고 파일 기반 유형의 경우 파일과 함께 반환합니다.

**qrId** `string` *required*

QR 코드의 ID로, 목록 조회 또는 생성 응답에서 가져옵니다.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

응답은 전체 [QR 코드 객체](#qr-코드-객체)입니다.

## QR 코드 업데이트

`PATCH /api/v1/qrs/{qrId}`

QR 코드의 콘텐츠, 목적지, 디자인, 접근 규칙을 변경합니다. 변경할 필드만 보내세요. 업데이트된 [QR 코드](#qr-코드-객체)를 반환합니다.

**qrId** `string` *required*

QR 코드의 ID입니다.

본문은 [QR 코드 생성](#qr-코드-생성)과 같은 필드를 모두 선택 사항으로 받으며, 다음 점이 다릅니다.

* **`templateId`.** 받지 않습니다.
* **`link`.** 일부만 보낼 수 있습니다. `link.url`을 생략하면 현재 목적지가 유지됩니다. `link.domain`과 `link.key`는 `422`를 반환합니다. 인쇄된 코드가 인코딩하는 것은 단축 링크이므로, 다른 단축 링크를 사용하려면 새 QR 코드를 만드세요.
* **`data`.** `data` 또는 `qrType`이 바뀔 때만 결과 유형에 맞는지 검사됩니다. 일치하는 `data` 없이 `qrType`을 바꾸면 거부됩니다. [유형 변경](https://docs.getqr.com/ko/api/guides/qr-types.md#유형-변경)을 참조하세요.
* **디자인.** `styles`, `frameOptions`, `logoOptions`는 저장된 디자인에 병합되므로 일부만 담은 객체는 지정한 항목만 변경합니다. 다른 로고를 고르면 로고는 교체되지만 크기는 유지됩니다.
* **`access`.** 각 키는 있을 때만 적용됩니다. `null`은 규칙을 지웁니다. 접근 규칙은 `access` 아래에 넣어야 하며, `link` 아래에 보내면 `422`를 반환합니다.
* **`archived`.** [일시 중지](#qr-코드-일시-중지), [재활성화](#qr-코드-재활성화)와 마찬가지로 QR 코드와 단축 링크를 함께 일시 중지하거나 재활성화합니다.

```bash cURL theme={null}
curl -X PATCH "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Autumn campaign",
    "access": { "password": "s3cr3t", "passwordProtected": true }
  }'
```

```json 200 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "title": "Autumn campaign",
  "access": { "passwordProtected": true, "activeAt": null, "pauseAt": null, "scanLimit": null },
  "…": "…"
}
```

유형별로 인쇄 후에 변경할 수 있는 항목은 [유형별 QR 코드 데이터](https://docs.getqr.com/ko/api/guides/qr-types.md)에 나와 있습니다.

## 일시 중지 상태 설정

`PUT /api/v1/qrs/{qrId}`

일시 중지 상태를 직접 설정합니다. [일시 중지](#qr-코드-일시-중지)와 [재활성화](#qr-코드-재활성화)도 같은 일을 하며 의도가 더 분명하게 드러납니다.

**qrId** `string` *required*

QR 코드의 ID입니다.

**archived** `boolean` *required*

QR 코드를 일시 중지하려면 `true`, 재활성화하려면 `false`입니다.

```bash cURL theme={null}
curl -X PUT "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'
```

```json 200 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}
```

## QR 코드 일시 중지

`POST /api/v1/qrs/{qrId}/pause`

QR 코드가 목적지로 연결되지 않도록 합니다. 스캔하면 대신 일시 중지 페이지가 표시됩니다. 인쇄된 코드와 단축 링크는 계속 유효합니다. 요청 본문은 없습니다.

**qrId** `string` *required*

QR 코드의 ID입니다.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}
```

## QR 코드 재활성화

`POST /api/v1/qrs/{qrId}/activate`

일시 중지된 QR 코드가 다시 목적지로 연결되도록 합니다. 일정과 스캔 제한은 계속 적용됩니다. 요청 본문은 없습니다.

**qrId** `string` *required*

QR 코드의 ID입니다.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/activate" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": false,
  "…": "…"
}
```

## QR 코드 복제

`POST /api/v1/qrs/{qrId}/duplicate`

같은 콘텐츠와 디자인을 가진 복사본을 만듭니다. 요청 본문은 없습니다. 새 [QR 코드](#qr-코드-객체)와 함께 `201 Created`를 반환합니다.

**qrId** `string` *required*

복사할 QR 코드의 ID입니다.

* **단축 링크.** 복사본에는 별도의 단축 링크가 생깁니다. 슬러그는 무작위이고, 도메인은 원본의 도메인이 아니라 워크스페이스의 기본 도메인입니다. 스캔은 따로 집계됩니다.
* **제목.** 제목 뒤에 ` (Copy)`가 붙습니다. 결과는 40자를 넘지 않으며, 긴 제목은 먼저 줄어듭니다. 제목 없는 QR 코드는 제목 없는 상태로 유지됩니다.
* **복사되지 않는 항목.** 접근 규칙(비밀번호, 일정, 스캔 제한)과 일시 중지 상태입니다. 복사본은 항상 활성 상태입니다.
* **파일.** PDF와 이미지 파일(번들과 갤러리 파일 포함)은 복사되어 복사본이 소유합니다. 동영상 파일과 로고 같은 디자인 파일은 원본과 공유됩니다.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/duplicate" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 201 theme={null}
{
  "id": "qr_7Hk2PqWmX9cTnV4sLbR8YdZe",
  "title": "Landing page (Copy)",
  "shortLink": "https://getqr.sh/p2Wq9dL",
  "url": "https://example.com",
  "archived": false,
  "scans": 0,
  "…": "…"
}
```

## QR 코드 삭제

`DELETE /api/v1/qrs/{qrId}`

QR 코드와 단축 링크를 삭제합니다. 삭제된 ID를 반환합니다.

> [!WARNING]
>
> 삭제는 영구적입니다. 인쇄된 코드와 단축 링크가 작동을 멈추고, 스캔 기록에도 더 이상 접근할 수 없습니다. 다시 필요할 수 있다면 대신 QR 코드를 [일시 중지](#qr-코드-일시-중지)하세요.

**qrId** `string` *required*

QR 코드의 ID입니다.

**id** `string`

삭제된 QR 코드의 ID입니다.

**deleted** `boolean`

항상 `true`입니다.

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{ "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf", "deleted": true }
```

## QR 코드 이미지 다운로드

`GET /api/v1/qrs/{qrId}/download`

QR 코드를 디자인대로 렌더링하여 파일을 반환합니다.

**qrId** `string` *required*

렌더링할 QR 코드의 ID로, 목록 조회 또는 생성 응답에서 가져옵니다.

**format** `string` (default: jpg)

출력 형식: `jpg`, `png`, `svg`, `pdf`(A4 페이지), `eps`. Branded design과 AI design은 `jpg`, `png`, `pdf`로만 다운로드됩니다.

**resolution** `integer` (default: 1024)

픽셀 단위 이미지 크기: `1024`, `2048`, `4096`. `svg`와 `pdf`는 이 값을 무시합니다. Branded design과 AI design은 `1024`로만 다운로드됩니다.

| `format` | `Content-Type` | 파일 이름 |
| - | - | - |
| `jpg` | `image/jpeg` | `<title>-<resolution>px.jpg` |
| `png` | `image/png` | `<title>-<resolution>px.png` |
| `svg` | `image/svg+xml` | `<title>.svg` |
| `pdf` | `application/pdf` | `<title>.pdf` |
| `eps` | `application/postscript` | `<title>-<resolution>px.eps` |

* **본문.** 응답 본문은 파일입니다. 권장 파일 이름은 `Content-Disposition` 헤더에 있으며, 제목으로 만들어지고 제목 없는 QR 코드는 `qr-code`입니다.
* **캐싱.** 응답에는 `ETag`와 `Cache-Control: private, max-age=3600, must-revalidate`가 담깁니다. `ETag`를 `If-None-Match`로 다시 보내면 QR 코드가 바뀌지 않았을 때 `304 Not Modified`를 받습니다.
* **오류.** 지원하지 않는 형식이나 해상도는 `400 bad_request`를 반환합니다. 오류 메시지에 이유가 표시됩니다: `qr_download_invalid_format`, `qr_download_invalid_resolution`, `qr_download_art_format_unsupported`, `qr_download_art_resolution_unsupported`.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png
```

```http 200 theme={null}
HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="landing-page-1024px.png"
ETag: "9f2c0e1b5a7d43c8b016e2f4a9d5c3718be40f92"
Cache-Control: private, max-age=3600, must-revalidate

<binary image data>
```

## 접근 규칙

생성 또는 업데이트 시 `access` 객체를 보내면 시작과 종료를 예약하고, 스캔 수를 제한하고, 비밀번호를 요구할 수 있습니다. 생략한 규칙은 변경되지 않으며, `null`은 규칙을 지웁니다. 예시를 포함한 전체 동작은 [접근 규칙](https://docs.getqr.com/ko/api/guides/access-rules.md)에 있습니다.

## 디자인 객체

`styles`, `frameOptions`, `logoOptions`는 점과 모서리 모양, 색상, 프레임, 로고를 설정합니다. QR 코드, [템플릿](https://docs.getqr.com/ko/api/endpoints/templates.md), [대량 생성](https://docs.getqr.com/ko/api/endpoints/bulk-qr-creations.md)에서 똑같이 작동합니다. 알 수 없는 모양, 프레임, 로고는 거부됩니다. 허용되는 모든 값과 실제 예시는 [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md)에 있습니다.

## 자주 발생하는 문제

> [accordion] 비밀번호, 일정, 스캔 제한을 설정하면 422가 반환됩니다
>
> 규칙은 `link` 아래가 아니라 `access` 아래에 보내세요.

> [accordion] link.domain 또는 link.key를 변경하면 422가 반환됩니다
>
> 인쇄된 코드가 단축 링크를 인코딩하므로 생성 후에는 단축 링크를 바꿀 수 없습니다. 대신 새 QR 코드를 만드세요.

> [accordion] 422 "Expected … for qrType"
>
> `data`가 `qrType`의 형식과 맞지 않습니다. [유형별 QR 코드 데이터](https://docs.getqr.com/ko/api/guides/qr-types.md)에서 유형을 확인하세요.

> [accordion] QR 코드를 만들 때 409 conflict가 반환됩니다
>
> 동일한 생성 요청이 아직 처리 중이거나 `link.key`가 이미 사용 중입니다. 첫 번째 요청이 끝난 뒤 다시 시도하세요. `Idempotency-Key`가 있으면 재시도 시 원래 QR 코드가 반환됩니다.

> [accordion] PNG가 아니라 JPEG로 다운로드됩니다
>
> 매개변수는 `format`과 `resolution`이며, `format`의 기본값은 `jpg`입니다. `format=png`를 보내세요.

> [accordion] 대시보드에 보이는 QR 코드인데 404가 반환됩니다
>
> 모든 요청은 API 키의 워크스페이스에서 실행됩니다. QR 코드가 해당 워크스페이스에 속하는지 확인하세요. [인증](https://docs.getqr.com/ko/api/authentication.md)을 참조하세요.

## 다음 단계

> [card] [유형별 QR 코드 데이터](https://docs.getqr.com/ko/api/guides/qr-types.md)

> [card] [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md)

> [card] [접근 규칙](https://docs.getqr.com/ko/api/guides/access-rules.md)

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


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