二维码 API：创建和追踪动态二维码

可以用它做什么

每个订单、商品或桌位一个码按你自己的记录建码，每个码都带着你自己的编号。

一次几千个每个请求最多建 100 个码，每一个都可以单独安全重试。

随时更换目标网址一个 PATCH 请求就能把已印刷的码指向新页面，码图不变。

可直接印刷的 SVG按需要的尺寸和留白获取任意码的 SVG，带上你的 Logo 和配色。

把扫码数据放进你的报表按天、国家、设备、App 和投放位置汇总，时区由你指定。

不需要 webhook 的实时数据按顺序拉取新的扫码事件，只需保存一个游标，你这边不用开放任何接口。

一个请求创建一个码

发送目标网址和你自己的编号。响应里有要编码的短链接；带上 include=svg 还能同时拿到做好的码图。

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",
    "external_id": "AB12CD",
    "name": "Product AB12CD",
    "folder": "spring-campaign",
    "style": { "dot_style": "fluid", "finder_shape": "smooth" }
  }'

{
  "success": true,
  "data": {
    "id": "hzu23X",
    "external_id": "AB12CD",
    "target_url": "https://shop.example.com/product/AB12CD",
    "short_link": "https://qrmk.cc/hzu23X",
    "status": "active",
    "scan_count": 0,
    "image_version": "a1b2c3d4e5f60718",
    "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1000 1000\" …>"
  }
}

编码进二维码的应该是 short_link，而不是你自己的网址：有了它，码才能改址、才能统计。再次发送同一个 external_id 会返回同一个码，所以重试不会产生重复。

接口一览

POST /v1/qrcodes: 创建一个码（加 ?include=svg 同时拿到码图）
POST /v1/qrcodes/batch: 一个请求最多创建 100 个码
GET /v1/qrcodes: 列出码，可用 updated_since 做增量同步
PATCH /v1/qrcodes/{id}: 修改目标网址、名称、文件夹、状态或样式
GET /v1/qrcodes/{id}/svg: 获取 SVG 码图，支持 ETag 缓存
GET /v1/qrcodes/{id}/analytics: 单个码在一段日期内的扫码数据
GET /v1/analytics/summary: 一次调用汇总多个码，可按码、文件夹或日期分组
GET /v1/scans: 上次处理之后的新扫码事件
GET /v1/scans/export: 把扫码事件导出为 CSV 文件
GET /v1/usage: 本月用量与配额

可以直接运行的示例

每个文件都是完整的程序，填上令牌就能运行。

Shell: quickstart.sh — 建码、保存 SVG、修改目标网址、读取扫码数
Node.js: node-quickstart.mjs — 同样的流程，带重试和冲突处理，不需要安装任何包
Python: python-bulk-from-csv.py — 把一份 CSV 里的链接批量建成码，每个请求 100 个，每行输出一张 SVG
Google 表格: google-sheets.gs — 按表格里的行建码，并把短链接写回表格
交互式 API 文档
OpenAPI 3 规范
Postman 集合
给 AI 编程助手的规则文件

限制与价格

套餐: Business：每月 $29，或每年 $279
免费试用: 新客户的月付套餐可试用 14 天，需要绑定银行卡。
每月配额: 50,000 次成功请求，失败的请求不计入。
频率限制: 每个账号每分钟 120 次请求
调用方式: 服务器对服务器。浏览器直接调用会被 CORS 拦截。
图片格式: 只提供 SVG。需要 PNG 请在你自己的系统里转换。

查看 Business 价格

几个能帮你省事的细节

建码可以安全重试。 external_id 在一个账号内唯一。同一个编号加同一个目标网址，会返回已有的码（状态码 200）。
POST 永远不会改动已印刷的码。 同一个编号配不同的目标网址会返回 409。改址必须显式调用 PATCH，并且会经过和网站上一样的安全检查。
稳定的错误码。 每个错误都带机器可读的 code。英文提示是给人看的，以后可能调整。
按版本缓存码图。 image_version 只在码图变化时才变，它同时也是 SVG 接口的 ETag。修改目标网址不会改变它。
只读令牌。 给报表系统一个只能 GET 的令牌。即使泄露，也无法用它创建、修改或删除任何东西。

常见问题

API 有免费额度吗？

没有。API 属于 Business 套餐。新客户可以免费试用月付套餐 14 天；需要绑定银行卡，不取消的话到期后按每月 $29 续费。

能拿到 PNG 图片吗？

API 返回的是 SVG，放大到任何印刷尺寸都清晰，也可以直接放进 img 标签。需要 PNG 的话请在你自己的系统里转换，对接教程里有 Node、Python 和浏览器三种做法。

可以在网页里直接调用 API 吗？

不可以。跨域的浏览器请求会被拦截，这样令牌始终留在你的服务器上。请从你的后端调用 API，再把结果传给页面。

支持 webhook 吗？

不支持。取而代之的是 GET /v1/scans：它按顺序返回新的扫码事件。每 30 到 60 秒拉一次，并保存它返回的游标即可。没有新数据的响应不计入配额。

如果我取消订阅，码会怎样？

码会继续跳转。套餐到期后，API 和其他 Business 功能会停用。

二维码 API