QR Code API：建立和追蹤動態 QR Code

可以用它做什麼

每個訂單、商品或桌位一個碼按你自己的記錄建碼，每個碼都帶著你自己的編號。

一次幾千個每個請求最多建 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\" …>"
  }
}

編碼進 QR Code 的應該是 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 功能會停用。

QR Code API