> ## 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. # 各类型的二维码数据 > 16 种二维码类型各自的数据格式、请求示例，以及印刷后能否修改。 > [!NOTE] > > GetQR API 目前处于 Beta 阶段，仅向部分工作区开放。正式发布前，细节可能会有所变化。 每个二维码都有一个 `qrType`，类型决定了 `data` 必须包含的内容。本指南列出每种类型的格式、一个可用的请求体，以及二维码印刷后还能修改哪些内容。 示例均为[创建二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md#创建二维码)的请求体。发送方式如下： ```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 字符串 | 是 | ## 二维码的解析方式 每个二维码都由一个短链接和一份载荷组成。内容由两个字段承载： | 字段 | 含义 | | - | - | | `link.url` | 短链接将访问者送往的地址。除 `wifi` 外，所有类型的实际目标都是它。 | | `data` | 该类型的载荷，会根据 `qrType` 进行校验。只有 `wifi`、`vcard`、`social`、`multilink`、`event` 和 `sms` 会按原样保存。对于其他类型，它只用于提供 `link.url`，保存的 `data` 会变成短链接。请从响应中的 `url` 读取目标地址。 | 适用于所有类型的规则： * **默认值。** 创建时，省略或为空的 `link.url` 会取 `data` 的值，您也可以省略整个 `link` 对象。两者都发送且不一致时，以 `link.url` 为准。请让两者保持一致，或只发送 `data`。 * **图片编码的内容。** 除 `wifi` 外，所有类型的图片编码的都是短链接。因此，您可以更改已印刷二维码的跳转目标，并且扫描会被统计。WiFi 二维码编码的是网络本身：印刷后无法修改，也不统计扫描。 * **协议。** `link.url` 只接受 `http:`、`https:`、`wifi:`、`mailto:`、`sms:` 和 `begin:`。其他协议（包括 `geo:`、`smsto:`、`matmsg:` 和 `tel:`）都会返回 `422 Invalid destination URL`，即使 `data` 接受它们。 * **空 data。** `data` 为空时会跳过类型校验。此时跳转类类型必须设置 `link.url`，否则请求返回 `400 Missing destination URL`。 * **结构。** 除类型校验外，服务器不会验证载荷。JSON 类型只需能解析为 JSON 对象，vCard 只需以 `BEGIN:VCARD` 开头。 > [!TIP] > > 下文标注 **Builder** 的限制是控制台编辑器强制执行的规则。API 接受不符合这些限制的载荷，但它们在落地页或编辑器中可能显示异常。 ## Website `qrType`：`"website"`。控制台指南：[Website 二维码](https://docs.getqr.com/zh/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"`。控制台指南：[反馈二维码](https://docs.getqr.com/zh/qr-types/feedback.md)。 `data` 是反馈表单的 http(s) URL，例如 Google Form 或评价页面。其余行为与 [Website](#website) 相同。 ```json Request body theme={null} { "qrType": "feedback", "data": "https://forms.gle/abc123" } ``` ## Payment `qrType`：`"payment"`。控制台指南：[支付二维码](https://docs.getqr.com/zh/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 二维码](https://docs.getqr.com/zh/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"`。控制台指南：[位置二维码](https://docs.getqr.com/zh/qr-types/location.md)。 `data` 是一个地图 URL。使用以下格式可让二维码在控制台中保持可编辑（`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"`。控制台指南：[应用链接二维码](https://docs.getqr.com/zh/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"`。控制台指南：[电子邮件二维码](https://docs.getqr.com/zh/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"`。控制台指南：[短信二维码](https://docs.getqr.com/zh/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 二维码](https://docs.getqr.com/zh/qr-types/wifi.md)。 ```text theme={null} WIFI:T:;S:;P:;H:;; ``` | 字段 | 行为 | | - | - | | `data` | 必填。请保持 `T`、`S`、`P`、`H` 的顺序：控制台编辑器和列表都依赖这一顺序。SSID 和密码中的 `\`、`;`、`"` 和 `:` 需要用反斜杠转义。对于开放网络，请使用 `T:nopass` 并将 `P:` 留空。扫码程序会拒绝 `T:none`。**Builder：** 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 二维码的类型。已印刷的二维码仍会保留旧网络。 ## PDF 和 Image 以及 Video `qrType`：`"pdf"`、`"image"` 或 `"video"`。控制台指南：[PDF](https://docs.getqr.com/zh/qr-types/pdf.md)、[Image](https://docs.getqr.com/zh/qr-types/image.md)、[Video](https://docs.getqr.com/zh/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` 即可替换文件，旧文件会被释放。 | 每个二维码只能有一个文件：API 不支持 PDF 文件包和图片图库。请参阅[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/zh/api/endpoints/files.md)。 ## vCard `qrType`：`"vcard"`。控制台指南：[vCard 二维码](https://docs.getqr.com/zh/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:;;;;`：姓和名。**Builder：** 均为必填，最多 40 个字符。 * `FN: `：页面不读取。控制台列表的标签取自此行。 * `ORG:` 和 `TITLE:`：公司和职位。**Builder：** 最多 40 个字符。 * `TEL;TYPE=HOME:`、`TEL;TYPE=CELL:`、`TEL;TYPE=WORK:`、`TEL;TYPE=FAX:`：电话、手机、工作和传真号码（`+` 和数字）。 * `EMAIL:`：电子邮件地址。 * `URL:`：网站。 * `NOTE:`：简介。请转义 `\\`、`\n`、`\;` 和 `\,`。**Builder：** 最多 200 个字符。 * `ADR:;;;;;;`：地址。 * `X-SOCIALPROFILE;TYPE=:` 或 `URL;TYPE=:`：社交链接，每个平台一行。 * `PHOTO;VALUE=URI:`：头像 URL。优先于任何文件 ID。 * `X-GETQR-IMAGE-FILEID:`：头像（`logo` 用途）。 * `X-GETQR-PAGE-LOGO-FILEID:`：页面 Logo（`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 二维码](https://docs.getqr.com/zh/qr-types/social.md)。 | 字段 | 行为 | | - | - | | `data` | 必填。编码了一个对象的 JSON 字符串。请使用 `JSON.stringify` 生成。 | | `fileId` | 可选的顶层头像（`logo` 用途）。 | | `link.url` | 会被忽略并替换为托管页面。请不要发送。 | | 编码内容 | 短链接，会打开托管的社交页面。 | | 印刷后 | 可修改。发送新的 `data` 即可更新页面。 | `data` 中的字段： | 字段 | 类型 | 说明 | | - | - | - | | `firstName` | string | 页面标题，也是唯一显示的名称。**Builder：** 必填，最多 40。 | | `lastName` | string | 最多 40。不会在页面上显示。 | | `summary` | string | 最多 200。 | | `socialLinks` | `{ platform, url }[]` | `platform` 为 [vCard 社交平台](#vcard)之一。**Builder：** 每个平台只能出现一次。 | | `customItems` | `{ name, url, logoFileId }[]` | **Builder：** `name` 最多 40，需要 http(s) 的 `url` 和 `logoFileId`。社交链接和自定义项合计至少一个。 | | `fileId` | string | 头像（`logo` 用途）。顶层的 `fileId` 作为备用。 | | `imageUrl` | string | 外部头像 URL，仅在没有文件 ID 时使用。 | | `pageLogoFileId` | string | 页面 Logo（`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"`。控制台指南：[多链接二维码](https://docs.getqr.com/zh/qr-types/multi-link.md)。 | 字段 | 行为 | | - | - | | `data` | 必填。编码了一个对象的 JSON 字符串。 | | `fileId` | 可选的顶层头像（`logo` 用途）。 | | `link.url` | 会被忽略并替换为托管页面。请不要发送。 | | 编码内容 | 短链接，会打开托管的多链接页面。 | | 印刷后 | 可修改。发送新的 `data` 即可更新页面。 | `data` 中的字段与 [Social Media](#social-media) 相同，只是 `firstName`、`lastName` 和 `summary` 替换为： | 字段 | 类型 | 说明 | | - | - | - | | `title` | string | 页面标题。**Builder：** 必填，最多 40。 | | `description` | string | 最多 200。 | 在 `customItems` 中，`logoFileId` 为可选项：未提供时会显示备用图标。**Builder：** 至少需要一个社交链接或一个非空的自定义项。 ```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 二维码](https://docs.getqr.com/zh/qr-types/event.md)。 | 字段 | 行为 | | - | - | | `data` | 必填。编码了一个对象的 JSON 字符串。未知或无效的值会回退为默认值。 | | `fileId` | 会经过校验（`logo` 用途）并保存，但活动页面只从 `data.fileId` 读取封面。请将封面 ID 放在载荷中。 | | `link.url` | 会被忽略并替换为托管页面。请不要发送。 | | 编码内容 | 短链接，会打开托管的活动页面，并提供 `.ics` 下载。 | | 印刷后 | 可修改。发送新的 `data` 即可更新页面。 | `data` 中的字段： | 字段 | 类型 | 说明 | | - | - | - | | `name` | string | **Builder：** 必填。 | | `eventType` | string | 下列活动类型之一，或留空。 | | `start`, `end` | `"YYYY-MM-DDTHH:mm"` | `timezone` 时区的当地时间。**Builder：** 均为必填，结束须晚于开始。 | | `timezone` | IANA 时区，例如 `"Europe/Berlin"` | 决定 `.ics` 文件中开始和结束时间所在的时区。请始终发送：时区为空或未知时，`.ics` 会将时间按 UTC 处理。 | | `street`, `zip`, `city`, `state`, `country` | string | **Builder：** `city` 和 `country` 必填，各最多 40。 | | `facilities` | string\[] | 下列列表中的 ID。未知 ID 会被丢弃。 | | `notes` | string | 自由文本。 | | `fileId` | string | 封面图片（`logo` 用途）。 | | `pageLogoFileId` | string | 页面 Logo（`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".` ## 二维码中的文件 通过[文件](https://docs.getqr.com/zh/api/endpoints/files.md)注册文件并上传，然后传入其 `fileId`。请使用与用法匹配的用途： * **`pdf`、`image`、`video`。** PDF、Image 或 Video 二维码的内容。 * **`logo`。** 头像、页面 Logo、自定义链接图标和中心 Logo。 从未关联到任何二维码的文件会在宽限期结束后被删除。 `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 二维码上使用 `image` 上传，或将 `pdf`、`image` 或 `video` 上传用作 vCard 头像。 | | `422 unprocessable_entity` | 文件已注册，但向 `uploadUrl` 的上传一直未完成。 | 载荷中的文件 ID（`fileId`、`pageLogoFileId`、`customItems[].logoFileId`、`X-GETQR-*-FILEID` 行）不会经过校验。只有使用 `logo` 用途上传的文件才会显示。这些文件归该二维码所有，因此清理时不会删除它们。 ## 切换类型 您可以通过[更新二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md#更新二维码)更改 `qrType`。请发送与新类型匹配的 `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`，目标地址会随之更新。 在控制台中创建的静态二维码没有短链接，因此更改其 `link.url` 会返回 `422`。 ## API 不支持的功能 以下控制台功能不属于 v1 API。未知字段会被直接丢弃而不报错，因此发送它们不会产生任何效果。 | 字段 | 说明 | | - | - | | `appName` | 应用链接二维码的显示名称。通过 API 创建的应用链接二维码在控制台列表中显示其应用商店 URL。 | | `isStatic` | 没有短链接的静态二维码。API 创建的每个二维码都带有短链接，因此印刷后仍可修改和统计（`wifi` 除外）。 | | `pdfBundle` | 包含两个或更多文件的 PDF 二维码。API 只能创建单文件的 PDF 二维码。 | | `imageGallery` | 包含两张或更多图片的 Image 二维码。API 只能创建单张图片的二维码。 | 在控制台中创建的文件包和图库仍可通过 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] [二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md) > [card] [文件](https://docs.getqr.com/zh/api/endpoints/files.md) > [card] [自定义设计](https://docs.getqr.com/zh/api/guides/customization.md) > [card] [访问规则](https://docs.getqr.com/zh/api/guides/access-rules.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.