QRFLOW.codes
官方生成二维码,重新指向已打印的动态码,在您自己的域名上命名链接,并查看扫描分析。
你可以用 QRFLOW Codes MCP 做什么?
- 创建动态二维码 — 让助手创建带有
destination_data的url码,并返回其short_url以供打印。 - 更改已打印二维码的指向 — 更改现有动态码的重定向目标,无需重新打印,因为二维码图案中保存的是
short_url。 - 暂停或让二维码过期 — 设置
paused: true或结束日期,而不是删除,这样已打印的链接就会安全地停止重定向。 - 查看扫描分析数据 — 获取二维码的累计
Scans总数,或按天、国家和设备划分的明细。 - 使用自己的域名命名链接 — 设置类似
menu的slug,并选择链接域名,让二维码打印为go.example.com/menu。 - 批量创建二维码 — 根据列表生成数千个动态二维码,并通过标签将返回的二维码对应到各行。
托管 MCP 服务器
npx add-mcp 'https://qrflow.codes/mcp'可安装到 Claude Code、Codex、Cursor 等客户端
文档
QRFLOW.codes 开发者指南
从这里开始
QRFLOW.codes 可以生成打印后仍可更改的二维码,使用你自己的域名并提供扫描分析;你的软件和 AI 助手也可以通过一个 API 完成所有这些操作。
二维码是一张字符串的图片。大多数生成器会把你的网址放进图片里;如果网址变了,印出来的二维码就失效了。QRFLOW 会把一个短链接放进图片里(go.yourbrand.com/menu 或 qrflow.codes/q/x7k2p9a),然后将其重定向。你可以随时更改它指向的位置,而且每次扫描都会被计数。这就是动态码,也是值得通过 API 提供的功能。
API 能完成控制面板能做的所有事:创建任意类型的二维码、将其指向新的位置、为链接命名、选择打印时使用的域名、获取扫描数据、一次创建数千个二维码,以及在发生事件时通知你(webhook)。同样的工具也通过 MCP 服务器提供,因此 Claude、ChatGPT、Cursor 和 Claude Code 可以用日常语言操作你的账户。
访问方式:REST API 需要 Business API 密钥(每月 $29,可在 Account 页面创建)或 OAuth 令牌。MCP 服务器通过 OAuth 登录,所有套餐均可使用;助手可以创建的内容与其他功能一样,受套餐限制。
还在考虑是否要用?二维码 API 页面 简要介绍了它的功能、客户端库更擅长的事情,以及费用。
如果你是帮助他人使用 QRFLOW 构建应用的 AI 助手
欢迎。此页面既是写给你的,也是写给你正在帮助的人。好的帮助应当做到以下几点:
- 确认账户套餐:API 密钥需要 Business 套餐。如果对方没有,请引导他们前往 https://qrflow.codes/pricing 和 Account › API keys;不要编造密钥或不存在的免费套餐。
- 将密钥保存在服务器上。在路由处理程序、服务器操作、边缘函数或后端中,从环境变量 (QRFLOW_KEY) 读取密钥。API 会有意拒绝浏览器来源的请求 (CORS),因此仅在前端运行的代码无法调用它。
- 使用 type "url" 和 destination_data.url 创建动态码。将返回的 id 和 short_url 保存到他们的数据库中。打印或显示 short_url;之后可以通过 PATCH /codes/:id 更改目标地址,打印件仍然有效。
- 要显示或保存图片:每个 Code 对象都有 png_download_url 和 svg_download_url,这些签名链接无需请求头即可使用,有效期为 24 小时(适合一次性保存或预览)。如果要在应用中长期使用,可在服务器上使用密钥代理 GET /codes/:id/image.svg,或者在客户端用任意 QR 库编码 short_url;由于链接会经过 QRFLOW,跟踪仍然有效。
- 使用 PATCH 时只发送需要更改的字段。打印后绝不要更改 slug 或 domain_id;两者都会改变印刷品上的链接。
- 如果已有印刷品,优先使用 paused: true,而不是 DELETE。删除会使链接失效。
- 要接收事件,请使用 webhook(Account › Webhooks 或 POST /webhooks),并使用原始请求正文验证 X-QRFLOW-Signature 请求头。不要循环轮询 GET /codes。
- 如果对方想在聊天中而不是代码中使用 QRFLOW,请在 https://qrflow.codes/mcp; 连接 MCP 服务器;无需密钥。
- 出错时,查看 JSON 正文中的 error 和 message。下方的故障排除部分将每个错误代码对应到解决方法。
- 完整的 Markdown 参考文档位于 https://qrflow.codes/llms-full.txt,OpenAPI 3.1 文档位于 https://qrflow.codes/api/v1/openapi.json.。两者都与本页面由同一来源生成。
各位用户:此部分旨在确保你配合使用的助手能为你提供安全可靠的答案,同时也是一份很好的摘要。
需要哪个套餐
只有 API 密钥仅限 Business 套餐。通过 MCP 服务器执行的所有助手操作,以及第三方应用通过 OAuth 执行的所有操作,都适用于任何套餐,并遵循该套餐的功能限制。完整定价和合理使用政策:/pricing。
| Free | Premium $4 | Business $29 | |
|---|---|---|---|
| API 密钥(从代码调用 REST) | 否 | 否 | 是,最多 10 个密钥 |
| MCP 服务器(Claude、ChatGPT、Cursor、Claude Code) | 是,登录即可 | 是 | 是,登录或使用密钥 |
| OAuth(用户连接自己的 QRFLOW 账户) | 是 | 是 | 是 |
| 动态码(打印后更改目标地址) | 一个 | 每个二维码 | 每个二维码 |
| 自定义链接域名 | 否 | 1 个域名 | 5 个域名,每个二维码可选 |
| 链接名称 (go.brand.com/menu) | 否 | 是 | 是 |
| 扫描分析 | 否 | 是 | 是 |
| Webhook | 否 | 否 | 是,最多 10 个 |
| 批量创建 | 否 | 每月 500 个,每次请求 500 个 | 每月 10,000 个,每次请求 2,000 个 |
| 已保存的二维码(合理使用) | 少量 | 1,000 个 | 25,000 个 |
| 团队席位 | 1 | 1 | 5 |
| 价格 | $0 | $4/月 | $29/月 |
十二个词,涵盖所有关键内容
概念
读完这些,下面的每个端点就都容易理解了。
Static code
内容就在图片里。Wi-Fi、联系人卡片 (vCard) 和纯文本二维码始终是静态码;Free 套餐中的所有二维码也都是静态码。静态码无需服务器,永不过期,也无法更改或计数。
Dynamic code
图片中包含一个由 QRFLOW 重定向的短链接。Premium 和 Business 套餐中的 url、phone、email、sms 和 location 二维码都是动态码。你可以重新指定目标、暂停、设置过期时间、重命名并统计扫描次数,而无需更改印刷品。
short_url
动态码中编码的确切字符串,也是需要打印的内容。它是 https://qrflow.codes/q/<short_code>,连接域名后则是 https://<your domain>/<slug or short_code>.。每个 Code 对象都包含它。
short_code
七个随机字符,每个二维码都唯一,在创建时分配且永不更改。当二维码没有链接名称时,它就是备用路径。
slug (link name)
自定义域名上的易读路径:go.example.com/menu。由 3 到 40 个小写字母、数字和连字符组成,在你的账户内唯一,且只能与已连接的域名搭配使用。请在打印前设置:更改它会改变印刷品上的链接。
Link domain
你拥有的主机名 (go.example.com),通过 CNAME 指向 QRFLOW,并在 Account 页面完成验证。Premium 套餐可使用一个域名;Business 套餐可使用五个,并可通过 domain_id 为每个二维码选择域名。最早添加且仍有效的域名是默认域名。
Kind, type and subtype
type 表示编码类型:url、text、wifi、vcard、email、phone、sms、location。kind 是人们需求的更易懂名称(instagram、googlereview、whatsapp、pdf、menu、appstore,...)。大多数 kind 都是设置了 destination_data.subtype 的 url 二维码。GET /catalog 会列出所有 kind 及其字段;Code 上的 kind 会告诉你它属于哪一种。
destination_data
对应类型的字段,值均为字符串:网站使用 { url },Wi-Fi 使用 { ssid, password, encryption },Google 评论使用 { placeId },Instagram 使用 { handle }。对于动态码,你可以随时替换这些字段。
Scans
每次重定向都会根据请求本身记录设备类型、国家、城市、引荐来源、浏览器、操作系统和语言,并使用每日单向哈希统计独立访客。不会设置 Cookie,也不会存储 IP 地址。Code 上的 scans 是累计总数;GET /codes/:id/scans 会提供详细分类数据。
Source
每个二维码都会记录其创建来源:dashboard、api:<key name>、mcp、canva、app:<connected app>(例如 app:Google Sheets)或 bulk;通过批量请求创建时,还会带有 bulk: 前缀。此信息会显示在控制面板和 webhook 负载中,因此你可以区分集成创建的二维码和手动创建的二维码。
Workspace
Business 账户所有者最多可邀请四名队友。密钥和 webhook 属于所有者账户;工作区中任何人创建的二维码都对整个团队可见。
五分钟
快速开始
获取密钥
- 使用 Business 套餐,打开 Account › API keys。
- 根据用途为密钥命名("Shop backend"、"Reporting"),并选择其作用域。作用域之后无法更改;如果需要更多权限,请创建新密钥。
- 只复制一次。密钥格式为
qrf_live_…。将其放入名为QRFLOW_KEY的环境变量中。 - 在每个请求中将其作为
Authorization: Bearer $QRFLOW_KEY发送。身份验证就这么简单。
密钥仅供服务器使用。绝不要将密钥放入网页、移动应用或共享电子表格中;如果密钥泄露,请撤销并重新签发。
以下是用 curl、TypeScript 和 Python 实现的相同步骤。每个示例都会创建动态码、下载图片、更改目标地址并读取扫描数据。
export QRFLOW_KEY=qrf_live_... # from Account › API keys
# 1. Who am I, what can this key do?
curl https://qrflow.codes/api/v1/me -H "Authorization: Bearer $QRFLOW_KEY"
# 2. Make a dynamic code. Print what comes back as short_url.
curl -X POST https://qrflow.codes/api/v1/codes \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "type": "url", "destination_data": { "url": "https://example.com/menu" }, "label": "Table tents" }'
# 3. The print-ready image (SVG, with your colors and frame).
curl "https://qrflow.codes/api/v1/codes/$CODE_ID/image.svg?size=1024" \
-H "Authorization: Bearer $QRFLOW_KEY" -o menu.svg
# 4. Fall menu. The printed code keeps working.
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "destination_data": { "url": "https://example.com/menu-fall" } }'
# 5. How did it do?
curl "https://qrflow.codes/api/v1/codes/$CODE_ID/scans?group=day" -H "Authorization: Bearer $QRFLOW_KEY"
TypeScript (Node 18+, Bun, Deno, Workers)
// npm install qrflow (zero dependencies; ESM + CommonJS; full types)
import { QRFlow, QRFlowError } from "qrflow";
const qr = new QRFlow(process.env.QRFLOW_KEY!);
const { code } = await qr.createCode({
type: "url",
destination_data: { url: "https://example.com/menu" },
label: "Table tents",
});
console.log(code.id, code.short_url); // save both; print short_url
await qr.updateCode(code.id, { destination_data: { url: "https://example.com/menu-fall" } });
const stats = await qr.scans(code.id, { group: "day" });
console.log(stats.total, stats.rows); // [{ key: "2026-09-21", scans: 18 }, ...]
try {
await qr.updateCode(code.id, { slug: "menu" });
} catch (e) {
if (e instanceof QRFlowError) console.log(e.status, e.code, e.message); // 400 no_domain: connect a domain first
}
# Download https://qrflow.codes/sdk/qrflow.py next to your code.
import os
from qrflow import QRFlow, QRFlowError
qr = QRFlow(os.environ["QRFLOW_KEY"])
code = qr.create_code(type="url", destination_data={"url": "https://example.com/menu"}, label="Table tents")["code"]
print(code["id"], code["short_url"]) # save both; print short_url
qr.update_code(code["id"], destination_data={"url": "https://example.com/menu-fall"})
stats = qr.scans(code["id"], group="day")
print(stats["total"], stats["rows"])
try:
qr.update_code(code["id"], slug="menu")
except QRFlowError as e:
print(e.status, e.code, e) # 400 no_domain: connect a domain first
身份验证
API 密钥(Business)
每个账户最多 10 个密钥,每个密钥每分钟可发出 600 个请求;密钥以哈希形式存储,且只显示一次。密钥包含创建时指定的作用域:
| Scope | 允许的操作 |
|---|---|
| profile | GET /me:套餐、功能和限制。每个密钥都包含此作用域。 |
| codes:read | 列出和读取二维码、下载图片。 |
| codes:write | 创建、修改、设为动态、删除和批量创建二维码。 |
| analytics:read | GET /codes/:id/scans。 |
| domains:read | GET /domains(合理使用 domain_id 时需要)。 |
| codes:read / codes:write | 也适用于 GS1 产品:/products 端点共用二维码作用域,因此管理二维码的密钥也能管理包装码。 |
| webhooks:manage | 列出、创建、测试和删除 webhook。 |
OAuth 2.0(适用于任何套餐,供应用和助手使用)
如果二维码应归属于你的用户账户,而不是你的账户,或者客户端是聊天助手,请使用 OAuth。客户端需要自行注册;公共客户端必须使用 PKCE S256;令牌可以绑定到 MCP 服务器,方法是使用 resource=。OAuth 操作指南 会逐步介绍整个流程。
| 端点 | URL | 说明 |
|---|---|---|
| 授权 | https://qrflow.codes/oauth/authorize | 将用户发送到此处;他们登录后点击 Allow。 |
| 令牌 | https://qrflow.codes/api/oauth/token | 支持 authorization_code 和 refresh_token 授权类型。访问令牌有效期为 1 小时,刷新令牌有效期为 90 天。 |
| 撤销 | https://qrflow.codes/api/oauth/revoke | RFC 7009。用户也可以在 Account › Connected apps 中断开连接。 |
| 注册客户端 | https://qrflow.codes/api/oauth/register | RFC 7591 动态注册,无需账户。公共客户端会获得 dyn_ client_id,且必须使用 PKCE S256。 |
| 发现 | https://qrflow.codes/.well-known/oauth-authorization-server | RFC 8414。MCP 资源文档位于 /.well-known/oauth-protected-resource。 |
访问令牌有效期为 1 小时,刷新令牌有效期为 90 天。用户可以在 Account › Connected apps 中查看已连接的应用,并随时断开连接。为 https://qrflow.codes/mcp 签发的令牌在 /api/v1 上会被拒绝,反之亦然。
人们真正会用到的内容
构建指南
每个指南都完整可用,直接复制自经过验证的代码。选择与你的技术栈匹配的指南;流程始终相同:在服务器端使用密钥发起调用,保存 id 和 short_url,然后显示图片。
- Next.js
- 无需代理即可显示二维码
- Express 或任意 Node 服务器
- Cloudflare Workers、Vercel Edge、Deno Deploy、Supabase Edge Functions
- Python
- 为每个订单、桌位、产品、票券或活动创建一个二维码
- 更改已打印二维码的目标地址
- 使用自定义域名打印二维码
- 在自己的管理后台显示扫描图表
- 在 Next.js 中接收并验证 webhook
- 在 Python 中接收 webhook
- 从 CSV 批量创建数千个二维码
- 让用户连接自己的 QRFLOW 账户 (OAuth)
- Zapier、Make、n8n
Next.js:创建二维码的路由和显示二维码的路由
适用场景:你有一个 Next.js 应用(App Router),并希望添加一个用于创建二维码的按钮和一个用于显示二维码的页面。
- 将密钥放入 .env.local,变量名为 QRFLOW_KEY。绝不要添加 NEXT_PUBLIC_ 前缀。
- 添加一个 POST 路由处理程序来创建二维码并返回 id 和 short_url。
- 添加一个 GET 路由来代理图片,这样浏览器就不会看到密钥。
- 将 id 和 short_url 保存到你自己的记录中(订单、桌位、产品、活动)。
import { NextResponse } from "next/server";
export async function POST(req: Request) {
const { url, label } = await req.json();
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST",
headers: { Authorization: \`Bearer ${process.env.QRFLOW_KEY}\`, "Content-Type": "application/json" },
body: JSON.stringify({ type: "url", destination_data: { url }, label }),
});
const data = await r.json();
if (!r.ok) return NextResponse.json(data, { status: r.status }); // { error, message }
return NextResponse.json({ id: data.code.id, short_url: data.code.short_url });
}
// Proxies the SVG so the key stays on the server. Check that the signed-in
// user owns this id before you serve it, or anyone with an id can fetch it.
export async function GET(_: Request, { params }: { params: Promise<{ id: string }> }) {
const { id } = await params;
const r = await fetch(\`https://qrflow.codes/api/v1/codes/${id}/image.svg?size=1024\`, {
headers: { Authorization: \`Bearer ${process.env.QRFLOW_KEY}\` },
});
return new Response(r.body, {
status: r.status,
headers: { "Content-Type": "image/svg+xml", "Cache-Control": "private, max-age=3600" },
});
}
<img src={\`/api/qr/${code.id}/image\`} alt={\`QR code for ${code.label}\`} width={256} height={256} />
<a href={code.short_url}>{code.short_url}</a>
- Server Actions 的工作方式相同:在 action 中调用 fetch,并在其中传入密钥。
- 对于 Pages Router,将相同的代码放在 pages/api/qr.ts 中,并使用 req/res。
显示 QR 码而不经过代理:自行渲染 short_url
适用场景:你希望立即在浏览器中显示图片,并且不需要 QRFLOW 的边框或徽标。
任何 QR 库都可以,因为代码本身就是短链接
import QRCode from "qrcode"; // npm i qrcode
// short_url came back from POST /codes. Encode it as-is.
const dataUrl = await QRCode.toDataURL(code.short_url, { width: 512, margin: 2 });
// <img src={dataUrl} /> scans go through QRFLOW, so analytics and re-pointing still work.
- 这是最快的预览方式。用于打印时,请下载 /codes/:id/image.svg:它包含已保存的颜色、边框、说明文字和徽标,而且是矢量图。
- 如果之后更改 slug 或 domain_id,short_url 也会改变;请重新渲染。
Express 或任何 Node 服务器
适用场景:普通的 Node 后端。
import express from "express";
const app = express();
app.use(express.json());
const H = { Authorization: \`Bearer ${process.env.QRFLOW_KEY}\`, "Content-Type": "application/json" };
app.post("/qr", async (req, res) => {
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST", headers: H,
body: JSON.stringify({ type: "url", destination_data: { url: req.body.url }, label: req.body.label }),
});
res.status(r.status).json(await r.json());
});
app.get("/qr/:id.svg", async (req, res) => {
const r = await fetch(\`https://qrflow.codes/api/v1/codes/${req.params.id}/image.svg\`, { headers: H });
res.status(r.status).type("image/svg+xml").send(await r.text());
});
app.listen(3000);
Cloudflare Workers、Vercel Edge、Deno Deploy、Supabase Edge Functions
适用场景:仅支持 fetch、没有 Node 内置模块的运行时。
export default {
async fetch(req: Request, env: { QRFLOW_KEY: string }) {
const { url, label } = await req.json();
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST",
headers: { Authorization: \`Bearer ${env.QRFLOW_KEY}\`, "Content-Type": "application/json" },
body: JSON.stringify({ type: "url", destination_data: { url }, label }),
});
return new Response(r.body, { status: r.status, headers: { "Content-Type": "application/json" } });
},
};
Deno.serve(async (req) => {
const { url, label } = await req.json();
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST",
headers: { Authorization: \`Bearer ${Deno.env.get("QRFLOW_KEY")}\`, "Content-Type": "application/json" },
body: JSON.stringify({ type: "url", destination_data: { url }, label }),
});
return new Response(await r.text(), { status: r.status, headers: { "Content-Type": "application/json" } });
});
// supabase secrets set QRFLOW_KEY=qrf_live_...
- npm 包
qrflow\仅使用 fetch 和 WebCrypto,因此无需修改即可在所有这些环境中运行。
Python:FastAPI、Flask、Django 或脚本
适用场景:你的后端使用 Python。
import os
from fastapi import FastAPI, HTTPException, Response
from qrflow import QRFlow, QRFlowError # https://qrflow.codes/sdk/qrflow.py
app = FastAPI()
qr = QRFlow(os.environ["QRFLOW_KEY"])
@app.post("/qr")
def make_qr(url: str, label: str | None = None):
try:
code = qr.create_code(type="url", destination_data={"url": url}, label=label)["code"]
except QRFlowError as e:
raise HTTPException(e.status, {"error": e.code, "message": str(e)})
return {"id": code["id"], "short_url": code["short_url"]}
@app.get("/qr/{code_id}.svg")
def qr_image(code_id: str):
import urllib.request
req = urllib.request.Request(qr.image_url(code_id), headers={"Authorization": f"Bearer {os.environ['QRFLOW_KEY']}"})
with urllib.request.urlopen(req) as r:
return Response(r.read(), media_type="image/svg+xml")
为每个订单、餐桌、产品、票券或活动创建一个 QR 码
适用场景:你的某个表中的每一行都需要一个自动生成的专属码。
- 在表中添加两列:qrflow_code_id (uuid) 和 qr_short_url (text)。
- 创建行时,使用该行的公开 URL 和能标识该行的标签(“Order 10432”、“Table 7”)POST /codes。保存 id 和 short_url。
- 如果该行对应的页面发生变化(新域名、新路径),PATCH destination_data。已打印的码仍可正常使用。
- 停用该行时,如果已经打印过任何码,则 PATCH { paused: true };如果没有打印过,则 DELETE。
- 需要一次创建数千个码(例如为 300 家餐厅的每张餐桌创建菜单码)?分批使用 POST /codes/bulk,并通过标签或顺序将返回的码对应回各行。
const { code } = await qr.createCode({
type: "url",
destination_data: { url: \`https://example.com/orders/${order.id}\` },
label: \`Order ${order.number}\`,
});
await db.orders.update(order.id, { qrflow_code_id: code.id, qr_short_url: code.short_url });
- Business 套餐的合理使用上限为 25,000 个已保存的码;API 的上限是该数量的两倍。如果你需要永久为每张收据创建一个码,请先联系我们:hello@qrflow.codes。
更改已打印码的跳转目标
适用场景:活动已结束、页面已迁移、PDF 已替换或季节已更替。
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "destination_data": { "url": "https://example.com/spring" } }'
暂停它,或为它设置结束日期
# Scans show a "paused" page instead of redirecting
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID -H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" -d '{ "paused": true }'
# Stops working after the date; null clears it
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID -H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" -d '{ "expires_at": "2026-12-31T23:59:59Z" }'
- 只有动态码可以更改跳转目标;静态码会返回 400 not_dynamic。Wi-Fi、vCard 和纯文本码将内容直接编码在图案中,因此永远不能设为动态码;对它们调用 POST /codes/:id/dynamic 会返回 400 not_dynamic_capable。对于 url、phone、email、sms 和 location 码,Free 套餐会将第一个码设为动态码,其余设为静态码;付费套餐中的所有码都是动态码。只要账户仍有可用额度,POST /codes/:id/dynamic 就能将静态码转换为动态码。之后请重新渲染并重新打印,因为图案会发生变化。
- 扫描器下次扫描时就会看到新的跳转目标,无需等待缓存过期。
在自己的域名上打印码
适用场景:你希望码中显示 go.example.com/menu,而不是 qrflow.codes/q/x7k2p9a。
- 在 Account 页面中的 Your own link domain 下添加 go.example.com,并在 DNS 服务商处创建页面显示的 CNAME。通常几分钟内即可完成验证。
- 此后,每个新动态码的 short_url 都会使用该域名。现有码也会切换:其图案中编码的是 qrflow.codes/q/...,该地址仍会继续重定向,因此已打印的码不会失效。
- 使用 slug 为链接设置易读名称:PATCH { "slug": "menu" } 会生成 go.example.com/menu。请在打印前完成此操作。
- 如果 Business 套餐配置了多个域名,GET /domains 会列出这些域名及其 id;在 POST 或 PATCH 中传入 domain_id,即可为每个码选择域名。
为链接命名并选择域名
curl https://qrflow.codes/api/v1/domains -H "Authorization: Bearer $QRFLOW_KEY"
# { "default_base": "https://go.example.com", "domains": [ { "id": "…", "host": "go.example.com", "is_default": true, … }, { "id": "…", "host": "qr.example.fr", … } ] }
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID -H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "slug": "menu", "domain_id": "<id of qr.example.fr>" }'
# short_url is now https://qr.example.fr/menu
在自己的管理后台中查看扫描图表
适用场景:你希望在自己的数据旁边查看每天、每个国家或每种设备的扫描次数。
const stats = await qr.scans(code.id, { from: "2026-09-01", to: "2026-09-30", group: "day" });
// stats.total -> 412
// stats.rows -> [{ key: "2026-09-01", scans: 18 }, { key: "2026-09-02", scans: 25 }, ...]
// Feed rows straight into Recharts, Chart.js, or a <table>.
const byCountry = await qr.scans(code.id, { group: "country" }); // [{ key: "US", scans: 300 }, { key: "MX", scans: 41 }]
const byDevice = await qr.scans(code.id, { group: "device" }); // mobile, desktop, tablet
- 每个请求最多涵盖 92 天;更长的时间范围请循环请求。日期使用 UTC。
- 如需实时数据而不必轮询,可为扫描事件订阅 webhook:系统会每隔几分钟分批发送每次扫描及其详细信息。
在 Next.js 中接收并验证 webhooks
适用场景:你希望在自己的数据库中近乎实时地获知码何时被扫描或更改。
- 在 Account › Webhooks 中创建 webhook,或使用 POST /webhooks 创建。将密钥(whsec_...)复制到 QRFLOW_WEBHOOK_SECRET 中;密钥只会显示一次。
- 解析前先将原始请求体读取为文本;签名覆盖的是精确的字节内容。
- 验证后,再根据事件类型进行处理。尽快返回 2xx;耗时操作应在响应后执行,或放入队列。
- 点击 webhook 上的 Test,接收带签名的 ping 并确认配置正确。
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(raw: string, header: string, secret: string): boolean {
const t = /t=(\d+)/.exec(header)?.[1], v1 = /v1=([a-f0-9]+)/.exec(header)?.[1];
if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(\`${t}.${raw}\`).digest("hex");
return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
export async function POST(req: Request) {
const raw = await req.text();
if (!verify(raw, req.headers.get("x-qrflow-signature") ?? "", process.env.QRFLOW_WEBHOOK_SECRET!)) {
return new Response("bad signature", { status: 401 });
}
const evt = JSON.parse(raw) as { id: string; event: string; created_at: string; data: any };
// evt.id is stable across retries: store it and skip duplicates.
switch (evt.event) {
case "scan": // evt.data.scans[]: code_id, label, slug, scanned_at, device, country, city, referrer, browser, os, language
break;
case "code.created": // evt.data.code, evt.data.source
case "code.updated": // evt.data.code, evt.data.changed[]
case "code.deleted": // evt.data.code { id, label, short_code, slug }
break;
case "ping": // the Test button
break;
}
return new Response(null, { status: 204 });
}
- 在本地开发时,可通过隧道公开开发服务器(cloudflared tunnel --url http://localhost:3000, 或 ngrok),并在开发期间将该 https URL 用作 webhook 地址。
- npm 包可为你完成这些操作:
import { parseWebhook } from "qrflow"\通过一次调用完成验证和解析(使用 WebCrypto,因此也可在 Workers 和 Deno 中运行)。Python 客户端提供 verify_webhook。
在 Python 中接收 webhooks
适用场景:使用 Flask、FastAPI 或 Django 接收相同的事件。
import os, json
from flask import Flask, request, abort
from qrflow import verify_webhook # https://qrflow.codes/sdk/qrflow.py
app = Flask(__name__)
@app.post("/qrflow")
def hook():
raw = request.get_data() # bytes, before any parsing
if not verify_webhook(raw, request.headers.get("X-QRFLOW-Signature", ""), os.environ["QRFLOW_WEBHOOK_SECRET"]):
abort(401)
evt = json.loads(raw)
if evt["event"] == "scan":
for s in evt["data"]["scans"]:
print(s["code_id"], s["scanned_at"], s["country"], s["device"])
return "", 204
从 CSV 创建数千个码
适用场景:为每个 SKU、座位、资产标签或邮寄物创建一个码。
import { parse } from "csv-parse/sync";
import { readFileSync } from "node:fs";
const rows = parse(readFileSync("skus.csv"), { columns: true }) as Array<{ sku: string; url: string }>;
const out: Array<{ sku: string; id: string; short_url: string }> = [];
for (let i = 0; i < rows.length; i += 2000) { // Business: 2,000 per request
const chunk = rows.slice(i, i + 2000);
const { codes, rejected, remaining_this_month } = await qr.bulkCreate(
chunk.map((r) => ({ destination: r.url, label: r.sku })),
);
codes.forEach((c, j) => out.push({ sku: chunk[j].sku, id: c.id, short_url: c.short_url }));
if (rejected.length) console.warn(rejected); // rows that were not web addresses
console.log(remaining_this_month, "left this month");
}
- Bulk 仅创建动态 url 码,且所有码使用相同的颜色。返回的码会按提交顺序排列,但会排除被拒绝的行;不确定时,请通过标签进行匹配。
- 每个 bulk 请求会触发一个包含 codes[] 的 code.created 事件,而不是每个码各触发一个事件。
让用户连接自己的 QRFLOW 账户(OAuth)
适用场景:你正在为其他人构建产品,并希望码创建在他们自己的 QRFLOW 账户中,而不是你的账户中。
- 注册一次客户端:使用 client_name 和 redirect_uris 调用 POST https://qrflow.codes/api/oauth/register。你会获得一个 client_id(机密客户端还会获得一个 client_secret)。
- 将用户发送到 /oauth/authorize,并附上 response_type=code、client_id、redirect_uri、scope、state 和 PKCE(code_challenge、code_challenge_method=S256)。
- 在 /api/oauth/token 处交换授权码。保存 refresh token;access token 的有效期为一小时。
- 使用 Authorization: Bearer <access_token> 调用 /api/v1。所有功能都与使用密钥时完全相同,但会遵循用户的套餐。
curl -X POST https://qrflow.codes/api/oauth/register -H "Content-Type: application/json" \
-d '{ "client_name": "Acme Menus", "redirect_uris": ["https://app.example.com/oauth/qrflow"], "token_endpoint_auth_method": "none" }'
# { "client_id": "dyn_…", "redirect_uris": [...], "grant_types": ["authorization_code","refresh_token"], … }
https://qrflow.codes/oauth/authorize?response_type=code&client_id=dyn_…&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fqrflow
&scope=profile%20codes%3Aread%20codes%3Awrite%20analytics%3Aread&state=…&code_challenge=…&code_challenge_method=S256
- Scope 与 API 密钥的六种 scope 相同。只申请所需的最少权限;同意页面会列出这些权限。
- 如果你的应用是聊天助手或 agent,请在授权请求中添加 resource=https://qrflow.codes/mcp,并改为与 MCP 服务器通信;令牌将绑定到该服务器。
Zapier、Make、n8n:完全无需编写代码
适用场景:你希望将扫描数据或新建的码发送到电子表格、Slack 频道或 CRM。
- 创建一个 catch-hook 触发器(Zapier:Webhooks by Zapier › Catch Hook;Make:Custom webhook;n8n:Webhook 节点),并复制其 https URL。
- 在 Account › Webhooks 中添加该 URL 并选择事件。点击 Test;工具中会显示 ping,并提供负载格式。
- 将 data.scans[](用于 scan)或 data.code(用于 code.*)映射到电子表格、消息或记录。
- 如需通过这些工具创建码,请使用它们的 HTTP 模块,向 POST /codes 发送请求并附上 Authorization 标头。将密钥保存在工具的凭据存储中。
- Zapier 现已提供 QRFLOW.codes 应用:其 Create QR Code、Update QR Code 和 Find 步骤,以及即时 New Scan 触发器,无需配置 webhook 或 API 密钥。请参阅 QRFLOW with Zapier。以下步骤适用于 Make、n8n 和其他工具。
- 这些工具无法验证签名。它们提供的 URL 无法被猜出,这就是你拥有的保护措施;请勿将其发布到任何地方。
- 如果列表已经保存在 Google Sheets 中,你可能根本不需要 webhook:QRFLOW for Google Sheets 插件可为每一行创建一个码,并将短链接和扫描次数写回表格;Premium 套餐可用,无需 API 密钥。请参阅 the Google Sheets add-on。
氛围编程
可直接粘贴的提示词
只要事先告知规则,编程助手就能构建正确的功能。这些提示词包含了相关规则。选择一个,填写方括号中的内容,助手就会在编写代码前阅读 Markdown 参考文档。
为我的应用添加 QR 码
Claude、ChatGPT、Cursor、Codex、Windsurf、Copilot Chat:粘贴到聊天中
Add QR codes to this project using the QRFLOW.codes API.
Read https://qrflow.codes/llms-full.txt before writing code; it is the complete reference.
Rules:
- The API key is in the environment variable QRFLOW_KEY. It must only be used server-side (route handler, server action, edge function). Never expose it to the browser.
- Create dynamic codes: POST https://qrflow.codes/api/v1/codes with { "type": "url", "destination_data": { "url": ... }, "label": ... }.
- Save the returned code.id and code.short_url on my record. short_url is what gets printed or displayed.
- Show the image by proxying GET /codes/:id/image.svg through my server, or by encoding short_url with a QR library on the client.
- Handle errors from the JSON body: { "error", "message" }. Map 402 to "upgrade needed", 429 to a retry with the Retry-After header.
What I want: [describe the feature, e.g. "every event in my events table gets a QR code that opens its public page; show it on the event admin page with a download button"].
让你的代码仓库了解 QRFLOW
添加到 CLAUDE.md、AGENTS.md、.cursorrules 或 .github/copilot-instructions.md 中
## QR codes (QRFLOW.codes)
- Docs: https://qrflow.codes/llms-full.txt (Markdown), https://qrflow.codes/api/v1/openapi.json (OpenAPI 3.1).
- Base URL https://qrflow.codes/api/v1, header Authorization: Bearer $QRFLOW_KEY. Server-side only.
- Codes are created with POST /codes { type: "url", destination_data: { url }, label }. Store code.id and code.short_url.
- Change the destination with PATCH /codes/:id { destination_data: { url } }. Never change slug/domain_id after printing.
- Image: GET /codes/:id/image.svg (needs the key). Prefer paused: true over DELETE when a print exists.
- Webhooks arrive as POST with X-QRFLOW-Signature (t=,v1=HMAC-SHA256 of "t.rawBody"); verify with the raw body.
在 Lovable、Bolt、v0、Replit 和其他应用构建器中
这类构建器以构建前端为主,并提供后端(Supabase、无服务器函数)
Integrate QRFLOW.codes QR codes. The API refuses browser calls, so create a backend function (Supabase Edge Function / serverless function) that holds the secret QRFLOW_KEY and calls POST https://qrflow.codes/api/v1/codes with { "type": "url", "destination_data": { "url": "<the page URL>" }, "label": "<name>" }. Return code.id and code.short_url to the UI and save them in the database. Render the QR in the UI by encoding short_url with a QR library; add a "Download for print" button that fetches /codes/:id/image.svg through the same backend function. Reference: https://qrflow.codes/llms-full.txt
管理我的码的自定义 GPT
ChatGPT › Create a GPT › Actions
Import from URL: https://qrflow.codes/api/v1/openapi.json
Authentication: API Key › Bearer › paste a Business key with the scopes you want the GPT to have.
Then the GPT can list, create, re-point and report on your codes. For a no-setup version, add the MCP connector instead (Developer mode › Plugins › https://qrflow.codes/mcp).
连接器启用后可以提出的要求
已连接 QRFLOW MCP 服务器的 Claude、ChatGPT、Claude Code
"Make a QR code for https://example.com/fall-menu, call it Fall menu, frame caption 'Scan for menu'."
"Which of my codes got the most scans this month? Show a breakdown by country for the top one."
"Point the 'Lobby poster' code at https://example.com/events/october."
"Name the 'Business card' code's link 'hi' on my domain."
"Pause every code with 'Summer' in the label."
"Make 40 codes, one per table, going to https://example.com/order?table=1 through 40."
"Show me the PNG of the 'Front door' code."
MCP 服务器
在 Claude、ChatGPT、Cursor 和 Claude Code 中使用
QRFLOW 是一个 MCP 服务器,地址为 https://qrflow.codes/mcp。连接一次并登录后,就可以提出诸如 “为我们的秋季菜单页面创建一个 QR 码,在我的域名上命名为 menu”、“将大厅海报上的码指向新页面” 或 “上周传单的扫描次数是多少,按国家统计?” 这样的要求。助手可以使用此 API 提供的相同工具,并遵循相同规则;创建的码会显示在你的控制面板中,来源标记为 mcp。
不是开发者?请参阅 Make QR codes with your AI assistant,其中提供了通俗易懂的说明,以及各个助手的具体操作步骤。
Glama 每小时独立评分并进行健康检查;同时列入 awesome-remote-mcp-servers 目录和官方 MCP Registry,名称为 codes.qrflow/qrflow。
连接
Customize › Connectors › Add custom connector › 粘贴地址,或在 QRFLOW 的目录条目中点击 Connect。Claude 会打开 QRFLOW 登录页面;点击 Allow。所有套餐均可使用。
https://qrflow.codes/mcp
Settings › Security and login › 开启 Developer mode,然后进入 Settings › Plugins › + › 粘贴地址;按提示登录。适用于 Plus、Pro、Team、Enterprise 和 Edu。
https://qrflow.codes/mcp
运行一条命令,然后输入 /mcp 登录。添加 Business 密钥作为标头即可跳过登录。
claude mcp add --transport http qrflow https://qrflow.codes/mcp
# or, with a key:
claude mcp add --transport http qrflow https://qrflow.codes/mcp --header "Authorization: Bearer $QRFLOW_KEY"
Cursor、Windsurf、VS Code 及任何 MCP 客户端
在该 URL 添加一个 HTTP 服务器。OAuth 登录会在浏览器中进行;也可以通过 Authorization 标头传入密钥。
{
"mcpServers": {
"qrflow": { "type": "http", "url": "https://qrflow.codes/mcp" }
}
}
你自己的 agent(Anthropic 或 OpenAI SDK)
将 MCP connector 或工具指向该 URL,并使用 Business 密钥作为 bearer;无需浏览器登录流程。
// Anthropic Messages API, MCP connector
mcp_servers: [{ type: "url", url: "https://qrflow.codes/mcp", name: "qrflow", authorization_token: process.env.QRFLOW_KEY }]
助手可以做什么
| 工具 | 功能 | Scope |
|---|---|---|
| list_code_kinds | 列出所有码类型、各自的字段以及所需套餐。助手在创建不常见的内容前会调用此工具。 | profile |
| list_domains | 列出你的链接域名、默认域名及其 id。 | domains:read |
| get_qr_image | 提供助手可显示或保存的 PNG,以及用于打印的 SVG URL。 | codes:read |
| get_account | 查看账户的套餐、功能和限制。 | profile |
安全机制
- 助手只会持有你账户的令牌;该令牌是在你于 QRFLOW 页面点击 Allow 后签发的。你可以随时在 Account › Connected apps 中断开连接。
- 令牌绑定到 MCP 服务器,无法用于 REST API。
- 所有写入操作都经过与控制面板相同的验证:目标地址白名单、套餐检查和合理使用上限。
- 具有破坏性的工具会明确说明自身行为:
delete_qr_code会提示模型在已有印刷品时优先暂停码。 - 发现文档位于
/.well-known/oauth-authorization-server和/.well-known/oauth-protected-resource;注册遵循 RFC 7591;仅支持 PKCE S256。
SDK 和 OpenAPI 规范
- TypeScript / JavaScript:
npm install qrflow(npm)。零依赖,支持 ESM 和 CommonJS,提供完整类型;可在 Node 18+、Bun、Deno 和 Workers 中运行。自动重试 429,并提供verifyWebhook/parseWebhook。 - Python 3.9+,仅使用标准库:qrflow.py。
- OpenAPI 3.1:/api/v1/openapi.json。导入 Postman 或 Insomnia、生成任意语言的客户端,或将其附加到 ChatGPT Action。
- 两个客户端都会抛出带类型的错误(
QRFlowError,包含status、code、message、retryAfter),并提供 webhook 验证器。如果你更愿意将其作为依赖 vendoring,单文件 TypeScript 源码仍位于 /sdk/qrflow.ts。
| TypeScript | Python | 调用 |
|---|---|---|
| me() | me() | GET /me |
| catalog() | catalog() | GET /catalog |
| listCodes({ limit, q }) | list_codes(limit, q) | GET /codes |
| getCode(id) | get_code(id) | GET /codes/:id |
| createCode(input) | create_code(**fields) | POST /codes |
| updateCode(id, patch) | update_code(id, **patch) | PATCH /codes/:id |
| deleteCode(id) | delete_code(id) | DELETE /codes/:id |
| makeDynamic(id) | make_dynamic(id) | POST /codes/:id/dynamic |
| scans(id, { from, to, group }) | scans(id, from_, to, group) | GET /codes/:id/scans |
| bulkCreate(rows, colors) | bulk_create(rows, **colors) | POST /codes/bulk |
| domains() | domains() | GET /domains |
| listWebhooks() / createWebhook() / testWebhook(id) / deleteWebhook(id) | list_webhooks() / create_webhook() / test_webhook(id) / delete_webhook(id) | /webhooks |
| imageUrl(id, size) | image_url(id, size) | 图片地址(使用密钥获取) |
| verifyWebhook(raw, header, secret) | verify_webhook(raw, header, secret) | 验证投递的签名 |
端点参考
基础 URL https://qrflow.codes/api/v1。请求体和响应均为 JSON。日期为 UTC 时区的 ISO 8601 格式。PATCH 只发送需要更改的字段。
GETprofile
账户适用的套餐、功能标志和限制,以及密钥的作用域。
curl https://qrflow.codes/api/v1/me \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "id": "…", "email": "ops@example.com", "plan": "business", "paid": true,
"features": { "dynamic_codes": true, "custom_domain": true, "link_names": true, "gs1": true, "api_keys": true },
"limits": { "saved_codes": 25000, "bulk_per_month": 10000, "bulk_per_request": 2000, "link_domains": 5, "requests_per_minute": 600 },
"auth": "api_key", "scopes": ["codes:read", "codes:write"] }
GETpublic
原生类型(url、wifi、vcard、email、phone、sms、text、location)和约 50 种子类型(Instagram、Google review、Wi-Fi、应用商店……),每种都列出所需字段和适用套餐。无需密钥。
curl https://qrflow.codes/api/v1/catalog
GETcodes:read
按最新优先排序。?limit= 最多为 100,?q= 用于搜索标签。
curl "https://qrflow.codes/api/v1/codes?limit=20&q=menu" \
-H "Authorization: Bearer $QRFLOW_KEY"
POSTcodes:write
规则与网站上的“保存”相同:付费套餐中的 url、phone、email、sms 和 location 码为动态码;Wi-Fi、vCard 和 text 会将内容编码在图案中。将子类型 id 放入 destination_data.subtype,即可创建 Google review 码等。可选的 domain_id 用于指定码上显示的链接域名(GET /domains 会列出这些域名)。
curl -X POST https://qrflow.codes/api/v1/codes \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "type": "url", "destination_data": { "url": "https://example.com/menu" }, "label": "Table tents", "frame_style": "caption-below", "frame_caption": "Scan for menu" }'
{ "code": { "id": "…", "label": "Table tents", "kind": "url", "dynamic": true, "short_code": "x7k2p9a",
"short_url": "https://go.example.com/x7k2p9a", "scans": 0, "image_url": "https://qrflow.codes/api/v1/codes/…/image.svg", … } }
GETcodes:read
返回码及其扫描次数、短链接和图片地址。
curl https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY"
PATCHcodes:write
可修改以下任意字段:destination_data(仅动态码,印刷品仍然有效)、label、paused、expires_at(ISO 格式或 null)、slug(你域名上的链接名称)、domain_id(此码使用的链接域名;null = 账户默认域名)、fg_color、bg_color、frame_style、frame_caption、frame_caption2。只发送要更改的字段。
curl -X PATCH https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "destination_data": { "url": "https://example.com/menu-fall" }, "slug": "menu" }'
DELETEcodes:write
永久删除,包括其扫描历史。动态码的印刷链接将停止解析。如果印刷品仍在流通,建议使用 paused: true。
curl -X DELETE https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY"
204 No Content
POSTcodes:write
印刷图案会发生变化(现在编码的是短链接),因此之后需要重新渲染图片。
curl -X POST https://qrflow.codes/api/v1/codes/$ID/dynamic \
-H "Authorization: Bearer $QRFLOW_KEY"
GETcodes:read
可直接用于印刷的 SVG,包含边框和颜色。?size= 用于设置模块网格的宽度(像素);文件本身无论如何都可以无损缩放。
curl https://qrflow.codes/api/v1/codes/$ID/image.svg \
-H "Authorization: Bearer $QRFLOW_KEY" -o code.svg
GETanalytics:read
?from= 和 ?to=(ISO 日期,最多 92 天,默认最近 30 天),以及 ?group= day、device、country、city、browser、os 或 referrer。数据与分析页面相同。
curl "https://qrflow.codes/api/v1/codes/$ID/scans?from=2026-09-01&to=2026-09-21&group=day" \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "code_id": "…", "from": "…", "to": "…", "group": "day", "total": 412,
"rows": [ { "key": "2026-09-01", "scans": 18 }, { "key": "2026-09-02", "scans": 25 }, … ] }
POSTcodes:write
一次调用最多创建 2,000 个 URL 码,且全部为动态码。计入与 Bulk 页面相同的每月批量额度(Business 套餐为 10,000)。非网址的行会出现在 rejected 中,其余行则会创建。
curl -X POST https://qrflow.codes/api/v1/codes/bulk \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "rows": [ { "destination": "https://example.com/t/1", "label": "Table 1" }, { "destination": "https://example.com/t/2", "label": "Table 2" } ] }'
{ "codes": [ … ], "rejected": [], "remaining_this_month": 9998 }
GETcodes:read
用于零售包装的码。每个产品包含一个 GTIN、包装上印刷的地址,以及其背后的链接。使用 ?q= 搜索名称和 GTIN。Business 套餐。
curl https://qrflow.codes/api/v1/products \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "products": [ { "gtin": "00860001234565", "name": "Wildflower Honey 12 oz",
"digital_link": "https://id.example.com/01/00860001234565",
"page_url": "https://id.example.com/p/00860001234565",
"links": [ { "link_type": "gs1:pip", "url": "…", "is_default": true, "batch": null } ] } ] }
POSTcodes:write
gtin 和 name 为必填项;brand 和 url 为可选项。写入前会验证校验位,8、12、13 和 14 位格式都会规范化为 14 位。已存在的 GTIN 会返回 409,而不会创建重复产品。
curl -X POST https://qrflow.codes/api/v1/products \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{"gtin":"00860001234565","name":"Wildflower Honey 12 oz","brand":"Sunny Acres","url":"https://sunnyacres.example/honey"}'
{ "product": { "gtin": "00860001234565", "digital_link": "https://id.example.com/01/00860001234565", … } }
PUTcodes:write
一个 GTIN 可以同时指向多个位置,每个位置都标注用途。默认使用 phone;请求类型的应用会使用对应类型。此操作具有幂等性:相同的 link_type 和 batch 会替换该链接,而不是新增一个,因此夜间脚本可以安全地运行两次。传入 batch 可将链接限定到某一批次,从而在发布召回信息时不影响同一生产批次中的其他产品。
curl -X PUT https://qrflow.codes/api/v1/products/00860001234565/links \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{"link_type":"gs1:recallStatus","url":"https://sunnyacres.example/recall-a42","title":"Recall notice","batch":"A42","is_default":true}'
GETanalytics:read
按 GTIN 统计最近 ?days= 天(1 到 365,默认 30)的数据,并按国家、设备、链接类型和批次细分。went_nowhere 统计未找到目标位置的扫描次数,理应为零。
curl "https://qrflow.codes/api/v1/products/00860001234565/scans?days=30" \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "gtin": "00860001234565", "days": 30, "total": 412, "went_nowhere": 0,
"by_link_type": [ { "key": "gs1:pip", "scans": 390 }, { "key": "gs1:recallStatus", "scans": 22 } ],
"by_batch": [ { "key": "A42", "scans": 22 } ] }
GETdomains:read
已连接的域名、各自的状态,以及动态码默认使用的域名(default_base)。将某个域名的 id 作为代码上的 domain_id 传入,即可让该码使用其他域名。
curl https://qrflow.codes/api/v1/domains \
-H "Authorization: Bearer $QRFLOW_KEY"
GETwebhooks:manage
你的 webhook,包括其事件、最近状态和失败次数。
curl https://qrflow.codes/api/v1/webhooks \
-H "Authorization: Bearer $QRFLOW_KEY"
POSTwebhooks:manage
url 必须是公共主机上的 https 地址;events 可以是 scan、code.created、code.updated、code.deleted 中的任意事件。签名密钥只会返回一次。
curl -X POST https://qrflow.codes/api/v1/webhooks \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/hooks/qrflow", "events": ["scan", "code.updated"] }'
{ "webhook": { "id": "…", "url": "…", "events": ["scan", "code.updated"], "active": true, "secret": "whsec_…" } }
POSTwebhooks:manage
立即发送带签名的 ping,并报告响应。
curl -X POST https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $QRFLOW_KEY"
DELETEwebhooks:manage
停止所有投递,包括已排队的重试。
curl -X DELETE https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $QRFLOW_KEY"
204 No Content
GETpublic
边框 id 及其所需内容(说明文字、第二行),按自定义器中的分组方式排列。无需密钥。
curl https://qrflow.codes/api/v1/frames
Code 对象
所有涉及代码的端点都会返回相同结构。忽略不认识的字段;后续可能会添加新字段。
| 字段 | 类型 | 含义 |
|---|---|---|
| id | uuid | 稳定 id。在其他所有调用中使用它。 |
| label | string | null | 控制面板中的名称。最多 120 个字符。可使用 ?q= 搜索。 |
| kind | string | 目录 id:url、wifi、instagram、googlereview,... kind_label 是人类可读的名称。 |
| type | string | 编码类型:url、text、wifi、vcard、email、phone、sms、location。 |
| destination_data | object | 你发送的字段(以及 kind 对应的 subtype)。destination 是这些字段的单行摘要。 |
| dynamic | boolean | 为 true 时,扫描会经过 QRFLOW,且目标地址可以更改。dynamic_capable 表示此类型在付费套餐中是否可以设为动态码。 |
| short_code | string | 七个字符,永不更改。 |
| short_url | string | 动态码的印刷内容。设置后会包含你的域名和 slug。 |
| domain_id | uuid | null | 此码使用的链接域名;null 表示账户默认域名。 |
| fg_color, bg_color | hex | 模块和背景颜色。 |
| has_logo | boolean | 已在控制面板中添加徽标;image.svg 会包含该徽标。 |
| frame_style, frame_caption, frame_caption2 | string | null | 边框 id 和说明文字,与自定义器中的设置相同。 |
| scans | integer | 生命周期内的扫描次数。 |
| created_at, updated_at | ISO 8601 | UTC。 |
| manage_url | url | 代码在控制面板中的页面,可用于创建“在 QRFLOW 中打开”链接。 |
| image_url | url | GET /codes/:id/image.svg。需要 Authorization 标头;不是公开图片 URL。 |
| svg_download_url, png_download_url | url | 相同的 SVG(边框、颜色、徽标)和普通 PNG,通过签名链接提供;无需标头,链接有效期为 24 小时:适用于 <img> 标签、脚本和需要保存文件的助手。download_expires_at 表示链接何时失效;每次读取代码都会返回新的链接。 |
其他结构:Scans(code_id, from, to, group, total, rows[key, scans])、Domain(id, host, status, active, is_default, verified_at, grace_until)、Webhook(id, url, events, active, last_status, last_delivery_at, consecutive_failures,以及一次性返回的 secret)、Me(id, email, plan, paid, features, limits, auth, scopes)和 Error(error, message)。OpenAPI 文档为所有属性提供了类型定义。
Business
Webhook
发生事件时,QRFLOW 会调用你的 https URL。可在 Account › Webhooks 中创建,或使用 POST /webhooks 创建;签名密钥只会提供一次。每个账户最多 10 个。
| 事件 | 触发时机 | data |
|---|---|---|
| scan | 批量发送:每隔几分钟发送一次,包含上次投递以来的所有新扫描,每次最多 500 条。 | count、from、to、scans[],包含 code_id、label、short_code、slug、scanned_at、device、country、city、referrer、browser、os、language |
| code.created | API 和助手创建后立即发送;从控制面板创建则在几分钟内发送。批量请求会发送一个包含 bulk: true 和 codes[] 的事件。 | code、source |
| code.updated | 发送时机相同。涵盖目标地址、标签、暂停状态、过期时间、链接名称、域名、颜色、边框以及转换为动态码。 | code、changed[](已更改的字段名称) |
| code.deleted | 发送时机相同。 | code: { id, label, short_code, slug } |
| ping | 按下 Test 时发送。 | webhook_id、message |
接收内容
每个负载都是 { id, event, created_at, data }。同一次投递的重试中,id 保持不变,因此你可以据此去重。
{
"id": "9b1c6d2e-…",
"event": "scan",
"created_at": "2026-09-21T18:05:00.000Z",
"data": {
"count": 2,
"from": "2026-09-21T18:00:00.000Z",
"to": "2026-09-21T18:04:12.331Z",
"scans": [
{ "code_id": "…", "label": "Table tents", "short_code": "x7k2p9a", "slug": "menu", "scanned_at": "2026-09-21T18:03:40.101Z",
"device": "mobile", "country": "US", "city": "Las Vegas", "referrer": null, "browser": "Safari", "os": "iOS", "language": "en-US" },
{ "code_id": "…", "label": "Table tents", "short_code": "x7k2p9a", "slug": "menu", "scanned_at": "2026-09-21T18:04:12.331Z",
"device": "mobile", "country": "MX", "city": "Tijuana", "referrer": null, "browser": "Chrome", "os": "Android", "language": "es-MX" }
]
}
}
{
"id": "2f0a…",
"event": "code.updated",
"created_at": "2026-09-21T18:06:00.000Z",
"data": {
"code": { "id": "…", "label": "Table tents", "kind": "url", "dynamic": true, "short_url": "https://go.example.com/menu", "scans": 412, "…": "…" },
"changed": ["destination_data"]
}
}
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: QRFLOW-Webhooks/1.0 (+https://qrflow.codes/developers)
X-QRFLOW-Event: scan
X-QRFLOW-Signature: t=1758477900,v1=5f1c…e9
验证签名
X-QRFLOW-Signature: t=<unix seconds>,v1=<hex>。使用你的密钥对 ${t}.${rawBody} 计算 HMAC-SHA256,并以恒定时间比较结果与 v1;如果 t 超过五分钟前,则拒绝请求。使用收到的原始字节,切勿重新序列化对象。Next.js 和 Python 的可用接收端示例位于 recipes 中,两个 SDK 也都包含此辅助函数。
投递规则
- 在 8 秒内返回任意 2xx 响应。响应后再处理任务。
- 其他响应会在 1、5、15、60、240 和 720 分钟后重试。
- 连续失败 20 次后,webhook 会被关闭,并向账户所有者发送电子邮件。修复接收端后重新启用;已排队的重试会继续。
- URL 必须是公共主机上的 https 地址。localhost、私有地址段和 qrflow.codes 本身都会被拒绝。开发时请使用隧道。
- 按下 Test 可接收带签名的
ping,并查看服务器返回的状态。
错误
每个错误都是 { "error": "<code>", "message": "<what to do>" },并带有下表中的状态码。错误消息面向用户,请直接显示。
| 状态 | error | 含义 |
|---|
症状、原因、解决方法
故障排除
每次调用都返回 401 invalid_token
原因:标头错误,或密钥尚未启用。
解决方法:准确发送 Authorization: Bearer qrf_live_…(中间是空格,不是冒号)。检查密钥是否已在 Account › API keys 中撤销。如果密钥是从聊天或文档中复制的,请留意末尾的句点或智能引号。
使用在 MCP 服务器上有效的令牌调用 /api/v1 时返回 401
原因:为 https://qrflow.codes/mcp 签发的令牌与该服务器绑定。
解决方法:REST API 请使用 API 密钥,或在不带 resource= 的情况下再次执行 OAuth 流程,以获取 REST API 的令牌。
创建密钥或 webhook 时返回 402 upgrade_required
原因:这两项功能都仅限 Business 套餐。
解决方法:在 /pricing 升级,或使用 MCP 服务器;所有套餐均可通过登录使用该服务器。
OAuth 应用调用 POST /codes 时返回 402
原因:用户的套餐不包含应用请求的功能(动态码、域名)。
解决方法:先读取 GET /me 中的 features 并据此调整:仍然创建代码(Free 套餐下会创建静态码),或告知用户需要升级到相应套餐。
403 insufficient_scope
原因:创建密钥时作用域已固定。 修复:创建一个包含所需权限范围的新密钥,并撤销旧密钥。对于 OAuth,请在授权请求中请求相应的权限范围。
PATCH destination_data 时出现 400 not_dynamic
原因:代码是静态的:属于 Wi-Fi/vCard/文本类型,或者是在 Free 套餐中已用完唯一的免费动态码后创建的代码。
修复:对于 url/phone/email/sms/location,在账户仍有额度时调用 POST /codes/:id/dynamic,然后重新下载并打印(图片会改变)。Wi-Fi、vCard 和文本代码永远无法设为动态;请改为创建一个打开网页的 url 代码。
设置 slug 时出现 400 no_domain
原因:链接名称只能用于你自己的域名。
修复:先在 Account 页面连接并验证域名。在 qrflow.codes/q 上,路径始终是 short_code。
slug 出现 409 conflict
原因:你的其他代码已使用该名称。
修复:调用 GET /codes?q= 查找该代码,或选择其他名称。名称仅在账户内唯一,并非全局唯一。
浏览器控制台出现 CORS 错误
原因:API 只接受服务器到服务器的调用(以及 Canva)。这是有意为之:网页中的密钥会泄露。
修复:将调用移到路由处理程序、服务器操作、边缘函数或后端中,并从页面调用该服务。
图片上显示 QRFLOW 标记
原因:该代码由未登录的用户创建。此标记仅用于匿名下载。
修复:任何账户都可以移除该标记,包括免费账户。已保存代码的图片不会带有该标记。
添加域名后,short_url 仍显示 qrflow.codes/q/…
原因:域名尚未验证,或其 CNAME 配置错误。
修复:在 Account 页面或通过 GET /domains 检查状态(状态必须为 verified)。验证完成后,现有代码会自动切换。
在 <img> 标签中,image_url 返回 401
原因:它需要 Authorization 标头,而 <img> 无法发送该标头。
修复:使用同一个 Code 对象中的 svg_download_url 或 png_download_url:这些签名链接无需标头,有效期为 24 小时。如需永久使用,请通过服务器代理 image_url(参见 Next.js 示例),或自行编码 short_url。
我需要 PNG,而不是 SVG
原因:SVG 包含边框和徽标;PNG 是纯二维码。
修复:GET /codes/:id/image.png(使用 bearer 或签名的 png_download_url)会返回 PNG,尺寸为 256 到 2048 px。如需带边框的 PNG,请使用 sharp 或 resvg 转换 SVG(sharp(svgBuffer).png().toBuffer())。
助手说图片端点拒绝了请求,于是自行绘制了二维码
原因:它获取了 image_url,而该地址需要 bearer。
修复:现在每个代码都带有 png_download_url 和 svg_download_url,get_qr_image 也会返回它们;助手无需登录即可通过 curl 获取这些链接。自行绘制、编码相同 short_url 的二维码仍然有效,也仍会统计扫描次数,但不包含边框和徽标。
Webhook 始终没有送达
原因:URL 规则或接收端存在问题。
修复:URL 必须是公共主机上的 https 地址(不能是 localhost、私有 IP 或 qrflow.codes)。在 webhook 上点击 Test:结果会显示你的服务器返回的状态。扫描事件会批量发送,最长可能需要约五分钟;来自控制面板的 code.* 事件也会排队几分钟,而 API 和 MCP 写入会立即送达。
签名始终无法验证
原因:你对重新序列化后的请求体进行了签名验证。
修复:在解析 JSON 之前,使用收到的原始字节进行验证。在 Express 中,对该路由使用 express.raw({ type: 'application/json' });在 Next.js App Router 中使用 await req.text();在 Flask 中使用 request.get_data()。然后计算 ${t}.${raw}\ 的 HMAC-SHA256。
Webhook 自动关闭了
原因:连续失败二十次。
修复:修复接收端,然后重新将其设为 active(Account › Webhooks,或删除后重新创建)。发生此情况时,你会收到邮件通知。排队的重试会继续执行。
Webhook 重复送达
原因:响应缓慢的 2xx(超过 8 秒)会被视为失败并重试。
修复:先响应,再处理。使用 payload 中的 id 进行去重;该 id 在重试期间保持不变。
导入期间出现 429 rate_limited
原因:每个密钥每分钟最多 600 个请求。
修复:使用 POST /codes/bulk(单个请求最多 2,000 个代码),而不是每个代码单独发送一个 POST;或者等待 Retry-After 指定的秒数。
我删除了一个代码,打印的海报现在显示“Code not found”
原因:删除操作不可逆,并会使链接失效。
修复:无法撤销。下次请使用 PATCH { paused: true };暂停的代码会显示友好提示页,并且可以恢复。
降级后,我的密钥停止工作了
原因:离开 Business 套餐后,密钥仍可使用 30 天,之后会返回 402。
修复:重新订阅;没有任何内容被删除,同一批密钥会再次生效。
列表中没有你遇到的问题?请联系 hello@qrflow.codes,并提供确切的请求内容和收到的 JSON 错误。Business 账户可获得优先支持。
限制与合理使用
| 限制 | |
|---|---|
| 每个密钥每分钟的请求数 | 600。超过后返回带有 Retry-After 的 429。 |
| 每个账户的密钥数 | 10 |
| 每个账户的 Webhook 数 | 10 |
| 已保存代码数(合理使用) | Premium 为 1,000,Business 为 25,000;API 在达到该数量两倍时停止。 |
| 批量操作 | Premium 每月 500 个(每次请求 500 个);Business 每月 10,000 个(每次请求 2,000 个)。 |
| 链接域名 | Premium 为 1 个,Business 为 5 个 |
| 扫描次数 | 不限。Premium 每个代码每月达到 100,000 次扫描、Business 达到 1,000,000 次扫描时会收到提醒邮件;不会进行限流。 |
| 扫描分析时间范围 | 每个请求 92 天 |
| 列表页大小 | 100(?limit=) |
| 标签 / 说明文字 / slug | 120 / 60 / 40 个字符 |
| Webhook 超时与重试 | 8 秒;分别在 1、5、15、60、240 和 720 分钟后重试;连续失败 20 次后关闭。 |
| 离开 Business 套餐后 | 密钥和 webhook 继续工作 30 天,之后返回 402。不会删除任何内容。 |
合理使用额度是套餐定价所依据的范围。达到该数量时不会限流;API 会在达到其两倍时停止,并会先由工作人员通过邮件联系你。如需更高用量,请联系 hello@qrflow.codes。
安全性:保护你和扫描二维码的人
QRFLOW 如何保护你的账户
- 密钥只显示一次,并以 SHA-256 哈希形式存储。QRFLOW 的任何人都无法读取密钥;如果你丢失了密钥,请创建一个新密钥。
- 每个请求都限定在密钥所属的账户内。其他账户的代码 id 会返回 404,不会泄露信息。
- 每个密钥的权限范围都是固定的,因此用于报告仪表板的密钥无法创建或删除代码。
- 每个密钥每分钟最多 600 个请求;超过后会明确返回 429,不会拖慢所有人的服务。
- 目标地址采用允许列表:http、https、mailto、tel、sms、geo,以及少量应用 scheme(whatsapp、tg、signal、spotify、应用商店)。创建时会拒绝 javascript:、data: 和 file:,因此即使集成遭到入侵,也无法将你的代码变成攻击工具。
- Webhook URL 必须是公共主机上的 https 地址;QRFLOW 绝不会调用私有网络或自身。每次投递都会签名,每个 payload 都有稳定的 id。
- OAuth 客户端使用 PKCE S256 注册,令牌会绑定到签发它的服务器;发给 MCP 服务器的令牌无法在 REST API 上重放。
- 任何人都可以在 Account 页面撤销密钥或断开应用连接;更改会立即生效。
你需要采取的措施
- 使用环境变量,绝不要将密钥写入源代码。如果密钥进入了 git 历史记录,请撤销它。
- 仅在服务器端调用。API 会拒绝浏览器来源,但包装 API 的自有端点也需要身份验证,否则任何人都能使用你的额度创建代码。
- 为每个集成单独创建密钥,并仅授予其所需的权限范围;密钥名称应注明对应的集成。这样撤销密钥时只会影响一个集成。
- 验证 webhook 签名,并拒绝时间戳早于五分钟的请求。
- 如果用户数据会写入标签或目标地址,请记住 QRFLOW 会存储这些数据;尽可能避免在标签中放入个人数据。
扫描会记录哪些信息,不会记录哪些信息
- 每次重定向都会存储设备类型、国家、城市、引荐来源、浏览器、操作系统和语言,这些信息根据请求推导得出;还会存储由代码 + 日期 + IP + 用户代理生成的单向哈希,以便所有者统计独立访客。无法通过该哈希还原地址。
- 不会在扫描者的设备上设置 Cookie,也不会将 IP 地址本身与扫描记录一同保存。已知机器人和链接预览爬虫会被跳过。
- 删除代码会删除其扫描记录。删除账户会删除所有内容。
- 完整文本:https://qrflow.codes/privacy 和 https://qrflow.codes/terms.
版本管理与稳定性
API 的版本号位于路径中:/api/v1。在 v1 中,我们会添加字段、端点、类型和事件;不会删除或重命名任何内容,你的代码应忽略响应中的未知字段。
如果必须对 v1 进行破坏性更改,我们会以 /api/v2 的形式发布,并至少让 v1 继续运行十二个月。我们会提前 90 天通过邮件通知密钥所有者有关弃用的信息。
MCP 服务器的工具遵循相同规则:只会添加参数,每个工具都会保留原有名称。
/api/v1/openapi.json 中的 OpenAPI 文档和 /llms-full.txt 中的 Markdown 文档均由提供 API 服务的代码生成,因此描述的是当前线上运行的内容。
开发者常见问题
使用 QRFLOW API 需要付费吗?
API 密钥包含在 Business 套餐中,每月 $29,按月订阅。MCP 服务器(Claude、ChatGPT、Cursor、Claude Code)和供你自己的应用使用的 OAuth 可通过登录在所有套餐中使用,其可创建的内容受套餐限制。GET /catalog、GET /frames 和 /preview.svg 完全不需要密钥。
我可以通过 API 免费生成二维码吗?
不能使用密钥免费生成。对于纯静态图片,qrflow.codes 上的免费生成器或任何开源二维码库都可以满足需求。API 面向动态代码、自有域名、分析、批量操作和 webhook,这些功能属于付费账户。
我可以从浏览器调用 API 吗?
不可以。API 会拒绝浏览器来源,以确保密钥不会出现在网页中。请从路由处理程序、服务器操作、边缘函数或后端调用 API,再由页面调用这些服务。
可以获取哪些图片格式?
SVG 支持自定义颜色、边框、说明文字和徽标(GET /codes/:id/image.svg,标称尺寸为 256 到 4096 px);另有纯 PNG(GET /codes/:id/image.png,尺寸为 256 到 2048 px)。两者都可以使用 bearer 获取,也可以使用每个 Code 对象都带有的签名 svg_download_url / png_download_url 获取;这些链接无需标头,有效期为 24 小时。MCP 工具 get_qr_image 会以内嵌形式返回 PNG,并提供这两个链接。
打印后还能更改二维码吗?
可以,前提是它是动态代码(付费套餐中的 url、phone、email、sms、location)。使用新的 destination_data 调用 PATCH /codes/:id;图片不会改变,但下一次扫描会跳转到新的目标地址。Wi-Fi、vCard 和文本代码的内容直接保存在图片中,无法更改。
short_url 和目标地址有什么区别?
short_url 是图片中编码的链接(go.example.com/menu)。目标地址是该链接重定向到的位置(https://example.com/menu-fall)。打印一次 short_url 后,你可以随意更改目标地址。
代码可以使用我自己的域名吗?
可以。Premium 可连接 1 个域名,Business 可连接 5 个;你需要添加 CNAME 并在 Account 页面完成验证。Business 用户可以通过 domain_id 为每个代码选择域名。链接名称(slug)可在该域名下创建易读的路径。
扫描记录会保存扫描者的哪些信息?
设备类型、国家、城市、引荐来源、浏览器、操作系统和语言,这些信息来自请求;此外还会生成单向的每日哈希,用于统计独立访客。不使用 Cookie,也不存储 IP 地址。足以生成图表,但不足以识别任何人。详情:https://qrflow.codes/privacy#scans
有 npm 或 PyPI 软件包吗?
npm:npm install qrflow\(https://www.npmjs.com/package/qrflow),零依赖,支持 ESM 和 CommonJS,提供完整的 TypeScript 类型,可在 Node 18+、Bun、Deno 和 Workers 中运行;它封装了所有端点,会在遇到 429 时重试,并包含 verifyWebhook/parseWebhook。Python:https://qrflow.codes/sdk/qrflow.py 提供单文件客户端(仅使用标准库),包含 verify_webhook;PyPI 软件包将随后推出。
它支持 Claude、ChatGPT、Cursor 和 Claude Code 吗?
支持。QRFLOW 是一个 MCP 服务器,地址为 https://qrflow.codes/mcp.。将其添加为连接器,登录一次,然后用日常语言提出请求。11 个工具涵盖创建、编辑、暂停、命名、批量操作、分析、图片和域名。
我自己的用户可以将其 QRFLOW 账户连接到我的应用吗?
可以,使用 OAuth 2.0。通过 /api/oauth/register 注册客户端(无需账户),使用 PKCE 将用户引导至 /oauth/authorize,然后使用他们的令牌调用 API。生成的代码会根据用户的套餐存入其账户。
如何在 localhost 上测试 Webhook?
使用隧道(cloudflared 或 ngrok)公开你的开发服务器,并将其 https 地址用作 Webhook URL,然后在 Account › Webhooks 中点击 Test,即可收到带签名的 ping。Webhook URL 必须是公开的 https 地址;localhost 和私有地址会被拒绝。
如果我取消 Business 套餐,我的集成会怎样?
密钥和 Webhook 会继续工作 30 天,之后返回 402。代码、扫描记录和域名会保留在账户中。重新订阅后,所有功能都会恢复,且密钥保持不变。
如何通过 API 创建 Google 评价、Instagram、Wi-Fi 或 PDF 代码?
GET /catalog 会列出所有类型及其字段。然后使用对应类型的 type 和 fields 发送 POST /codes;对于以下类型,还需添加 subtype:{ type: 'url', destination_data: { subtype: 'googlereview', placeId: 'ChIJ…' } }、{ type: 'wifi', destination_data: { ssid, password, encryption: 'WPA' } }、{ type: 'url', destination_data: { subtype: 'instagram', handle: 'acme' } }。
API 能否将徽标上传到代码中?
暂时不能。请在控制面板中添加徽标;image.svg 会包含该徽标,has_logo 会告知你徽标是否存在。颜色、边框和说明文字都可以通过 API 设置。
API 稳定吗?
v1 只会增加内容;不会删除或重命名。破坏性变更会以 v2 的形式发布,v1 至少会继续提供十二个月,并提前 90 天通过电子邮件通知。
面向代理、工具和阅读本文的助手
机器可读
本页的所有内容都有可供软件获取的格式。所有内容均由提供 API 的代码生成,因此始终保持最新。
| URL | 内容 | |
|---|---|---|
| llms-full.txt | https://qrflow.codes/llms-full.txt | 本完整参考文档的 Markdown 版本:概念、所有端点、所有 MCP 工具、操作指南、故障排除和常见问题。与本页由同一来源生成。 |
| developers.md | https://qrflow.codes/developers.md | 同一份文档,适用于获取 a.md 的工具。 |
| llms.txt | https://qrflow.codes/llms.txt | 面向助手的网站索引,指向此处。 |
| 单页 API 介绍 | https://qrflow.codes/qr-code-api | API 的功能、何时客户端库是更好的选择,以及费用。本文档的简明版本,帮助你做决策,而非着手构建。 |
| openapi.json | https://qrflow.codes/api/v1/openapi.json | OpenAPI 3.1。可导入 Postman、Insomnia、代码生成器或 ChatGPT Action。 |
| MCP server | https://qrflow.codes/mcp | Streamable HTTP、通过动态注册进行 OAuth,或将 Business 密钥用作 bearer。 |
| server.json | https://qrflow.codes/.well-known/mcp/server.json | MCP 注册表清单。 |
| OAuth 发现 | https://qrflow.codes/.well-known/oauth-authorization-server | RFC 8414 元数据;受保护资源文档就在旁边。 |
| npm 包 | https://www.npmjs.com/package/qrflow | npm install qrflow。类型化客户端、零依赖、Webhook 验证。Python 单文件客户端:https://qrflow.codes/sdk/qrflow.py. |
| GitHub | https://github.com/nativecodeapps/qrflow-sdk | 客户端、OpenAPI 快照,以及适用于 Next.js、Workers、Express、FastAPI 和 Flask Webhook 的可运行示例。欢迎提交 Issues 和 PR。 |
如有问题、想法,或希望我们添加某种代码,请联系:hello@qrflow.codes。条款:/terms。隐私:/privacy。