跳转到主要内容
GetQR API 目前处于 Beta 阶段,仅向部分工作区开放。正式发布前,细节可能会有所变化。
每个二维码都有一个 qrType,类型决定了 data 必须包含的内容。本指南列出每种类型的格式、一个可用的请求体,以及二维码印刷后还能修改哪些内容。 示例均为创建二维码的请求体。发送方式如下:

所有类型一览

二维码的解析方式

每个二维码都由一个短链接和一份载荷组成。内容由两个字段承载: 适用于所有类型的规则:
  • 默认值。 创建时,省略或为空的 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 开头。
下文标注 Builder 的限制是控制台编辑器强制执行的规则。API 接受不符合这些限制的载荷,但它们在落地页或编辑器中可能显示异常。

Website

qrType:"website"。控制台指南:Website 二维码。
Request body
错误:
  • 422 Expected an http(s) URL, e.g. "https://example.com" for qrType "website".
  • 422 Invalid destination URL

Feedback

qrType:"feedback"。控制台指南:反馈二维码。 data 是反馈表单的 http(s) URL,例如 Google Form 或评价页面。其余行为与 Website 相同。
Request body

Payment

qrType:"payment"。控制台指南:支付二维码。 data 是服务商的付款 URL,例如:
控制台编辑器能识别以下域名:paypal.me、paypal.com/paypalme、cash.app、venmo.com、buy.stripe.com、stripe.com、square.link 和 payoneer.com。对于 PayPal,金额是路径的最后一段。其他 http(s) URL 也可以使用,但编辑器不会将其拆分为服务商和金额。其余行为与 Website 相同。
Request body

WhatsApp

qrType:"whatsapp"。控制台指南:WhatsApp 二维码。 data 是一个 wa.me 链接:包含不带 + 的纯数字国际号码,可选附带预填文本。
服务器只检查是否为 http(s) URL。控制台也能读取 api.whatsapp.com/send 链接。其余行为与 Website 相同。
Request body

Location

qrType:"location"。控制台指南:位置二维码。 data 是一个地图 URL。使用以下格式可让二维码在控制台中保持可编辑(query_place_id 为可选项):
其他 http(s) URL 也能正常跳转。geo: URI 能通过 data 校验,但作为目标地址会被拒绝,因此请不要使用。其余行为与 Website 相同。
Request body
qrType:"app"。控制台指南:应用链接二维码。
Request body
错误:
  • 422 Invalid URL
  • 400 Missing destination URL

Email

qrType:"email"。控制台指南:电子邮件二维码。
Request body
错误:
  • 422 Expected a mailto URI, e.g. "mailto:[email protected]?subject=Hello" for qrType "email".

SMS

qrType:"sms"。控制台指南:短信二维码。
Request body
错误:
  • 422 Expected an SMS URI, e.g. "sms:+14155550123?body=Hello" for qrType "sms".

WiFi

qrType:"wifi"。控制台指南:WiFi 二维码。
Request body
错误:
  • 422 Expected a Wi-Fi payload, e.g. "WIFI:T:WPA;S:MyNetwork;P:secret;H:false;" for qrType "wifi".
请不要更改已印刷 WiFi 二维码的类型。已印刷的二维码仍会保留旧网络。

PDF 和 Image 以及 Video

qrType:"pdf"、"image" 或 "video"。控制台指南:PDF、Image、Video。 每个二维码只能有一个文件:API 不支持 PDF 文件包和图片图库。请参阅API 不支持的功能。
关于如何上传文件并获取其 fileId,请参阅文件。

vCard

qrType:"vcard"。控制台指南:vCard 二维码。 落地页和编辑器只读取下列格式的行。其他写法(例如 TEL;CELL: 或 EMAIL;TYPE=INTERNET:)会被保存,但不会显示在页面上。
  • N:<last>;<first>;;;:姓和名。Builder: 均为必填,最多 40 个字符。
  • FN:<first> <last>:页面不读取。控制台列表的标签取自此行。
  • ORG:<company> 和 TITLE:<role>:公司和职位。Builder: 最多 40 个字符。
  • TEL;TYPE=HOME:、TEL;TYPE=CELL:、TEL;TYPE=WORK:、TEL;TYPE=FAX::电话、手机、工作和传真号码(+ 和数字)。
  • EMAIL:<email>:电子邮件地址。
  • URL:<url>:网站。
  • NOTE:<text>:简介。请转义 \\、\n、\; 和 \,。Builder: 最多 200 个字符。
  • ADR:;;<street>;<city>;<state>;<zip>;<country>:地址。
  • X-SOCIALPROFILE;TYPE=<platform>:<url> 或 URL;TYPE=<PLATFORM>:<url>:社交链接,每个平台一行。
  • PHOTO;VALUE=URI:<url>:头像 URL。优先于任何文件 ID。
  • X-GETQR-IMAGE-FILEID:<fileId>:头像(logo 用途)。
  • X-GETQR-PAGE-LOGO-FILEID:<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。
Request body
错误:
  • 422 Expected a vCard payload starting with "BEGIN:VCARD" for qrType "vcard".

Social Media

qrType:"social"。控制台指南:Social Media 二维码。 data 中的字段:
Request body
错误:
  • 422 Expected a JSON object describing the social profile page for qrType "social".
qrType:"multilink"。控制台指南:多链接二维码。 data 中的字段与 Social Media 相同,只是 firstName、lastName 和 summary 替换为: 在 customItems 中,logoFileId 为可选项:未提供时会显示备用图标。Builder: 至少需要一个社交链接或一个非空的自定义项。
Request body
错误:
  • 422 Expected a JSON object describing the multi-link page for qrType "multilink".

Event

qrType:"event"。控制台指南:Event 二维码。 data 中的字段:
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
Request body
错误:
  • 422 Expected a JSON object describing the event page for qrType "event".

二维码中的文件

通过文件注册文件并上传,然后传入其 fileId。请使用与用法匹配的用途:
  • pdf、image、video。 PDF、Image 或 Video 二维码的内容。
  • logo。 头像、页面 Logo、自定义链接图标和中心 Logo。
从未关联到任何二维码的文件会在宽限期结束后被删除。 fileId 错误,在创建时返回,以及在发送了 fileId 的 PATCH 请求中返回: 载荷中的文件 ID(fileId、pageLogoFileId、customItems[].logoFileId、X-GETQR-*-FILEID 行)不会经过校验。只有使用 logo 用途上传的文件才会显示。这些文件归该二维码所有,因此清理时不会删除它们。

切换类型

您可以通过更新二维码更改 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。未知字段会被直接丢弃而不报错,因此发送它们不会产生任何效果。 在控制台中创建的文件包和图库仍可通过 API 读取、暂停和删除,但无法通过 API 更改其文件。

常见问题

link.url 使用了短链接无法跳转的协议,例如 geo:、smsto:、matmsg: 或 tel:。请使用本页列出的格式。
data 为空,并且没有 link.url。对于 app,请至少设置 link.ios、link.android、link.url 或 data 中的一项。
对于链接类类型,保存的 data 是短链接。请从 url 读取目标地址。
页面只读取为该类型列出的字段和行格式。其他字段会被保存,但不会显示。

后续步骤

二维码

文件

自定义设计

访问规则