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

# 맞춤 설정

> API로 QR 코드의 스타일을 설정하세요. 점과 모서리 모양, 색상, 프레임, 로고.

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

QR 코드를 만들거나 업데이트할 때 선택적 `styles`, `frameOptions`, `logoOptions` 객체로 스타일을 설정하세요. 모든 필드는 선택 사항이며, 생략한 항목에는 기본값이 적용됩니다.

이 세 객체는 [QR 코드](https://docs.getqr.com/ko/api/endpoints/qr-codes.md), [템플릿](https://docs.getqr.com/ko/api/endpoints/templates.md), [대량 생성](https://docs.getqr.com/ko/api/endpoints/bulk-qr-creations.md)에서 똑같이 작동합니다. 알 수 없는 모양, 프레임, 로고는 `422`로 거부됩니다.

## 디자인 객체 예시

```json theme={null}
{
  "styles": {
    "dotsOptions": { "type": "rounded", "color": "#000000" },
    "backgroundOptions": { "color": "#ffffff" },
    "cornersSquareOptions": { "type": "dot", "color": "#000000" },
    "cornersDotOptions": { "type": "dot", "color": "#000000" }
  },
  "frameOptions": { "id": "card", "text": "Scan me!", "color": "#000000", "textColor": "#ffffff" },
  "logoOptions": { "type": "suggested", "id": "logo-google", "scalePercent": 25 }
}
```

QR 코드의 나머지 필드와 함께 보내세요.

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" } },
    "frameOptions": { "id": "card", "text": "Scan me!" },
    "logoOptions": { "type": "suggested", "id": "logo-website-3" }
  }'
```

## 스타일

`styles` 객체는 패턴의 모양과 색상을 설정합니다.

| 필드 | 값 |
| - | - |
| `dotsOptions.type` | 본체 점의 모양: `square`, `dots`, `rounded`, `classy`, `classy-rounded`, `extra-rounded` |
| `cornersSquareOptions.type` | 모서리 사각형(눈 테두리) 모양: `square`, `rounded`, `dot`, `classy-rounded` |
| `cornersDotOptions.type` | 모서리 점(눈동자) 모양: `square`, `dot`, `dots`, `rounded`, `classy` |
| `dotsOptions.color` | 전경색입니다. 기본값은 `#000000`입니다. |
| `backgroundOptions.color` | 배경색입니다. 기본값은 `#ffffff`입니다. |
| `cornersSquareOptions.color`, `cornersDotOptions.color` | 받기는 하지만 효과가 없습니다. 모서리에는 항상 `dotsOptions.color`가 사용됩니다. |

* **색상.** 16진수 값만 사용합니다: `#RGB` 또는 `#RRGGBB`.
* **오류 정정.** 항상 `Q`이며 입력 항목이 아닙니다. `styles.qrOptions`를 보내면 `422`를 반환합니다.
* **Branded design과 AI design.** API로는 설정할 수 없습니다. `styles.logoQrArt`를 보내면 `422`를 반환합니다.
* **콘텐츠.** `styles.data`는 무시됩니다. 이미지는 항상 QR 코드의 콘텐츠를 인코딩합니다.

