用 REST API 从你自己的系统生成二维码：10 分钟上手

2026-10-12 · 更新于 2026-10-26 api developers automation

要从你自己的系统生成二维码，只需向 QR Maker REST API 发送一次带身份验证的 POST 请求，带上目的地网址和你自己的业务编号，再把返回的短链接渲染出来。用业务编号让重试变得安全，在同一次调用里请求 SVG，页面变了以后再用 PATCH 修改目的地。API 在 Business 版提供，应该从你的服务器调用，而不是从浏览器调用。

准备工作

Business 版套餐和一个 API 令牌。在「设置」页的「API 令牌」里创建，显示时立即复制：它以 qrs_ 开头，只显示一次。只用来拉取报表的令牌，选只读权限。
一个服务端运行环境。API 不允许浏览器跨域调用，所以令牌要留在你的服务器上。
你自己系统里每个码的稳定编号，比如订单号、SKU 或推荐码。它就是 external_id。

基础地址是 https://qrmaker.ai/api/v1，每个请求都带上 Authorization: Bearer qrs_...。

第 1 步：创建一个码

curl -X POST "https://qrmaker.ai/api/v1/qrcodes?include=svg" \
  -H "Authorization: Bearer $QR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://shop.example.com/product/AB12CD?ref=qr",
    "external_id": "AB12CD",
    "name": "Product AB12CD",
    "folder": "spring-campaign"
  }'

只有 target_url 是必填的。返回结果里包含这个码，其中有一个 short_link，比如 https://qrmk.cc/hzu23X；因为加了 ?include=svg，svg 字段里还有 SVG 图形代码。只有这个短链接应该被编码进图片或分享出去。之后修改 target_url，图片不会变。

第 2 步：用 external_id 让重试变得安全

网络会出错，任务会重复执行。如果你用同样的 external_id 和同样的 target_url 再发一次，API 不会创建第二个码，而是返回已有的那个，状态码 200，并带上 X-Idempotent-Replay: true 响应头。对已存在的 external_id 提交不同的 target_url，会返回 409，所以重试永远不会悄悄改掉一个已印刷码的去向。

第 3 步：使用 SVG

把 SVG 原样存储或输出即可。它能缩放到任何印刷尺寸，也能直接放进 img 标签。之后要再获取，就调用 GET /v1/qrcodes/{id}/svg，可选 size 和 margin 参数；响应带有 ETag，所以你可以缓存它，只在样式变化时重新下载。API 不生成 PNG 文件。如果需要 PNG，请在你自己的系统里把 SVG 转换过去。

第 4 步：不重印就修改目的地

curl -X PATCH "https://qrmaker.ai/api/v1/qrcodes/by-external-id/AB12CD" \
  -H "Authorization: Bearer $QR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "target_url": "https://shop.example.com/product/AB12CD-v2" }'

你可以用自己的编号查找码，所以根本不需要保存 QR Maker 的 ID。新网址会经过和在网站上填写时相同的安全检查。

第 5 步：读取结果

GET /v1/qrcodes/{id}/analytics 返回扫码次数、每天的独立访客数，以及按国家、设备、操作系统、浏览器、来源、语言和位置标签的细分，日期范围和时区由你选择。GET /v1/analytics/summary 一次调用就能汇总多个码，免得每个码各发一次请求。如果你更想要数据流，GET /v1/scans 会按顺序返回新的扫码事件，你只需保存最后看到的 next_since_id。

频率限制和额度

每个账户每分钟可以发 120 次 API 请求，由账户下所有令牌共享，每个响应都带有显示剩余额度的响应头。Business 版每月包含 50,000 次成功请求；返回 4xx 或 5xx 状态的失败请求不计入。批量任务可以用 POST /v1/qrcodes/batch，每次请求最多创建 100 个码，每个码各自保持幂等。

一个简短的 Node 示例

const res = await fetch('https://qrmaker.ai/api/v1/qrcodes?include=svg', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.QR_TOKEN}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ target_url: url, external_id: orderId }),
})
if (!res.ok) throw new Error(`QR API ${res.status}: ${(await res.json()).code}`)
const { data } = await res.json()
// data.short_link 是印刷出来的码里编码的内容；data.svg 是图片

处理错误时，依据错误响应里稳定不变的 code 字段，而不是给人看的提示文字。

下一步

API 参考文档列出了所有接口和错误码，概览页里有 OpenAPI 文件、Postman 集合和完整示例程序的链接。不想写服务器代码也能生成二维码，见 Google 表格以及 Make、n8n 和 Zapier 的教程。

常见问题

可以从浏览器调用 API 吗？

不可以。浏览器直接调用 API 会把你的令牌暴露给每一个访客。从你的服务器调用，再把 SVG 或短链接传给页面。

令牌泄露了怎么办？

在「设置」里撤销它，再创建一个新的。令牌只能调用二维码 API，不能修改你的密码、账单或域名；只读令牌则不能创建、修改或删除任何东西。

码能用我自己的域名吗？

能。Business 版可以连接一个自有短链接域名。创建码时把它作为 short_domain 传入，短链接就会使用你的域名，而不是共享域名。