用 REST API 從你自己的系統生成 QR Code：10 分鐘上手

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

要從你自己的系統生成 QR Code，只需向 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 集合和完整示例程式的連結。不想寫伺服器程式碼也能生成 QR Code，見 Google 表格以及 Make、n8n 和 Zapier 的教程。

常見問題

可以從瀏覽器呼叫 API 嗎？

不可以。瀏覽器直接呼叫 API 會把你的令牌暴露給每一個訪客。從你的伺服器呼叫，再把 SVG 或短連結傳給頁面。

令牌洩露了怎麼辦？

在「設定」裡撤銷它，再建立一個新的。令牌只能呼叫 QR Code API，不能修改你的密碼、帳單或網域；只讀令牌則不能建立、修改或刪除任何東西。

碼能用我自己的網域嗎？

能。Business 版可以連線一個自有短連結網域。建立碼時把它作為 short_domain 傳入，短連結就會使用你的網域，而不是共享網域。