> [!TIP]
>
> 밝은 배경에 어두운 전경을 사용하여 전경색과 배경색의 대비를 충분히 유지하세요. 대비가 낮은 코드는 스캔되지 않을 수 있습니다. [색상](https://docs.getqr.com/ko/design/colors.md)을 참조하세요.

## 프레임

`frameOptions` 객체는 QR 코드 주위에 행동 유도 문구가 있는 장식 프레임을 추가합니다.

| 필드 | 설명 |
| - | - |
| `id` | `frameOptions`를 보낼 때 필수입니다. 아래 목록의 프레임 유형입니다. `none`은 프레임 없음을 뜻합니다. |
| `text` | 행동 유도 문구 레이블로, 최대 12자입니다. 기본값은 `Scan me!`입니다. |
| `color` | 프레임 색상(16진수)입니다. |
| `textColor` | 레이블 색상(16진수)입니다. 프레임에 레이블이 표시되면 `color`와 달라야 합니다. 단, 이 조합이 프레임에 내장된 색상 프리셋이면 예외입니다. |
| `borderColor` | 테두리 색상(16진수)입니다. |
| `fingerPrintColor` | 프레임 아이콘의 강조 색상(16진수)입니다. |

> [accordion] 일반 프레임
>
> `none`, `card`, `card-1`, `card-2`, `card-3`, `card-4`, `card-5`, `card-7`, `card-8`, `card-9`, `card-10`, `card-11`, `card-12`, `card-13`, `card-14`, `card-15`, `card-hor`, `wreath`, `envelope`, `waitress`, `coffee-cup`, `scooter`, `clipboard`
>
> `card-hor`에는 레이블이 표시되지 않습니다.

> [accordion] QR 코드 유형별 프레임
>
> | 유형 | 레이블이 있는 프레임 | 레이블이 없는 프레임 |
> | - | - | - |
> | App Link | `app-3` | `app-1`, `app-2` |
> | vCard | `contact-1`, `contact-5` | `contact-2`, `contact-3`, `contact-4` |
> | Email | `email-1` | `email-2`, `email-3`, `email-4`, `email-5` |
> | Feedback | — | `feedback-1`, `feedback-2`, `feedback-3`, `feedback-4`, `feedback-5` |
> | Image | — | `image-1`, `image-2`, `image-3`, `image-4`, `image-5`, `image-6` |
> | Location | `location-3` | `location-1`, `location-2`, `location-4`, `location-5`, `location-6` |
> | Multi-Link | `multilink-3` | `multilink-1`, `multilink-2` |
> | Payment | — | `payment-1`, `payment-2`, `payment-3`, `payment-4`, `payment-5` |
> | PDF | `pdf-1` | `pdf-2`, `pdf-3`, `pdf-4` |
> | SMS | `sms-3`, `sms-5`, `sms-7` | `sms-1`, `sms-2`, `sms-4`, `sms-6` |
> | Social Media | `social-3` | `social-1`, `social-2`, `social-4` |
> | Video | `video-1`, `video-3` | `video-2`, `video-4`, `video-5`, `video-6` |
> | Website | `website-1` | `website-2`, `website-3`, `website-4`, `website-5` |
> | WhatsApp | `whatsapp-2` | `whatsapp-1`, `whatsapp-3`, `whatsapp-4` |
> | WiFi | — | `wifi-1`, `wifi-2`, `wifi-3`, `wifi-4` |
>
> 모든 프레임은 모든 QR 코드 유형에 사용할 수 있습니다. 그룹 구분은 대시보드와 같습니다.

레이블이 없는 프레임에는 대시보드에 행동 유도 문구 입력란이 없으며, `textColor`가 `color`와 달라야 한다는 규칙도 적용되지 않습니다.

## 로고

`logoOptions` 객체는 QR 코드 중앙에 로고를 배치합니다. 로고 종류는 `type`으로 선택하세요.

### 추천 로고

`type`을 `suggested`로 설정하고 카탈로그에서 `id`를 고르세요. 로고를 넣지 않으려면 `logo-none`을 사용하세요.

```json theme={null}
{ "logoOptions": { "type": "suggested", "id": "logo-instagram", "scalePercent": 25 } }
```

> [accordion] 전체 추천 로고 ID
>
> `logo-none`, `logo-website-3`, `logo-website-4`, `logo-link`, `logo-pdf-1`, `logo-pdf-2`, `logo-pdf-3`, `logo-picture-1`, `logo-picture-2`, `logo-picture-3`, `logo-picture-5`, `logo-picture-7`, `logo-picture-8`, `logo-video-1`, `logo-video-5`, `logo-whatsapp-1`, `logo-whatsapp-2`, `logo-whatsapp`, `logo-wifi-1`, `logo-wifi-2`, `logo-wifi-3`, `logo-wifi`, `logo-airbnb`, `logo-apple`, `logo-binance`, `logo-bitcoin`, `logo-bolt-food`, `logo-booking`, `logo-facebook`, `logo-glovo`, `logo-google`, `logo-google-maps`, `logo-google-play`, `logo-instagram`, `logo-linkedin`, `logo-location`, `logo-mail`, `logo-paypal`, `logo-stripe`, `logo-venmo`, `logo-cashapp`, `logo-braintree`, `logo-square`, `logo-verifone`, `logo-google-pay`, `logo-apple-pay`, `logo-klarna`, `logo-ayden`, `logo-giropay`, `logo-cartes-bancaires`, `logo-restaurant`, `logo-scan-me`, `logo-tripadvisor`, `logo-trustpilot`, `logo-uber-eats`, `logo-youtube`, `logo-spotify`, `logo-spotify-black`

### 직접 만든 로고

**1. 이미지 업로드**

[파일](https://docs.getqr.com/ko/api/endpoints/files.md)에서 `"target": "logo"`로 등록한 다음, 반환된 `uploadUrl`로 파일을 업로드합니다.

**2. 파일 참조**

`type`을 `uploaded`로, `fileId`를 반환된 `fileId`로 설정합니다. `fileId`는 필수이며 Files 엔드포인트가 반환한 ID여야 합니다.

```json theme={null}
{ "logoOptions": { "type": "uploaded", "fileId": "file_7bQ2xR9mKp", "scalePercent": 35 } }
```

알 수 없는 파일, 업로드가 완료되지 않은 파일, 다른 용도로 업로드한 파일은 거부됩니다.

### 로고 크기

`scalePercent`는 QR 코드 대비 로고 크기를 백분율로 설정합니다. 15부터 45까지의 정수를 받습니다. 기본값은 25입니다. `0.25` 같은 비율을 포함하여 그 밖의 값은 `422`를 반환합니다.

## 디자인 업데이트

* **부분 업데이트.** [QR 코드 업데이트](https://docs.getqr.com/ko/api/endpoints/qr-codes.md#qr-코드-업데이트)에서 `styles`, `frameOptions`, `logoOptions`는 저장된 디자인에 병합됩니다. 일부만 담은 객체는 지정한 항목만 변경합니다.
* **로고 변경.** 다른 로고를 고르면 저장된 로고가 교체되지만 `scalePercent`는 유지됩니다.
* **템플릿.** 생성 시 `templateId`를 지정하면 보낸 필드가 템플릿 디자인 위에 병합됩니다. [템플릿](https://docs.getqr.com/ko/api/endpoints/templates.md)을 참조하세요.
* **Branded design과 AI design.** `designKind`가 `branded` 또는 `ai`인 QR 코드는 대시보드에서 만든 것입니다. API로는 그 이미지를 수정할 수 없지만, 다른 필드를 변경해도 이미지는 유지됩니다.
* **디자인 읽기.** 응답은 저장된 디자인을 요청 필드와 같은 구조로 `design`에 담아 반환하므로 그대로 다시 보낼 수 있습니다.

## 자주 발생하는 문제

> [accordion] 422 "Error correction is always Q and is not an input"
>
> 요청에서 `styles.qrOptions`를 제거하세요.

> [accordion] 422 "Frame caption is at most 12 characters"
>
> `frameOptions.text`를 12자 이하로 줄이세요.

> [accordion] 422 "Frame caption color must differ from the frame color"
>
> 레이블이 표시되는 프레임에서 `textColor`와 `color`가 같습니다. 대비되는 `textColor`를 고르세요.

> [accordion] 422 "Logo scale is a whole number from 15 to 45"
>
> `scalePercent`는 정수 백분율로 보내세요. 예를 들어 `0.25`가 아니라 `25`입니다.

> [accordion] 모서리 색상이 바뀌지 않습니다
>
> 모서리에는 항상 `dotsOptions.color`가 사용됩니다. `cornersSquareOptions.color`와 `cornersDotOptions.color`는 효과가 없습니다.

## 다음 단계

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

> [card] [템플릿](https://docs.getqr.com/ko/api/endpoints/templates.md)

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

> [card] [디자인 개요](https://docs.getqr.com/ko/design/overview.md)


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