맞춤 설정

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

QR 코드를 만들거나 업데이트할 때 선택적 styles, frameOptions, logoOptions 객체로 스타일을 설정하세요. 모든 필드는 선택 사항이며, 생략한 항목에는 기본값이 적용됩니다. 이 세 객체는 QR 코드, 템플릿, 대량 생성에서 똑같이 작동합니다. 알 수 없는 모양, 프레임, 로고는 422로 거부됩니다.

디자인 객체 예시

{
  "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 코드의 나머지 필드와 함께 보내세요.

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 코드의 콘텐츠를 인코딩합니다.

밝은 배경에 어두운 전경을 사용하여 전경색과 배경색의 대비를 충분히 유지하세요. 대비가 낮은 코드는 스캔되지 않을 수 있습니다. 색상을 참조하세요.

프레임

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

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

일반 프레임

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, clipboardcard-hor에는 레이블이 표시되지 않습니다.

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으로 선택하세요.

직접 만든 로고

이미지 업로드

파일에서 "target": "logo"로 등록한 다음, 반환된 uploadUrl로 파일을 업로드합니다.

파일 참조

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

{ "logoOptions": { "type": "uploaded", "fileId": "file_7bQ2xR9mKp", "scalePercent": 35 } }

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

로고 크기

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

디자인 업데이트

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

자주 발생하는 문제

422 "Error correction is always Q and is not an input"

요청에서 styles.qrOptions를 제거하세요.

422 "Frame caption is at most 12 characters"

frameOptions.text를 12자 이하로 줄이세요.

422 "Frame caption color must differ from the frame color"

레이블이 표시되는 프레임에서 textColor와 color가 같습니다. 대비되는 textColor를 고르세요.

422 "Logo scale is a whole number from 15 to 45"

scalePercent는 정수 백분율로 보내세요. 예를 들어 0.25가 아니라 25입니다.

모서리 색상이 바뀌지 않습니다

모서리에는 항상 dotsOptions.color가 사용됩니다. cornersSquareOptions.color와 cornersDotOptions.color는 효과가 없습니다.

API

디자인 객체 예시

스타일

프레임

로고

추천 로고

직접 만든 로고

로고 크기

디자인 업데이트

자주 발생하는 문제

다음 단계

QR 코드

템플릿

파일

디자인 개요

​디자인 객체 예시

​스타일

​프레임

​로고

​추천 로고

​직접 만든 로고

​로고 크기

​디자인 업데이트

​자주 발생하는 문제

​다음 단계

QR 코드

템플릿

파일

디자인 개요

디자인 객체 예시

스타일

프레임

로고

추천 로고

직접 만든 로고

로고 크기

디자인 업데이트

자주 발생하는 문제

다음 단계