API 参考

列出所有码

GET/api/v1/codes

工作区里的所有可编辑二维码和短链，按创建时间倒序，包括已归档的（看 "archived" 字段）。

参数

请求示例

curl https://qrglo.com/api/v1/codes?kind=qr \
  -H "Authorization: Bearer YOUR_KEY"

返回示例 · 状态码 200

{
  "data": [
    {
      "id": "k3v9x2",
      "name": "Menu",
      "kind": "qr",
      "type": "url",
      "short_url": "https://q.qrglo.com/ab3cd",
      "target_url": "https://example.com/menu",
      "active": true,
      "archived": false,
      "scans": 128,
      "tags": ["table-cards"],
      "domain": null,
      "created_at": "2026-10-01T09:30:00.000Z",
      "updated_at": "2026-10-20T14:02:11.000Z"
    }
  ]
}

可能的错误: unauthorized, pro_required, rate_limited

新建动态码

POST/api/v1/codes

新建一个可编辑的码，扫码后跳到 "url"。把返回的 "qr_payload" 交给任意二维码生成器，或传给 GET /qr，就能得到可打印的图案。

参数

请求示例

curl -X POST https://qrglo.com/api/v1/codes \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/menu","name":"Menu"}'

返回示例 · 状态码 201

{
  "id": "k3v9x2",
  "name": "Menu",
  "kind": "qr",
  "type": "url",
  "short_url": "https://q.qrglo.com/ab3cd",
  "target_url": "https://example.com/menu",
  "active": true,
  "archived": false,
  "scans": 128,
  "tags": ["table-cards"],
  "domain": null,
  "created_at": "2026-10-01T09:30:00.000Z",
  "updated_at": "2026-10-20T14:02:11.000Z",
  "qr_payload": "https://q.qrglo.com/ab3cd"
}

可能的错误: invalid_json, invalid, unsafe, limit, template_not_found, unauthorized, pro_required, rate_limited

查看一个码

GET/api/v1/codes/{id}

返回一个码，以及用来生成图案的 "qr_payload"。

参数

请求示例

curl https://qrglo.com/api/v1/codes/ID \
  -H "Authorization: Bearer YOUR_KEY"

返回示例 · 状态码 200

{
  "id": "k3v9x2",
  "name": "Menu",
  "kind": "qr",
  "type": "url",
  "short_url": "https://q.qrglo.com/ab3cd",
  "target_url": "https://example.com/menu",
  "active": true,
  "archived": false,
  "scans": 128,
  "tags": ["table-cards"],
  "domain": null,
  "created_at": "2026-10-01T09:30:00.000Z",
  "updated_at": "2026-10-20T14:02:11.000Z",
  "qr_payload": "https://q.qrglo.com/ab3cd"
}

可能的错误: not_found, unauthorized, pro_required, rate_limited

修改一个码

PATCH/api/v1/codes/{id}

修改已印刷的码跳转到哪里、重命名或暂停。只传要改的字段，印出去的图案不变。

参数

请求示例

curl -X PATCH https://qrglo.com/api/v1/codes/ID \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/menu-winter"}'

返回示例 · 状态码 200

{
  "id": "k3v9x2",
  "name": "Menu",
  "kind": "qr",
  "type": "url",
  "short_url": "https://q.qrglo.com/ab3cd",
  "target_url": "https://example.com/menu-winter",
  "active": true,
  "archived": false,
  "scans": 128,
  "tags": ["table-cards"],
  "domain": null,
  "created_at": "2026-10-01T09:30:00.000Z",
  "updated_at": "2026-10-20T14:02:11.000Z"
}

可能的错误: not_found, locked, invalid_json, not_a_link_code, invalid, unsafe, unauthorized, pro_required, rate_limited

归档一个码

DELETE/api/v1/codes/{id}

归档这个码：不再占用额度，统计数据保留，可以在后台恢复。

参数

请求示例

curl -X DELETE https://qrglo.com/api/v1/codes/ID \
  -H "Authorization: Bearer YOUR_KEY"

返回示例 · 状态码 200

{
  "id": "k3v9x2",
  "archived": true
}

可能的错误: not_found, unauthorized, pro_required, rate_limited

扫码统计

GET/api/v1/codes/{id}/stats

一个码的总数和按时间的扫码序列。去重访客按天计算，不使用 Cookie。

参数

请求示例

