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开头。
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
qrType:"whatsapp"。控制台指南:WhatsApp 二维码。
data 是一个 wa.me 链接:包含不带 + 的纯数字国际号码,可选附带预填文本。
api.whatsapp.com/send 链接。其余行为与 Website 相同。
Request body
Location
qrType:"location"。控制台指南:位置二维码。
data 是一个地图 URL。使用以下格式可让二维码在控制台中保持可编辑(query_place_id 为可选项):
geo: URI 能通过 data 校验,但作为目标地址会被拒绝,因此请不要使用。其余行为与 Website 相同。
Request body
App Link
qrType:"app"。控制台指南:应用链接二维码。
Request body
422 Invalid URL400 Missing destination URL
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".
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".
Multi-Link
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:已保存的载荷属于旧类型,因此不带新数据的切换会被拒绝。
更新后,目标地址按以下顺序确定:
vcard、social、multilink、event:始终为托管页面。- 在控制台中创建的 PDF 文件包或图片图库:其落地页。
pdf、image、video:文件 URL(新的fileId,否则为已保存的)。link.url(如已发送)。- 已更改的
data。 - 已保存的 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 更改其文件。
常见问题
422 Invalid destination URL
422 Invalid destination URL
link.url 使用了短链接无法跳转的协议,例如 geo:、smsto:、matmsg: 或 tel:。请使用本页列出的格式。400 Missing destination URL
400 Missing destination URL
data 为空,并且没有 link.url。对于 app,请至少设置 link.ios、link.android、link.url 或 data 中的一项。响应中的 data 是短链接,而不是我的 URL
响应中的 data 是短链接,而不是我的 URL
对于链接类类型,保存的
data 是短链接。请从 url 读取目标地址。落地页缺少载荷中的部分信息
落地页缺少载荷中的部分信息
页面只读取为该类型列出的字段和行格式。其他字段会被保存,但不会显示。