템플릿

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

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

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

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

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 코드를 생성할 때 templateId를 전달하세요. 템플릿의 디자인이 새 QR 코드에 적용됩니다. 같은 요청에서 세 디자인 객체 중 하나라도 보내면 템플릿 위에 병합됩니다.

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

헤더

string

필수

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

string

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

템플릿 객체

string

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

string

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

string

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

object

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

표시 properties

object | null

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

object | null

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

object | null

중앙의 로고입니다.

string

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

string

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

템플릿 목록 조회

GET /api/v1/templates 워크스페이스의 템플릿을 최신순으로 반환합니다. 목록은 페이지로 나뉩니다. 페이지네이션을 참조하세요.

integer

기본값:"1"

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

integer

기본값:"100"

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

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

{
  "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를 반환합니다. 디자인 필드는 맞춤 설정의 카탈로그와 대조되므로 알 수 없는 모양, 프레임, 로고는 422로 거부됩니다.

string

필수

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

object

점과 모서리의 모양과 색상입니다. 맞춤 설정을 참조하세요.

object

QR 코드를 감싸는 프레임과 행동 유도 문구입니다. 맞춤 설정을 참조하세요.

object

중앙에 배치할 로고입니다. 추천 로고 또는 파일의 logo 용도로 업로드한 직접 만든 파일을 사용합니다. 맞춤 설정을 참조하세요.

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

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

string

필수

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

curl "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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 코드는 만들 때의 디자인을 유지합니다.

string

필수

템플릿의 ID입니다.

string

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

object

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

object

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

object

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

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

{
  "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 코드는 디자인을 유지합니다.

string

필수

템플릿의 ID입니다.

curl -X DELETE "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw" \
  -H "Authorization: Bearer $GETQR_API_KEY"

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

템플릿 복제

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

string

필수

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

curl -X POST "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw/duplicate" \
  -H "Authorization: Bearer $GETQR_API_KEY"

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

자주 발생하는 문제

404 "QR template not found."

해당 templateId가 워크스페이스의 템플릿과 일치하지 않습니다. 템플릿 목록 조회에서 가져오세요.

템플릿을 만들거나 업데이트할 때 422가 반환됩니다

디자인 필드가 카탈로그와 맞지 않습니다. 예를 들어 알 수 없는 점 유형, 프레임, 추천 로고입니다. 메시지에 필드 이름이 표시됩니다. 맞춤 설정을 참조하세요.

QR 코드 생성 시 422 art_template_unsupported

템플릿이 Branded design 또는 AI design을 사용합니다. 대신 designKind가 custom인 템플릿을 적용하세요.

API

템플릿 적용

헤더

템플릿 객체

템플릿 목록 조회

템플릿 생성

템플릿 조회

템플릿 업데이트

템플릿 삭제

템플릿 복제

자주 발생하는 문제

다음 단계

맞춤 설정

QR 코드

앱의 템플릿

파일

​템플릿 적용

​헤더

​템플릿 객체

​템플릿 목록 조회

​템플릿 생성

​템플릿 조회

​템플릿 업데이트

​템플릿 삭제

​템플릿 복제

​자주 발생하는 문제

​다음 단계

맞춤 설정

QR 코드

앱의 템플릿

파일

템플릿 적용

헤더

템플릿 객체

템플릿 목록 조회

템플릿 생성

템플릿 조회

템플릿 업데이트

템플릿 삭제

템플릿 복제

자주 발생하는 문제

다음 단계