curl "https://qrglo.com/api/v1/codes/ID/stats?window=7d" \
  -H "Authorization: Bearer YOUR_KEY"

返回示例 · 状态码 200

{
  "id": "k3v9x2",
  "window": { "k": "7d", "from": "2026-10-26T00:00:00.000Z", "to": "2026-11-01T18:20:00.000Z", "bucket": "day" },
  "total": 42,
  "unique": 37,
  "series": [{ "label": "2026-10-26", "scans": 5 }, { "label": "2026-10-27", "scans": 8 }],
  "countries": [{ "k": "US", "n": 20 }, { "k": "DE", "n": 9 }],
  "devices": [{ "k": "mobile", "n": 39 }, { "k": "desktop", "n": 3 }],
  "os": [{ "k": "iOS", "n": 25 }, { "k": "Android", "n": 14 }],
  "browsers": [{ "k": "Safari", "n": 24 }],
  "languages": [{ "k": "en", "n": 30 }]
}

可能的错误: not_found, unauthorized, pro_required, rate_limited

生成二维码图片（SVG）

GET/api/v1/qr

把任意文字或链接画成静态二维码。配合 "qr_payload" 使用，就能打印可编辑的码。

参数

请求示例

curl "https://qrglo.com/api/v1/qr?data=https%3A%2F%2Fq.qrglo.com%2Fab3cd&size=1024" \
  -H "Authorization: Bearer YOUR_KEY" -o code.svg

返回示例 · 状态码 200

返回 image/svg+xml 图片。

可能的错误: data, template_not_found, unauthorized, pro_required, rate_limited

生成条形码图片（SVG）

GET/api/v1/barcode

生成零售、物流或二维条码。会校验校验位，不对时返回 400。

参数

请求示例

curl "https://qrglo.com/api/v1/barcode?kind=ean13&data=4006381333931" \
  -H "Authorization: Bearer YOUR_KEY" -o barcode.svg

返回示例 · 状态码 200

返回 image/svg+xml 图片。

可能的错误: kind, unauthorized, pro_required, rate_limited

列出样式模板

GET/api/v1/templates

模板在后台「开发者」页面从某个码的外观保存。新建或生成码时把 id 作为 "template" 传入。

请求示例

curl https://qrglo.com/api/v1/templates \
  -H "Authorization: Bearer YOUR_KEY"

返回示例 · 状态码 200

{
  "data": [
    { "id": "tpl_8f2k", "name": "Brand", "style": { "fg": "#111827", "bg": "#ffffff", "dots": "rounded" }, "created_at": "2026-09-12T08:00:00.000Z" }
  ]
}

可能的错误: unauthorized, pro_required, rate_limited

Webhook

在后台「开发者」页面添加一个 https 地址，选择要订阅的事件。我们会 POST 一个 JSON，5 秒超时；连续失败 5 次后自动暂停并通知你。

事件

• scan有人扫了码，扫码后几秒内发送。
• code.created新建了一个码（后台或 API）。
• code.updated码的链接、名称或状态有变化。
• code.archived码被归档。

请求体示例

{
  "id": "6f1c2d4e-0b7a-4c55-9a1e-2f3b4c5d6e7f",
  "event": "scan",
  "created": "2026-11-01T18:20:04.512Z",
  "data": {
    "code": { "id": "k3v9x2", "name": "Menu", "short": "ab3cd" },
    "scans": 129,
    "country": "US",
    "city": "Austin",
    "device": "mobile",
    "os": "iOS",
    "browser": "Safari",
    "lang": "en",
    "referrer": null,
    "destination": "https://example.com/menu"
  }
}

校验签名

每个请求都带 QRGlo-Signature: t=<秒级时间戳>,v1=<签名>。签名是用 Webhook 密钥对 "<t>.<原始请求体>" 做的 HMAC-SHA256（十六进制）。请比对签名，并拒绝 5 分钟以前的请求。

import crypto from 'node:crypto';

// header: the QRGlo-Signature request header, e.g. "t=1762021204,v1=5f2b…"
// body:   the raw request body, exactly as received
export function verify(header, body, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${body}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const got = Buffer.from(parts.v1 ?? '');
  return fresh && got.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), got);
}

给工具和 AI 用的格式

同一份接口说明也提供机器可读的版本：

• /openapi.json OpenAPI 3.1
• /llms.txt