> ## 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는 베타 버전이며 일부 워크스페이스에서만 사용할 수 있습니다. 정식 출시 전에 세부 사항이 변경될 수 있습니다.

템플릿에는 재사용할 수 있는 디자인(`styles`, `frameOptions`, `logoOptions`)이 저장됩니다. 콘텐츠나 링크는 담기지 않습니다. 템플릿은 워크스페이스의 모든 사람이 공유합니다.

| 메서드 | 경로 | 설명 |
| - | - | - |
| `GET` | `/api/v1/templates` | [템플릿 목록 조회](#템플릿-목록-조회) |
| `POST` | `/api/v1/templates` | [템플릿 생성](#템플릿-생성) |
| `GET` | `/api/v1/templates/{templateId}` | [템플릿 조회](#템플릿-조회) |
| `PATCH` | `/api/v1/templates/{templateId}` | [템플릿 업데이트](#템플릿-업데이트) |
| `DELETE` | `/api/v1/templates/{templateId}` | [템플릿 삭제](#템플릿-삭제) |
| `POST` | `/api/v1/templates/{templateId}/duplicate` | [템플릿 복제](#템플릿-복제) |

## 템플릿 적용

[QR 코드를 생성](https://docs.getqr.com/ko/api/endpoints/qr-codes.md)할 때 `templateId`를 전달하세요. 템플릿의 디자인이 새 QR 코드에 적용됩니다. 같은 요청에서 세 디자인 객체 중 하나라도 보내면 템플릿 위에 병합됩니다.

* **연결이 아닌 복사.** QR 코드는 디자인의 사본을 따로 가집니다. 나중에 템플릿을 수정하거나 삭제해도 QR 코드는 바뀌지 않습니다.
* **사용자 지정 디자인만.** `designKind`가 `branded` 또는 `ai`인 템플릿은 API로 적용할 수 없으며 `422`(`art_template_unsupported`)를 반환합니다.
* **내 워크스페이스만.** 알 수 없는 템플릿이나 다른 워크스페이스의 템플릿은 `404`를 반환합니다.

## 헤더

**Authorization** `string` *required*

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

**Content-Type** `string`

`application/json`. 본문이 있는 요청에서는 필수입니다.

## 템플릿 객체

**id** `string`

템플릿의 ID입니다. 예: `qrt_8Hs2mQvKpLd4RtYw`.

**name** `string`

템플릿을 고를 때 표시되는 이름입니다.

**designKind** `string`

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

**design** `object`

저장된 디자인입니다. 각 필드는 같은 이름의 요청 필드와 구조가 같으므로 그대로 다시 보낼 수 있습니다.

**properties**

**styles** `object | null`

점과 모서리의 모양과 색상입니다.

**frameOptions** `object | null`

QR 코드를 감싸는 프레임과 행동 유도 문구입니다.

**logoOptions** `object | null`

중앙의 로고입니다.

**createdAt** `string`

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

**updatedAt** `string`

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

## 템플릿 목록 조회

`GET /api/v1/templates`

워크스페이스의 템플릿을 최신순으로 반환합니다. 목록은 페이지로 나뉩니다. [페이지네이션](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/templates?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "qrt_8Hs2mQvKpLd4RtYw",
      "name": "Brand blue",
      "designKind": "custom",
      "design": {
        "styles": {
          "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
          "backgroundOptions": { "color": "#FFFFFF" }
        },
        "frameOptions": null,
        "logoOptions": null
      },
      "createdAt": "2026-07-20T09:12:00.000Z",
      "updatedAt": "2026-07-20T09:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}
```

## 템플릿 생성

`POST /api/v1/templates`

새 디자인을 저장합니다. `201 Created`를 반환합니다. 디자인 필드는 [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md)의 카탈로그와 대조되므로 알 수 없는 모양, 프레임, 로고는 `422`로 거부됩니다.

**name** `string` *required*

템플릿을 고를 때 표시되는 이름으로, 1\~40자입니다.

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

중앙에 배치할 로고입니다. 추천 로고 또는 [파일](https://docs.getqr.com/ko/api/endpoints/files.md)의 `logo` 용도로 업로드한 직접 만든 파일을 사용합니다. [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md)을 참조하세요.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/templates" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand blue",
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    }
  }'
```

```json 201 theme={null}
{
  "id": "qrt_8Hs2mQvKpLd4RtYw",
  "name": "Brand blue",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-07-20T09:12:00.000Z",
  "updatedAt": "2026-07-20T09:12:00.000Z"
}
```

## 템플릿 조회

`GET /api/v1/templates/{templateId}`

**templateId** `string` *required*

템플릿의 ID입니다. 목록 조회 또는 생성 응답에서 가져오세요.

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

```json 200 theme={null}
{
  "id": "qrt_8Hs2mQvKpLd4RtYw",
  "name": "Brand blue",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-07-20T09:12:00.000Z",
  "updatedAt": "2026-07-20T09:12:00.000Z"
}
```

## 템플릿 업데이트

`PATCH /api/v1/templates/{templateId}`

변경할 필드만 보내세요. 디자인 객체는 저장된 디자인에 병합되므로 일부만 담은 `styles`를 보내도 나머지는 유지됩니다. 템플릿으로 이미 만든 QR 코드는 만들 때의 디자인을 유지합니다.

**templateId** `string` *required*

템플릿의 ID입니다.

**name** `string`

새 이름으로, 1\~40자입니다.

**styles** `object`

스타일 변경 사항으로, 저장된 `styles`에 병합됩니다.

**frameOptions** `object`

프레임 변경 사항으로, 저장된 프레임에 병합됩니다.

**logoOptions** `object`

로고 변경 사항으로, 저장된 로고에 병합됩니다.

```bash cURL theme={null}
curl -X PATCH "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Brand blue (2026)" }'
```

```json 200 theme={null}
{
  "id": "qrt_8Hs2mQvKpLd4RtYw",
  "name": "Brand blue (2026)",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-07-20T09:12:00.000Z",
  "updatedAt": "2026-08-14T09:00:00.000Z"
}
```

## 템플릿 삭제

`DELETE /api/v1/templates/{templateId}`

템플릿을 삭제합니다. 템플릿으로 만든 QR 코드는 디자인을 유지합니다.

**templateId** `string` *required*

템플릿의 ID입니다.

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

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

## 템플릿 복제

`POST /api/v1/templates/{templateId}/duplicate`

`<name> copy`라는 이름의 사본을 만듭니다. 사본은 별도의 ID와 독립된 디자인을 가지므로 자유롭게 수정할 수 있습니다. 요청 본문은 없습니다. `201 Created`를 반환합니다.

**templateId** `string` *required*

복사할 템플릿의 ID입니다.

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

```json 201 theme={null}
{
  "id": "qrt_2Kd9pLm4Xs7BnVcQ",
  "name": "Brand blue copy",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-08-14T09:30:00.000Z",
  "updatedAt": "2026-08-14T09:30:00.000Z"
}
```

## 자주 발생하는 문제

> [accordion] 404 "QR template not found."
>
> 해당 `templateId`가 워크스페이스의 템플릿과 일치하지 않습니다. [템플릿 목록 조회](#템플릿-목록-조회)에서 가져오세요.

> [accordion] 템플릿을 만들거나 업데이트할 때 422가 반환됩니다
>
> 디자인 필드가 카탈로그와 맞지 않습니다. 예를 들어 알 수 없는 점 유형, 프레임, 추천 로고입니다. 메시지에 필드 이름이 표시됩니다. [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md)을 참조하세요.

> [accordion] QR 코드 생성 시 422 art\_template\_unsupported
>
> 템플릿이 Branded design 또는 AI design을 사용합니다. 대신 `designKind`가 `custom`인 템플릿을 적용하세요.

## 다음 단계

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

> [card] [QR 코드](https://docs.getqr.com/ko/api/endpoints/qr-codes.md)

> [card] [앱의 템플릿](https://docs.getqr.com/ko/templates/save-template.md)

> [card] [파일](https://docs.getqr.com/ko/api/endpoints/files.md)


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