> ## 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 코드 데이터 > 16가지 QR 코드 유형별 데이터 형식, 요청 예시, 인쇄 후 수정 가능 여부. > [!NOTE] > > GetQR API는 베타 버전이며 일부 워크스페이스에서만 사용할 수 있습니다. 정식 출시 전에 세부 사항이 변경될 수 있습니다. 모든 QR 코드에는 `qrType`이 있으며, 유형에 따라 `data`에 담아야 할 내용이 정해집니다. 이 가이드에서는 모든 유형의 형식, 그대로 사용할 수 있는 요청 본문, 코드를 인쇄한 후에도 변경할 수 있는 항목을 설명합니다. 예시는 [QR 코드 생성](https://docs.getqr.com/ko/api/endpoints/qr-codes.md#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/menu", "title": "Menu" }' ``` ## 전체 유형 한눈에 보기 | `qrType` | `data` | 인쇄 후 수정 | | - | - | - | | [`website`](#website) | http(s) URL | 가능 | | [`feedback`](#feedback) | 양식의 http(s) URL | 가능 | | [`payment`](#payment) | 결제 서비스 URL | 가능 | | [`whatsapp`](#whatsapp) | `wa.me` 링크 | 가능 | | [`location`](#location) | 지도 URL | 가능 | | [`app`](#app-link) | 스토어 URL 또는 빈 값, 그리고 `link.ios` / `link.android` | 가능 | | [`email`](#email) | `mailto:` URI | 가능 | | [`sms`](#sms) | `sms:` URI | 가능 | | [`wifi`](#wifi) | `WIFI:` 페이로드 | **불가** | | [`pdf`, `image`, `video`](#pdf와-image와-video) | 빈 값, `fileId` 사용 | 가능 | | [`vcard`](#vcard) | vCard 3.0 텍스트 | 가능 | | [`social`](#social-media) | JSON 문자열 | 가능 | | [`multilink`](#multi-link) | JSON 문자열 | 가능 | | [`event`](#event) | JSON 문자열 | 가능 | ## QR 코드가 연결되는 방식 모든 QR 코드는 단축 링크와 페이로드로 이루어집니다. 콘텐츠를 담는 필드는 두 가지입니다. | 필드 | 의미 | | - | - | | `link.url` | 단축 링크가 방문자를 보내는 곳입니다. `wifi`를 제외한 모든 유형에서 이것이 실제 목적지입니다. | | `data` | 유형의 페이로드로, `qrType`에 맞는지 검사됩니다. 보낸 그대로 저장되는 유형은 `wifi`, `vcard`, `social`, `multilink`, `event`, `sms`뿐입니다. 나머지 유형에서는 `link.url`을 제공하는 용도로만 쓰이며, 저장되는 `data`는 단축 링크가 됩니다. 목적지는 응답의 `url`에서 읽으세요. | 모든 유형에 적용되는 규칙: * **기본값.** 생성 시 `link.url`을 생략하거나 비워 두면 `data`가 사용되며, `link` 객체 전체를 생략해도 됩니다. 둘 다 보냈는데 값이 다르면 `link.url`이 우선합니다. 같은 값을 보내거나 `data`만 보내세요. * **이미지에 인코딩되는 내용.** `wifi`를 제외한 모든 유형에서 이미지는 단축 링크를 인코딩합니다. 따라서 인쇄된 코드의 목적지를 바꿀 수 있고 스캔도 추적됩니다. WiFi QR 코드는 네트워크 자체를 인코딩하므로 인쇄 후에는 변경할 수 없고 스캔도 추적되지 않습니다. * **스킴.** `link.url`은 `http:`, `https:`, `wifi:`, `mailto:`, `sms:`, `begin:`만 받습니다. `geo:`, `smsto:`, `matmsg:`, `tel:`을 포함한 그 밖의 스킴은 `data`에서 허용되더라도 `422 Invalid destination URL`을 반환합니다. * **빈 data.** `data`가 비어 있으면 유형 검사를 건너뜁니다. 이때 리디렉션 유형은 `link.url`을 설정해야 하며, 그렇지 않으면 `400 Missing destination URL`을 반환합니다. * **구조.** 서버는 유형 검사 외에는 페이로드를 검증하지 않습니다. JSON 유형은 JSON 객체로 파싱되기만 하면 되고, vCard는 `BEGIN:VCARD`로 시작하기만 하면 됩니다. > [!TIP] > > 아래에서 **빌더**로 표시한 제한은 대시보드 빌더가 적용하는 제한입니다. API는 이를 무시한 페이로드도 받지만, 랜딩 페이지나 빌더에서 이상하게 표시될 수 있습니다. ## Website `qrType`: `"website"`. 대시보드 가이드: [Website QR 코드](https://docs.getqr.com/ko/qr-types/website.md). | 필드 | 동작 | | - | - | | `data` | http(s) URL입니다. | | `link.url` | 목적지입니다. 기본값은 `data`입니다. | | `fileId` | 허용되지 않습니다. | | 인코딩 내용 | `link.url`로 리디렉션되는 단축 링크입니다. 스캔이 추적됩니다. | | 인쇄 후 | 수정할 수 있습니다. 목적지를 바꾸려면 `data` 또는 `link.url`을 보내세요. `data`만 보내도 됩니다. | ```json Request body theme={null} { "qrType": "website", "data": "https://example.com/menu", "title": "Menu" } ``` 오류: * `422 Expected an http(s) URL, e.g. "https://example.com" for qrType "website".` * `422 Invalid destination URL` ## Feedback `qrType`: `"feedback"`. 대시보드 가이드: [Feedback QR 코드](https://docs.getqr.com/ko/qr-types/feedback.md). `data`는 피드백 양식의 http(s) URL입니다. 예를 들어 Google Forms나 리뷰 페이지입니다. 나머지는 모두 [Website](#website)와 같습니다. ```json Request body theme={null} { "qrType": "feedback", "data": "https://forms.gle/abc123" } ``` ## Payment `qrType`: `"payment"`. 대시보드 가이드: [Payment QR 코드](https://docs.getqr.com/ko/qr-types/payment.md). `data`는 결제 서비스의 결제 URL입니다. 예: ```text theme={null} https://paypal.me//25EUR ``` 대시보드 빌더는 다음 호스트를 인식합니다: `paypal.me`, `paypal.com/paypalme`, `cash.app`, `venmo.com`, `buy.stripe.com`, `stripe.com`, `square.link`, `payoneer.com`. PayPal의 경우 금액은 경로의 마지막 세그먼트입니다. 다른 http(s) URL도 작동하지만 빌더가 결제 서비스와 금액으로 나누어 표시하지는 않습니다. 나머지는 모두 [Website](#website)와 같습니다. ```json Request body theme={null} { "qrType": "payment", "data": "https://paypal.me/acme/25EUR" } ``` ## WhatsApp `qrType`: `"whatsapp"`. 대시보드 가이드: [WhatsApp QR 코드](https://docs.getqr.com/ko/qr-types/whatsapp.md). `data`는 `wa.me` 링크입니다. `+` 없이 숫자로만 된 국제 전화번호를 사용하며, 필요하면 미리 입력할 텍스트를 붙입니다. ```text theme={null} https://wa.me/ https://wa.me/?text= ``` 서버는 http(s) URL인지만 확인합니다. 대시보드는 `api.whatsapp.com/send` 링크도 읽습니다. 나머지는 모두 [Website](#website)와 같습니다. ```json Request body theme={null} { "qrType": "whatsapp", "data": "https://wa.me/14155550123?text=Hi%20there" } ``` ## Location `qrType`: `"location"`. 대시보드 가이드: [Location QR 코드](https://docs.getqr.com/ko/qr-types/location.md). `data`는 지도 URL입니다. 대시보드에서 QR 코드를 계속 수정할 수 있게 하려면 다음 형식을 사용하세요(`query_place_id`는 선택 사항). ```text theme={null} https://www.google.com/maps/search/?api=1&query=
&query_place_coords=,&query_place_id= ``` 다른 http(s) URL도 리디렉션됩니다. `geo:` URI는 `data` 검사는 통과하지만 목적지로는 거부되므로 사용하지 마세요. 나머지는 모두 [Website](#website)와 같습니다. ```json Request body theme={null} { "qrType": "location", "data": "https://www.google.com/maps/search/?api=1&query=Golden+Gate+Bridge&query_place_coords=37.8199,-122.4783" } ``` ## App Link `qrType`: `"app"`. 대시보드 가이드: [App Link QR 코드](https://docs.getqr.com/ko/qr-types/app-link.md). | 필드 | 동작 | | - | - | | `link.ios`, `link.android` | App Store와 Google Play URL입니다. iOS 방문자는 `ios`로, Android 방문자는 `android`로 이동합니다. 스캔 시 이 값이 다른 모든 값보다 우선합니다. | | `link.url` | 그 밖의 기기를 위한 대체 목적지입니다. 기본값은 `data`이고, 그다음은 `ios` 또는 `android`입니다. | | `data` | http(s) URL(대시보드는 스토어 URL을 보냄) 또는 빈 값입니다. `link.ios`, `link.android`, `link.url`, `data` 중 하나 이상을 설정해야 하며, 그렇지 않으면 `400 Missing destination URL`을 반환합니다. | | `fileId` | 허용되지 않습니다. | | 인코딩 내용 | 단축 링크입니다. 스캔이 추적됩니다. | | 인쇄 후 | 수정할 수 있습니다. `link.ios`와 `link.android`는 각각 독립적으로, 보낸 경우에만 적용됩니다. `null`을 보내면 해당 값이 지워집니다. `qrType`을 다시 보낼 필요는 없습니다. 다른 유형으로 바꾸면 두 스토어 링크가 모두 지워집니다. | ```json Request body theme={null} { "qrType": "app", "data": "https://apps.apple.com/app/id123456789", "link": { "ios": "https://apps.apple.com/app/id123456789", "android": "https://play.google.com/store/apps/details?id=com.acme.app" } } ``` 오류: * `422 Invalid URL` * `400 Missing destination URL` ## Email `qrType`: `"email"`. 대시보드 가이드: [Email QR 코드](https://docs.getqr.com/ko/qr-types/email.md). ```text theme={null} mailto:
?subject=&body= ``` | 필드 | 동작 | | - | - | | `data` | 제목과 본문을 선택적으로 포함하는 `mailto:` URI입니다. 공백은 `%20`으로 인코딩하세요. 대시보드는 공백을 `+`로 쓰는데, 모든 메일 앱이 이를 공백으로 읽지는 않습니다. `matmsg:`는 목적지로 거부됩니다. | | `link.url` | `mailto:` URI입니다. 기본값은 `data`입니다. | | `fileId` | 허용되지 않습니다. | | 인코딩 내용 | 메일 앱으로 넘겨주는 페이지를 여는 단축 링크입니다. | | 인쇄 후 | 수정할 수 있습니다. 메시지를 바꾸려면 `data` 또는 `link.url`을 보내세요. `data`만 보내도 됩니다. | ```json Request body theme={null} { "qrType": "email", "data": "mailto:hi@example.com?subject=Hello&body=Hi%20there" } ``` 오류: * `422 Expected a mailto URI, e.g. "mailto:hi@example.com?subject=Hello" for qrType "email".` ## SMS `qrType`: `"sms"`. 대시보드 가이드: [SMS QR 코드](https://docs.getqr.com/ko/qr-types/sms.md). ```text theme={null} sms:+ sms:+?body= ``` | 필드 | 동작 | | - | - | | `data` | 본문을 선택적으로 포함하는 `sms:` URI입니다. 대시보드는 정확히 이 형식만 읽습니다. `smsto:`는 목적지로 거부됩니다. | | `link.url` | `sms:` URI입니다. 기본값은 `data`입니다. | | `fileId` | 허용되지 않습니다. | | 인코딩 내용 | 메시지 앱으로 넘겨주는 페이지를 여는 단축 링크입니다. | | 인쇄 후 | 수정할 수 있습니다. 메시지를 바꾸려면 `data` 또는 `link.url`을 보내세요. `data`만 보내도 됩니다. | ```json Request body theme={null} { "qrType": "sms", "data": "sms:+14155550123?body=Table%2012" } ``` 오류: * `422 Expected an SMS URI, e.g. "sms:+14155550123?body=Hello" for qrType "sms".` ## WiFi `qrType`: `"wifi"`. 대시보드 가이드: [WiFi QR 코드](https://docs.getqr.com/ko/qr-types/wifi.md). ```text theme={null} WIFI:T:;S:;P:;H:;; ``` | 필드 | 동작 | | - | - | | `data` | 필수입니다. `T`, `S`, `P`, `H` 순서를 지키세요. 대시보드 빌더와 목록이 이 순서에 의존합니다. SSID와 비밀번호에 들어 있는 `\`, `;`, `"`, `:`는 백슬래시로 이스케이프하세요. 개방형 네트워크에는 `T:nopass`와 빈 `P:`를 사용하세요. `T:none`은 스캐너가 거부합니다. **빌더:** SSID 필수, `nopass`가 아니면 비밀번호 8자 이상. | | `link.url` | 스캔에는 사용되지 않습니다. 기본값은 `data`입니다. | | `fileId` | 허용되지 않습니다. | | 인코딩 내용 | 단축 링크가 아닌 원본 `WIFI:` 페이로드입니다. 스캔이 추적되지 않습니다. | | 인쇄 후 | **수정할 수 없습니다.** 새 `data`는 이후 다운로드에만 반영됩니다. 인쇄된 코드에는 이전 네트워크가 남아 있습니다. | ```json Request body theme={null} { "qrType": "wifi", "data": "WIFI:T:WPA;S:Cafe Guest;P:espresso42;H:false;;" } ``` 오류: * `422 Expected a Wi-Fi payload, e.g. "WIFI:T:WPA;S:MyNetwork;P:secret;H:false;" for qrType "wifi".` > [!WARNING] > > 인쇄된 WiFi QR 코드의 유형은 바꾸지 마세요. 인쇄된 코드에는 이전 네트워크가 남아 있습니다. ## PDF와 Image와 Video `qrType`: `"pdf"`, `"image"` 또는 `"video"`. 대시보드 가이드: [PDF](https://docs.getqr.com/ko/qr-types/pdf.md), [Image](https://docs.getqr.com/ko/qr-types/image.md), [Video](https://docs.getqr.com/ko/qr-types/video.md). | 필드 | 동작 | | - | - | | `fileId` | 파일입니다. 유형에 맞는 용도(`pdf`, `image`, `video`)로 업로드하세요. `fileId`가 있으면 `link.url`은 파일의 URL이 되고, 여기에 보낸 값은 무시됩니다. | | `data` | 다른 유형의 페이로드(`WIFI:`, `BEGIN:VCARD`, `sms:`, `mailto:`, JSON 객체)만 아니면 무엇이든 됩니다. 비워 두어도 됩니다. | | `link.url` | `fileId`가 없으면 `link.url`(또는 `data`)이 외부 목적지로 사용됩니다. 작동은 하지만 대시보드에는 파일이 표시되지 않습니다. | | 인코딩 내용 | 파일로 바로 리디렉션되는 단축 링크입니다. PDF는 뷰어 페이지가 아닌 원본 파일로 열립니다. | | 인쇄 후 | 수정할 수 있습니다. 파일을 교체하려면 새 `fileId`를 보내세요. 이전 파일은 해제됩니다. | QR 코드 하나에는 파일 하나만 사용할 수 있습니다. PDF 번들과 이미지 갤러리는 API에서 사용할 수 없습니다. [API에서 지원하지 않는 기능](#api에서-지원하지-않는-기능)을 참조하세요. ```json pdf theme={null} { "qrType": "pdf", "data": "", "fileId": "file_9f8e7d6c5b4a", "title": "Brochure" } ``` ```json image theme={null} { "qrType": "image", "data": "", "fileId": "file_3c2b1a0f9e8d", "title": "Floor plan" } ``` ```json video theme={null} { "qrType": "video", "data": "", "fileId": "file_5e4d3c2b1a0f", "title": "Product demo" } ``` 파일을 업로드하고 `fileId`를 받는 방법은 [파일](https://docs.getqr.com/ko/api/endpoints/files.md)을 참조하세요. ## vCard `qrType`: `"vcard"`. 대시보드 가이드: [vCard QR 코드](https://docs.getqr.com/ko/qr-types/vcard.md). | 필드 | 동작 | | - | - | | `data` | 필수입니다. `BEGIN:VCARD`로 시작하는 vCard 3.0 텍스트이며, 줄은 `\r\n`으로 구분합니다(`\n`도 작동). | | `fileId` | 선택적 프로필 이미지(`logo` 용도)입니다. `data`에 `PHOTO` 줄이나 `X-GETQR-IMAGE-FILEID` 줄이 없을 때 사용됩니다. | | `link.url` | 무시되고 호스팅 페이지로 대체됩니다. 보내지 마세요. | | 인코딩 내용 | 연락처 저장(`.vcf`) 다운로드가 포함된 호스팅 연락처 페이지를 여는 단축 링크입니다. | | 인쇄 후 | 수정할 수 있습니다. 페이지를 업데이트하려면 새 `data`를 보내세요. | 랜딩 페이지와 빌더는 아래 줄 형식만 읽습니다. `TEL;CELL:`이나 `EMAIL;TYPE=INTERNET:` 같은 다른 형식은 저장되지만 페이지에는 표시되지 않습니다. * `N:;;;;`: 성과 이름입니다. **빌더:** 둘 다 필수, 최대 40자. * `FN: `: 페이지에서는 읽지 않습니다. 대시보드 목록의 레이블로 쓰입니다. * `ORG:`와 `TITLE:`: 회사와 직책입니다. **빌더:** 최대 40자. * `TEL;TYPE=HOME:`, `TEL;TYPE=CELL:`, `TEL;TYPE=WORK:`, `TEL;TYPE=FAX:`: 전화, 휴대폰, 직장, 팩스 번호입니다(`+`와 숫자). * `EMAIL:`: 이메일 주소입니다. * `URL:`: 웹사이트입니다. * `NOTE:`: 소개 글입니다. `\\`, `\n`, `\;`, `\,`로 이스케이프하세요. **빌더:** 최대 200자. * `ADR:;;;;;;`: 주소입니다. * `X-SOCIALPROFILE;TYPE=:` 또는 `URL;TYPE=:`: 소셜 링크입니다. 플랫폼마다 한 줄씩 씁니다. * `PHOTO;VALUE=URI:`: 프로필 이미지 URL입니다. 어떤 파일 ID보다도 우선합니다. * `X-GETQR-IMAGE-FILEID:`: 프로필 이미지(`logo` 용도)입니다. * `X-GETQR-PAGE-LOGO-FILEID:`: 페이지 로고(`logo` 용도)입니다. * `X-GETQR-LANDING-THEME:p|<0-4>` 또는 `X-GETQR-LANDING-THEME:c|#RRGGBB|#RRGGBB|#RRGGBB`: 랜딩 페이지 테마입니다. 프리셋 인덱스(0\~4) 또는 배경, 버튼, 아이콘의 사용자 지정 색상입니다. 소셜 플랫폼: `facebook`, `whatsapp`, `instagram`, `youtube`, `tiktok`, `messenger`, `snapchat`, `linkedin`, `x`, `reddit`, `pinterest`, `telegram`, `wechat`, `viber`, `line`. ```json Request body theme={null} { "qrType": "vcard", "data": "BEGIN:VCARD\r\nVERSION:3.0\r\nN:Doe;Jane;;;\r\nFN:Jane Doe\r\nORG:Acme\r\nTITLE:CTO\r\nTEL;TYPE=CELL:+14155550123\r\nEMAIL:jane@acme.com\r\nURL:https://acme.com\r\nX-GETQR-LANDING-THEME:p|0\r\nEND:VCARD", "title": "Jane Doe" } ``` 오류: * `422 Expected a vCard payload starting with "BEGIN:VCARD" for qrType "vcard".` ## Social Media `qrType`: `"social"`. 대시보드 가이드: [Social Media QR 코드](https://docs.getqr.com/ko/qr-types/social.md). | 필드 | 동작 | | - | - | | `data` | 필수입니다. 객체를 인코딩한 JSON 문자열입니다. `JSON.stringify`로 만드세요. | | `fileId` | 선택적 최상위 프로필 이미지(`logo` 용도)입니다. | | `link.url` | 무시되고 호스팅 페이지로 대체됩니다. 보내지 마세요. | | 인코딩 내용 | 호스팅 소셜 페이지를 여는 단축 링크입니다. | | 인쇄 후 | 수정할 수 있습니다. 페이지를 업데이트하려면 새 `data`를 보내세요. | `data`의 필드: | 필드 | 타입 | 참고 | | - | - | - | | `firstName` | string | 페이지 제목이자 유일하게 표시되는 이름입니다. **빌더:** 필수, 최대 40. | | `lastName` | string | 최대 40. 페이지에 표시되지 않습니다. | | `summary` | string | 최대 200. | | `socialLinks` | `{ platform, url }[]` | `platform`은 [vCard 소셜 플랫폼](#vcard) 중 하나입니다. **빌더:** 플랫폼마다 한 번씩. | | `customItems` | `{ name, url, logoFileId }[]` | **빌더:** `name`은 최대 40, http(s) `url`과 `logoFileId` 필요. 소셜 링크와 사용자 지정 항목을 합쳐 하나 이상. | | `fileId` | string | 프로필 이미지(`logo` 용도)입니다. 최상위 `fileId`가 대체 값입니다. | | `imageUrl` | string | 외부 프로필 이미지 URL로, 파일 ID가 없을 때만 사용됩니다. | | `pageLogoFileId` | string | 페이지 로고(`logo` 용도)입니다. | | `landingThemeMode` | `"preset" \| "custom"` | 기본값은 `preset`입니다. | | `landingPresetIndex` | 0–4 | 기본값은 0입니다. | | `landingCustomBg`, `landingCustomButton`, `landingCustomIcon` | `#RRGGBB` | 모드가 `custom`일 때 사용됩니다. | ```json Request body theme={null} { "qrType": "social", "data": "{\"firstName\":\"Acme Coffee\",\"summary\":\"Follow us\",\"socialLinks\":[{\"platform\":\"instagram\",\"url\":\"https://instagram.com/acme\"}],\"customItems\":[]}" } ``` 오류: * `422 Expected a JSON object describing the social profile page for qrType "social".` ## Multi-Link `qrType`: `"multilink"`. 대시보드 가이드: [Multi-Link QR 코드](https://docs.getqr.com/ko/qr-types/multi-link.md). | 필드 | 동작 | | - | - | | `data` | 필수입니다. 객체를 인코딩한 JSON 문자열입니다. | | `fileId` | 선택적 최상위 프로필 이미지(`logo` 용도)입니다. | | `link.url` | 무시되고 호스팅 페이지로 대체됩니다. 보내지 마세요. | | 인코딩 내용 | 호스팅 멀티 링크 페이지를 여는 단축 링크입니다. | | 인쇄 후 | 수정할 수 있습니다. 페이지를 업데이트하려면 새 `data`를 보내세요. | `data`의 필드는 [Social Media](#social-media)와 같지만, `firstName`, `lastName`, `summary` 대신 다음 필드를 사용합니다. | 필드 | 타입 | 참고 | | - | - | - | | `title` | string | 페이지 제목입니다. **빌더:** 필수, 최대 40. | | `description` | string | 최대 200. | `customItems`에서 `logoFileId`는 선택 사항이며, 없으면 대체 아이콘이 표시됩니다. **빌더:** 소셜 링크 또는 비어 있지 않은 사용자 지정 항목이 하나 이상 필요합니다. ```json Request body theme={null} { "qrType": "multilink", "data": "{\"title\":\"Acme links\",\"description\":\"Everything in one place\",\"socialLinks\":[],\"customItems\":[{\"name\":\"Shop\",\"url\":\"https://acme.com/shop\",\"logoFileId\":\"\"}]}" } ``` 오류: * `422 Expected a JSON object describing the multi-link page for qrType "multilink".` ## Event `qrType`: `"event"`. 대시보드 가이드: [Event QR 코드](https://docs.getqr.com/ko/qr-types/event.md). | 필드 | 동작 | | - | - | | `data` | 필수입니다. 객체를 인코딩한 JSON 문자열입니다. 알 수 없거나 잘못된 값은 기본값으로 대체됩니다. | | `fileId` | 검증(`logo` 용도)되고 저장되지만, 이벤트 페이지는 커버 이미지를 `data.fileId`에서만 읽습니다. 커버 이미지 ID는 페이로드에 넣으세요. | | `link.url` | 무시되고 호스팅 페이지로 대체됩니다. 보내지 마세요. | | 인코딩 내용 | `.ics` 다운로드가 포함된 호스팅 이벤트 페이지를 여는 단축 링크입니다. | | 인쇄 후 | 수정할 수 있습니다. 페이지를 업데이트하려면 새 `data`를 보내세요. | `data`의 필드: | 필드 | 타입 | 참고 | | - | - | - | | `name` | string | **빌더:** 필수. | | `eventType` | string | 아래 이벤트 유형 중 하나 또는 빈 값입니다. | | `start`, `end` | `"YYYY-MM-DDTHH:mm"` | `timezone` 기준 현지 시각입니다. **빌더:** 둘 다 필수, 종료가 시작보다 뒤. | | `timezone` | IANA, 예: `"Europe/Berlin"` | `.ics` 파일에서 시작과 종료 시각의 기준이 됩니다. 항상 보내세요. 비어 있거나 알 수 없는 시간대이면 `.ics`가 시각을 UTC로 처리합니다. | | `street`, `zip`, `city`, `state`, `country` | string | **빌더:** `city`와 `country` 필수, 각각 최대 40. | | `facilities` | string\[] | 아래 목록의 ID입니다. 알 수 없는 ID는 제거됩니다. | | `notes` | string | 자유 텍스트입니다. | | `fileId` | string | 커버 이미지(`logo` 용도)입니다. | | `pageLogoFileId` | string | 페이지 로고(`logo` 용도)입니다. | | `organizerName`, `organizerEmail`, `mobile`, `work` | string | `mobile`과 `work`는 최대 40. | | `socialLinks` | `{ platform, url }[]` | [vCard 소셜 플랫폼](#vcard)과 `website`입니다. | | `ticketsUrl` | http(s) URL | 티켓 구매 링크입니다. | | `ticketsLabel` | string | 최대 20자입니다. 더 긴 레이블은 잘립니다. 비워 두면 기본 레이블이 표시됩니다. | > [accordion] 이벤트 유형 > > `conference`, `seminar`, `workshop`, `training`, `webinar`, `meetup`, `networking`, `corporateEvent`, `productLaunch`, `tradeShow`, `jobFair`, `fundraiser`, `charity`, `wedding`, `engagement`, `birthday`, `anniversary`, `babyShower`, `graduation`, `reunion`, `party`, `religious`, `funeralMemorial`, `ceremony`, `concert`, `festival`, `clubNight`, `theater`, `comedy`, `filmScreening`, `exhibition`, `sports`, `tournament`, `raceMarathon`, `fitnessClass`, `foodDrink`, `market`, `openHouse`, `community`, `schoolEvent`, `kids`, `travelTour` > [accordion] 편의시설 > > | 그룹 | ID | > | - | - | > | 입장 | `freeEntry`, `idRequired`, `invitationOnly`, `plusOneAllowed`, `reEntryAllowed` | > | 연령(하나 선택) | `adultsOnly`, `age18Plus`, `age21Plus`, `kidsWelcome` | > | 현장 시설 | `parking`, `publicTransport`, `shuttle`, `wheelchairAccess`, `evCharging`, `wifi`, `foodDrinks`, `alcoholServed`, `atm`, `coatCheck`, `pool`, `phoneCharging`, `firstAid`, `wc` | > | 규칙 | `petsAllowed`, `noPets`, `smokingArea`, `noSmoking`, `noPhotos` | > | 드레스 코드(하나 선택) | `dressCasual`, `dressSmartCasual`, `dressBusiness`, `dressCocktail`, `dressThemed` | ```json Request body theme={null} { "qrType": "event", "data": "{\"name\":\"Launch party\",\"eventType\":\"productLaunch\",\"start\":\"2026-11-20T18:00\",\"end\":\"2026-11-20T22:00\",\"timezone\":\"Europe/Berlin\",\"city\":\"Berlin\",\"country\":\"Germany\",\"facilities\":[\"freeEntry\"],\"socialLinks\":[],\"ticketsUrl\":\"https://acme.com/tickets\"}" } ``` 오류: * `422 Expected a JSON object describing the event page for qrType "event".` ## QR 코드에 사용하는 파일 [파일](https://docs.getqr.com/ko/api/endpoints/files.md)로 파일을 등록하고 업로드한 다음 `fileId`를 전달하세요. 쓰임새에 맞는 용도를 지정하세요. * **`pdf`, `image`, `video`.** PDF, Image, Video QR 코드의 콘텐츠입니다. * **`logo`.** 프로필 이미지, 페이지 로고, 사용자 지정 링크 아이콘, 중앙 로고입니다. 어떤 QR 코드에도 연결되지 않은 파일은 유예 기간이 지나면 삭제됩니다. `fileId` 오류(생성 시와 `fileId`를 보낸 `PATCH`에서 반환): | 상태 | 원인 | | - | - | | `422 unprocessable_entity` | 이 유형은 파일을 받지 않습니다. 파일을 받는 유형은 `pdf`, `image`, `video`, `vcard`, `social`, `multilink`, `event`뿐입니다. | | `404 not_found` | 이 ID의 파일이 없습니다. 먼저 `POST /api/v1/files`로 등록하세요. | | `422 unprocessable_entity` | 파일이 다른 용도로 업로드되었습니다. 예를 들어 PDF QR 코드에 `image` 용도의 파일을 쓰거나, `pdf`, `image`, `video` 용도의 파일을 vCard 사진으로 쓴 경우입니다. | | `422 unprocessable_entity` | 파일은 등록되었지만 `uploadUrl`로의 업로드가 완료되지 않았습니다. | 페이로드 안의 파일 ID(`fileId`, `pageLogoFileId`, `customItems[].logoFileId`, `X-GETQR-*-FILEID` 줄)는 검증되지 않습니다. `logo` 용도로 업로드한 경우에만 표시됩니다. 이 파일들은 QR 코드에 연결되므로 정리 과정에서 삭제되지 않습니다. ## 유형 변경 [QR 코드 업데이트](https://docs.getqr.com/ko/api/endpoints/qr-codes.md#qr-코드-업데이트)로 `qrType`을 변경할 수 있습니다. 새 유형에 맞는 `data`를 보내세요. 저장된 페이로드는 이전 유형의 것이므로, data 없이 유형을 바꾸면 거부됩니다. 업데이트 후 목적지는 다음 순서로 결정됩니다. 1. `vcard`, `social`, `multilink`, `event`: 항상 호스팅 페이지. 2. 대시보드에서 만든 PDF 번들 또는 이미지 갤러리: 해당 랜딩 페이지. 3. `pdf`, `image`, `video`: 파일 URL(새 `fileId`, 없으면 저장된 것). 4. 보낸 경우 `link.url`. 5. 변경된 `data`. 6. 저장된 URL. 유형을 바꿀 때의 동작: * **`pdf`, `image`, `video`에서 다른 유형으로.** `fileId`와 번들 또는 갤러리가 지워집니다. * **`pdf`, `image`, `video`로.** `fileId`도 함께 보내세요. 보내지 않으면 저장된 값이 재사용되며, 이것이 vCard 사진일 수도 있습니다. * **`app`에서 다른 유형으로.** 앱 이름, `link.ios`, `link.android`가 지워지므로 휴대폰도 새 목적지로 이동합니다. * **`wifi`로.** 이미지가 원본 페이로드로 바뀝니다. 이미 인쇄된 코드에는 단축 링크가 남아 있으며, 이제 `wifi:` URL로 리디렉션됩니다. * **`wifi`에서 다른 유형으로.** 인쇄된 코드에는 이전 네트워크가 남아 있습니다. * **`vcard`, `social`, `multilink`, `event`로.** 단축 링크가 새 호스팅 페이지를 가리킵니다. * **`vcard`, `social`, `multilink`, `event`에서 다른 유형으로.** 새 `data`를 보내세요. 목적지가 이를 따릅니다. 대시보드에서 만든 정적 QR 코드에는 단축 링크가 없으므로 `link.url`을 변경하면 `422`를 반환합니다. ## API에서 지원하지 않는 기능 다음 대시보드 기능은 v1 API에 포함되지 않습니다. 알 수 없는 필드는 오류 없이 무시되므로 보내도 아무런 효과가 없습니다. | 필드 | 설명 | | - | - | | `appName` | App Link QR 코드의 표시 이름입니다. API로 만든 App Link QR 코드는 대시보드 목록에 스토어 URL이 표시됩니다. | | `isStatic` | 단축 링크가 없는 정적 QR 코드입니다. API로 만드는 모든 QR 코드에는 단축 링크가 있으므로 인쇄 후에도 수정하고 추적할 수 있습니다(`wifi` 제외). | | `pdfBundle` | 파일이 두 개 이상인 PDF QR 코드입니다. API는 파일이 하나인 PDF QR 코드만 만듭니다. | | `imageGallery` | 이미지가 두 개 이상인 Image QR 코드입니다. API는 이미지가 하나인 QR 코드만 만듭니다. | 대시보드에서 만든 번들과 갤러리도 API로 조회, 일시 중지, 삭제할 수 있지만, 그 파일을 API로 변경할 수는 없습니다. ## 자주 발생하는 문제 > [accordion] 422 Invalid destination URL > > `link.url`이 단축 링크가 리디렉션할 수 없는 스킴(`geo:`, `smsto:`, `matmsg:`, `tel:` 등)을 사용합니다. 이 페이지의 형식을 사용하세요. > [accordion] 400 Missing destination URL > > `data`가 비어 있고 `link.url`도 없습니다. `app`의 경우 `link.ios`, `link.android`, `link.url`, `data` 중 하나 이상을 설정하세요. > [accordion] 응답의 data가 내 URL이 아니라 단축 링크입니다 > > 링크 유형에서는 저장되는 `data`가 단축 링크입니다. 목적지는 `url`에서 읽으세요. > [accordion] 랜딩 페이지에 페이로드의 일부 정보가 표시되지 않습니다 > > 페이지는 해당 유형에 나열된 필드와 줄 형식만 읽습니다. 그 밖의 필드는 저장되지만 표시되지 않습니다. ## 다음 단계 > [card] [QR 코드](https://docs.getqr.com/ko/api/endpoints/qr-codes.md) > [card] [파일](https://docs.getqr.com/ko/api/endpoints/files.md) > [card] [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md) > [card] [접근 규칙](https://docs.getqr.com/ko/api/guides/access-rules.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.