QRFLOW.codes
官方建立QR碼、重新指向已印製的動態碼、在您自己的網域上命名連結,並讀取掃描分析。
你可以用 QRFLOW Codes MCP 做什麼?
- 建立動態 QR code — 請助理建立帶有
destination_data的urlcode,並回傳其short_url以供列印。 - 重新指定已列印 code 的目的地 — 變更現有動態 code 的重新導向目的地,無須重新列印,因為圖案中保存的是
short_url。 - 暫停或讓 code 到期 — 設定
paused: true或到期日,而非刪除,讓已列印的連結安全地停止重新導向。 - 查看掃描分析 — 擷取 code 的累計
Scans總數,或依日期、國家/地區、裝置分類的明細。 - 使用自有網域為連結命名 — 設定像
menu這樣的slug,並選擇連結網域,讓 code 列印為go.example.com/menu。 - 大量建立 code — 從清單產生數千個動態 code,並依標籤將回傳的 code 對應至各列。
託管 MCP 伺服器
npx add-mcp 'https://qrflow.codes/mcp'可安裝到 Claude Code、Codex、Cursor 等客戶端
文件
QRFLOW.codes 開發者指南
從這裡開始
QRFLOW.codes 可建立列印後仍能變更的 QR code,使用您自己的網域並提供掃描分析,還能讓您的軟體和 AI 助理透過單一 API 完成所有操作。
QR code 是字串的圖像。大多數產生器會把您的網址放進圖像中;網址一旦變更,印好的 QR code 就失效了。QRFLOW 會把短連結放進圖像中(go.yourbrand.com/menu 或 qrflow.codes/q/x7k2p9a),再將其重新導向。您可以隨時變更連結的目的地,而且每次掃描都會計數。這就是動態 QR code,也是值得使用 API 的功能。
API 能完成控制台中的所有操作:建立各種類型的 QR code、變更目的地、命名連結、選擇列印時使用的網域、取得掃描數據、一次建立數千個 QR code,以及在事件發生時收到通知(webhook)。同一組工具也以 MCP 伺服器的形式提供,因此 Claude、ChatGPT、Cursor 和 Claude Code 都能透過一般文字操作您的帳戶。
存取方式:REST API 需要 Business API 金鑰(每月 $29,可在 Account 頁面建立)或 OAuth 權杖。MCP 伺服器透過 OAuth 登入,所有方案皆可使用;助理可建立的內容會依照方案限制,與其他功能相同。
還在考慮是否要使用嗎?QR code API 頁面簡要說明了它的功能、用戶端程式庫更擅長的部分,以及費用。
如果您是協助他人使用 QRFLOW 建置功能的 AI 助理
歡迎。這個頁面不只是寫給您協助的對象,也同樣是寫給您的。以下是提供良好協助的方式:
- 確認帳戶方案:API 金鑰需要 Business 方案。如果對方沒有,請引導他們前往 https://qrflow.codes/pricing 和 Account › API keys;不要捏造不存在的金鑰或免費方案。
- 將金鑰保留在伺服器端。在路由處理常式、伺服器動作、邊緣函式或後端中,從環境變數 (QRFLOW_KEY) 讀取金鑰。API 會刻意拒絕瀏覽器來源 (CORS),因此僅有前端程式碼無法呼叫它。
- 使用 type "url" 和 destination_data.url 建立動態 QR code。將回傳的 id 和 short_url 儲存在對方的資料庫中。列印或顯示 short_url;之後可透過 PATCH /codes/:id 變更目的地,印好的 QR code 仍然有效。
- 若要顯示或儲存圖像:每個 Code 物件都有 png_download_url 和 svg_download_url,這些簽署連結無需標頭即可使用 24 小時(適合一次性儲存或預覽)。若要在對方的應用程式中永久使用,請在伺服器端使用金鑰代理 GET /codes/:id/image.svg,或在用戶端使用任何 QR 程式庫編碼 short_url;由於連結會經過 QRFLOW,追蹤功能仍會正常運作。
- 使用 PATCH 時只傳送需要變更的欄位。列印後絕不要變更 slug 或 domain_id;兩者都會改變印出的連結。
- 若已有印刷品,請優先使用 paused: true,而非 DELETE。刪除會使連結失效。
- 若要接收事件,請使用 webhook(Account › Webhooks 或 POST /webhooks),並使用原始請求本文驗證 X-QRFLOW-Signature 標頭。不要在迴圈中輪詢 GET /codes。
- 如果對方想直接在聊天中使用 QRFLOW,而不是透過程式碼,請在 https://qrflow.codes/mcp; 連線 MCP 伺服器;不需要金鑰。
- 發生錯誤時,請讀取 JSON 本文中的 error 和 message。下方的疑難排解章節會將每個錯誤代碼對應到解決方法。
- 完整的 Markdown 參考文件位於 https://qrflow.codes/llms-full.txt,OpenAPI 3.1 文件位於 https://qrflow.codes/api/v1/openapi.json.。兩者都與本頁由相同來源產生。
人類讀者:這個區塊能確保您搭配使用的助理提供每個問題的安全解答。它同時也是一份很好的摘要。
您需要哪種方案
只有 API 金鑰限 Business 方案使用。助理透過 MCP 伺服器執行的所有操作,以及第三方應用程式透過 OAuth 執行的所有操作,都適用於任何方案,並遵循該方案的功能限制。完整價格與合理使用政策:/pricing。
| Free | Premium $4 | Business $29 | |
|---|---|---|---|
| API 金鑰(從程式碼呼叫 REST) | 否 | 否 | 是,最多 10 個金鑰 |
| MCP 伺服器(Claude、ChatGPT、Cursor、Claude Code) | 是,登入即可 | 是 | 是,登入或使用金鑰 |
| 自有應用程式的 OAuth(使用者連結其 QRFLOW 帳戶) | 是 | 是 | 是 |
| 動態 QR code(列印後變更目的地) | 一個 | 每個 QR code | 每個 QR code |
| 自有連結網域 | 否 | 1 個網域 | 5 個網域,每個 QR code 可選擇 |
| 連結名稱 (go.brand.com/menu) | 否 | 是 | 是 |
| 掃描分析 | 否 | 是 | 是 |
| Webhook | 否 | 否 | 是,最多 10 個 |
| 批次建立 | 否 | 每月 500 個,每次請求 500 個 | 每月 10,000 個,每次請求 2,000 個 |
| 已儲存的 QR code(合理使用) | 少量 | 1,000 個 | 25,000 個 |
| 團隊席位 | 1 | 1 | 5 |
| 價格 | $0 | $4/月 | $29/月 |
十二個詞就能說明一切
概念
讀過一次,以下所有端點就都能理解。
Static code
內容就在圖像中。Wi-Fi、聯絡人卡片 (vCard) 和純文字 QR code 永遠是靜態的;Free 方案中的所有 QR code 也都是靜態的。靜態 QR code 不需要伺服器、永不過期,也無法變更或計數。
Dynamic code
圖像中放的是由 QRFLOW 重新導向的短連結。Premium 和 Business 方案中的 url、phone、email、sms 和 location QR code 都是動態的。您可以重新指定目的地、暫停、設定到期時間、重新命名和計數,而不必更動印刷品。
short_url
動態 QR code 中編碼的確切字串,也是要列印的內容。連結網域尚未連線時為 https://qrflow.codes/q/<short_code>,連線後則為 https://<your domain>/<slug or short_code>.。每個 Code 物件都包含此字串。
short_code
七個隨機字元,每個 QR code 都不重複,在建立時指派且永不變更。當 QR code 沒有連結名稱時,會使用此路徑作為備用路徑。
slug (link name)
您自有網域上的易讀路徑:go.example.com/menu。長度為 3 到 40 個小寫字母、數字和連字號,在您的帳戶中必須唯一,且只能搭配已連線的網域使用。請在列印前設定:變更它會改變印出的連結。
Link domain
您擁有的主機名稱 (go.example.com),透過 CNAME 指向 QRFLOW,並在 Account 頁面完成驗證。Premium 可使用一個網域;Business 可使用五個,並可透過 domain_id 為每個 QR code 選擇網域。最早啟用的網域會作為預設網域。
Kind, type and subtype
type 是編碼類型:url、text、wifi、vcard、email、phone、sms、location。kind 是更易懂的名稱,代表使用者想要的用途 (instagram、googlereview、whatsapp、pdf、menu、appstore,...)。大多數 kind 都是設定 destination_data.subtype 的 url QR code。GET /catalog 會列出所有 kind 及其欄位;Code 上的 kind 會告訴您它是哪一種。
destination_data
該類型的欄位,值皆為字串:網站使用 { url },Wi-Fi 使用 { ssid, password, encryption },Google 評論使用 { placeId },Instagram 使用 { handle }。動態 QR code 可隨時替換這些欄位。
Scans
每次重新導向都會從請求本身記錄裝置類型、國家、城市、來源網址、瀏覽器、作業系統和語言,並使用每日單向雜湊計算不重複訪客數。不會設定 Cookie,也不會儲存 IP 位址。Code 上的 scans 是累計總數;GET /codes/:id/scans 可查看詳細分類。
Source
每個 QR code 都會記錄其建立來源:dashboard、api:<key name>、mcp、canva、app:<connected app>(例如 app:Google Sheets)或 bulk;若來自批次請求,則會加上 bulk: 前綴。此資訊會顯示在控制台和 webhook 負載中,方便您區分整合程式建立的 QR code 與手動建立的 QR code。
Workspace
Business 帳戶擁有者最多可邀請四位團隊成員。金鑰和 webhook 屬於擁有者的帳戶;工作區中任何人建立的 QR code 都會對整個團隊顯示。
五分鐘
快速開始
取得金鑰
- 使用 Business 方案,開啟 Account › API keys。
- 以用途命名(「Shop backend」、「Reporting」),並選擇其範圍。範圍之後無法變更;若需要不同範圍,請建立新金鑰。
- 僅複製一次。金鑰格式如下:
qrf_live_…。將它放入名為QRFLOW_KEY的環境變數中。 - 每次請求都將它作為
Authorization: Bearer $QRFLOW_KEY傳送。驗證方式就是這麼簡單。
金鑰僅供伺服器使用。絕不要將金鑰放在網頁、行動應用程式或共用試算表中;若金鑰外洩,請撤銷並重新簽發。
以下以 curl、TypeScript 和 Python 示範相同的五個步驟。每個範例都會建立動態 QR code、下載其圖像、變更目的地,並讀取掃描數據。
export QRFLOW_KEY=qrf_live_... # from Account › API keys
# 1. Who am I, what can this key do?
curl https://qrflow.codes/api/v1/me -H "Authorization: Bearer $QRFLOW_KEY"
# 2. Make a dynamic code. Print what comes back as short_url.
curl -X POST https://qrflow.codes/api/v1/codes \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "type": "url", "destination_data": { "url": "https://example.com/menu" }, "label": "Table tents" }'
# 3. The print-ready image (SVG, with your colors and frame).
curl "https://qrflow.codes/api/v1/codes/$CODE_ID/image.svg?size=1024" \
-H "Authorization: Bearer $QRFLOW_KEY" -o menu.svg
# 4. Fall menu. The printed code keeps working.
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "destination_data": { "url": "https://example.com/menu-fall" } }'
# 5. How did it do?
curl "https://qrflow.codes/api/v1/codes/$CODE_ID/scans?group=day" -H "Authorization: Bearer $QRFLOW_KEY"
TypeScript(Node 18+、Bun、Deno、Workers)
// npm install qrflow (zero dependencies; ESM + CommonJS; full types)
import { QRFlow, QRFlowError } from "qrflow";
const qr = new QRFlow(process.env.QRFLOW_KEY!);
const { code } = await qr.createCode({
type: "url",
destination_data: { url: "https://example.com/menu" },
label: "Table tents",
});
console.log(code.id, code.short_url); // save both; print short_url
await qr.updateCode(code.id, { destination_data: { url: "https://example.com/menu-fall" } });
const stats = await qr.scans(code.id, { group: "day" });
console.log(stats.total, stats.rows); // [{ key: "2026-09-21", scans: 18 }, ...]
try {
await qr.updateCode(code.id, { slug: "menu" });
} catch (e) {
if (e instanceof QRFlowError) console.log(e.status, e.code, e.message); // 400 no_domain: connect a domain first
}
# Download https://qrflow.codes/sdk/qrflow.py next to your code.
import os
from qrflow import QRFlow, QRFlowError
qr = QRFlow(os.environ["QRFLOW_KEY"])
code = qr.create_code(type="url", destination_data={"url": "https://example.com/menu"}, label="Table tents")["code"]
print(code["id"], code["short_url"]) # save both; print short_url
qr.update_code(code["id"], destination_data={"url": "https://example.com/menu-fall"})
stats = qr.scans(code["id"], group="day")
print(stats["total"], stats["rows"])
try:
qr.update_code(code["id"], slug="menu")
except QRFlowError as e:
print(e.status, e.code, e) # 400 no_domain: connect a domain first
驗證
API 金鑰(Business)
每個帳戶最多 10 個,每個金鑰每分鐘可發出 600 個請求,金鑰以雜湊形式儲存,且只會顯示一次。金鑰會包含建立時指定的範圍:
| 範圍 | 允許的操作 |
|---|---|
| profile | GET /me:方案、功能、限制。每個金鑰都包含此範圍。 |
| codes:read | 列出和讀取 QR code、下載圖像。 |
| codes:write | 建立、變更、設為動態、刪除、批次建立。 |
| analytics:read | GET /codes/:id/scans。 |
| domains:read | GET /domains(合理使用 domain_id 所需)。 |
| codes:read / codes:write | 也適用於 GS1 產品:/products 端點共用 QR code 範圍,因此管理 QR code 的金鑰也能管理包裝 QR code。 |
| webhooks:manage | 列出、建立、測試和刪除 webhook。 |
OAuth 2.0(任何方案,適用於應用程式和助理)
如果 QR code 應屬於「您的使用者」帳戶,而非您的帳戶,或聊天助理是用戶端,請使用 OAuth。用戶端需自行註冊;公開用戶端必須使用 PKCE S256;權杖可透過 resource= 綁定至 MCP 伺服器。OAuth 操作指南會逐步說明。
| 端點 | URL | 備註 |
|---|---|---|
| 授權 | https://qrflow.codes/oauth/authorize | 將使用者導向此處;他們登入後按下 Allow。 |
| 權杖 | https://qrflow.codes/api/oauth/token | 支援 authorization_code 和 refresh_token 授權類型。存取權杖有效期為 1 小時,重新整理權杖有效期為 90 天。 |
| 撤銷 | https://qrflow.codes/api/oauth/revoke | RFC 7009。使用者也可以在 Account › Connected apps 中解除連線。 |
| 註冊用戶端 | https://qrflow.codes/api/oauth/register | RFC 7591 動態註冊,不需要帳戶。公開用戶端會取得 dyn_ client_id,且必須使用 PKCE S256。 |
| 探索 | https://qrflow.codes/.well-known/oauth-authorization-server | RFC 8414。MCP 資源文件位於 /.well-known/oauth-protected-resource。 |
存取權杖有效期為 1 小時,重新整理權杖有效期為 90 天。使用者可在 Account › Connected apps 查看已連線的應用程式,並隨時解除連線。為 https://qrflow.codes/mcp 簽發的權杖會在 /api/v1 上遭到拒絕,反之亦然。
大家實際會詢問的內容
建置指南
每份指南都完整且直接取自可運作的程式碼。選擇符合您技術堆疊的指南;流程一律相同:在伺服器端使用金鑰呼叫 API,儲存 id 和 short_url,並顯示圖像。
- Next.js
- 不透過代理顯示 QR code
- Express 或任何 Node 伺服器
- Cloudflare Workers、Vercel Edge、Deno Deploy、Supabase Edge Functions
- Python
- 為每筆訂單、每張桌子、每項產品、每張票券或每場活動建立一個 QR code
- 變更已列印 QR code 的目的地
- 在自有網域上列印 QR code
- 在自有管理介面中顯示掃描圖表
- 在 Next.js 中接收 webhook 並驗證
- 在 Python 中接收 webhook
- 從 CSV 建立數千個 QR code
- 讓使用者連結自己的 QRFLOW 帳戶 (OAuth)
- Zapier、Make、n8n
Next.js:建立 QR code 的路由和顯示 QR code 的路由
適用情境:您有一個 Next.js 應用程式(App Router),並想要一個可建立 QR code 的按鈕,以及一個顯示 QR code 的頁面。
- 將金鑰放在 .env.local 中,名稱為 QRFLOW_KEY。絕不要加上 NEXT_PUBLIC_ 前綴。
- 新增一個 POST 路由處理常式來建立 QR code,並回傳 id 和 short_url。
- 新增一個 GET 路由來代理圖像,讓瀏覽器永遠看不到金鑰。
- 將 id 和 short_url 儲存在您自己的記錄中(訂單、桌子、產品、活動)。
import { NextResponse } from "next/server";
export async function POST(req: Request) {
const { url, label } = await req.json();
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST",
headers: { Authorization: \`Bearer ${process.env.QRFLOW_KEY}\`, "Content-Type": "application/json" },
body: JSON.stringify({ type: "url", destination_data: { url }, label }),
});
const data = await r.json();
if (!r.ok) return NextResponse.json(data, { status: r.status }); // { error, message }
return NextResponse.json({ id: data.code.id, short_url: data.code.short_url });
}
// Proxies the SVG so the key stays on the server. Check that the signed-in
// user owns this id before you serve it, or anyone with an id can fetch it.
export async function GET(_: Request, { params }: { params: Promise<{ id: string }> }) {
const { id } = await params;
const r = await fetch(\`https://qrflow.codes/api/v1/codes/${id}/image.svg?size=1024\`, {
headers: { Authorization: \`Bearer ${process.env.QRFLOW_KEY}\` },
});
return new Response(r.body, {
status: r.status,
headers: { "Content-Type": "image/svg+xml", "Cache-Control": "private, max-age=3600" },
});
}
<img src={\`/api/qr/${code.id}/image\`} alt={\`QR code for ${code.label}\`} width={256} height={256} />
<a href={code.short_url}>{code.short_url}</a>
- Server Actions 的運作方式相同:在 action 內呼叫 fetch,並將金鑰放在其中。
- 對於 Pages Router,將相同的程式碼放在 pages/api/qr.ts,並使用 req/res。
不透過代理顯示 QR:自行呈現 short_url
適用情況:您想立即在瀏覽器中顯示圖片,而且不需要 QRFLOW 的外框或標誌。
任何 QR 程式庫都可以,因為這段程式碼就是短連結
import QRCode from "qrcode"; // npm i qrcode
// short_url came back from POST /codes. Encode it as-is.
const dataUrl = await QRCode.toDataURL(code.short_url, { width: 512, margin: 2 });
// <img src={dataUrl} /> scans go through QRFLOW, so analytics and re-pointing still work.
- 這是預覽最快的方式。若要列印,請下載 /codes/:id/image.svg:它包含已儲存的顏色、外框、說明文字和標誌,而且是向量圖。
- 如果之後變更 slug 或 domain_id,short_url 也會變更;請重新呈現。
Express 或任何 Node 伺服器
適用情況:一般的 Node 後端。
import express from "express";
const app = express();
app.use(express.json());
const H = { Authorization: \`Bearer ${process.env.QRFLOW_KEY}\`, "Content-Type": "application/json" };
app.post("/qr", async (req, res) => {
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST", headers: H,
body: JSON.stringify({ type: "url", destination_data: { url: req.body.url }, label: req.body.label }),
});
res.status(r.status).json(await r.json());
});
app.get("/qr/:id.svg", async (req, res) => {
const r = await fetch(\`https://qrflow.codes/api/v1/codes/${req.params.id}/image.svg\`, { headers: H });
res.status(r.status).type("image/svg+xml").send(await r.text());
});
app.listen(3000);
Cloudflare Workers、Vercel Edge、Deno Deploy、Supabase Edge Functions
適用情況:僅支援 fetch、沒有 Node 內建模組的執行環境。
export default {
async fetch(req: Request, env: { QRFLOW_KEY: string }) {
const { url, label } = await req.json();
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST",
headers: { Authorization: \`Bearer ${env.QRFLOW_KEY}\`, "Content-Type": "application/json" },
body: JSON.stringify({ type: "url", destination_data: { url }, label }),
});
return new Response(r.body, { status: r.status, headers: { "Content-Type": "application/json" } });
},
};
Deno.serve(async (req) => {
const { url, label } = await req.json();
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST",
headers: { Authorization: \`Bearer ${Deno.env.get("QRFLOW_KEY")}\`, "Content-Type": "application/json" },
body: JSON.stringify({ type: "url", destination_data: { url }, label }),
});
return new Response(await r.text(), { status: r.status, headers: { "Content-Type": "application/json" } });
});
// supabase secrets set QRFLOW_KEY=qrf_live_...
- npm 套件
qrflow\只使用 fetch 和 WebCrypto,因此無須修改即可在上述所有環境中執行。
Python:FastAPI、Flask、Django、指令碼
適用情況:您的後端使用 Python。
import os
from fastapi import FastAPI, HTTPException, Response
from qrflow import QRFlow, QRFlowError # https://qrflow.codes/sdk/qrflow.py
app = FastAPI()
qr = QRFlow(os.environ["QRFLOW_KEY"])
@app.post("/qr")
def make_qr(url: str, label: str | None = None):
try:
code = qr.create_code(type="url", destination_data={"url": url}, label=label)["code"]
except QRFlowError as e:
raise HTTPException(e.status, {"error": e.code, "message": str(e)})
return {"id": code["id"], "short_url": code["short_url"]}
@app.get("/qr/{code_id}.svg")
def qr_image(code_id: str):
import urllib.request
req = urllib.request.Request(qr.image_url(code_id), headers={"Authorization": f"Bearer {os.environ['QRFLOW_KEY']}"})
with urllib.request.urlopen(req) as r:
return Response(r.read(), media_type="image/svg+xml")
每筆訂單、桌位、產品、票券或活動各建立一個 QR code
適用情況:您其中一個資料表的每一列都需要自己的代碼,並且要自動建立。
- 在資料表中新增兩個欄位:qrflow_code_id (uuid) 和 qr_short_url (text)。
- 建立資料列時,使用該資料列的公開 URL 和能識別該資料列的標籤(「訂單 10432」、「桌位 7」)呼叫 POST /codes。儲存 id 和 short_url。
- 資料列的頁面位置變更時(新網域、新路徑),PATCH destination_data。已列印的代碼仍可正常使用。
- 資料列停用時,如果已列印任何代碼,請 PATCH { paused: true };只有在完全沒有列印時才使用 DELETE。
- 需要一次建立數千個(例如為 300 間餐廳的每張桌子建立一個菜單)?請分批使用 POST /codes/bulk,並依標籤或順序將傳回的代碼對應回資料列。
const { code } = await qr.createCode({
type: "url",
destination_data: { url: \`https://example.com/orders/${order.id}\` },
label: \`Order ${order.number}\`,
});
await db.orders.update(order.id, { qrflow_code_id: code.id, qr_short_url: code.short_url });
- Business 方案的合理使用上限為 25,000 個已儲存代碼;API 的上限是其兩倍。如果您需要永久為每張收據建立一個代碼,請先聯絡我們:hello@qrflow.codes。
變更已列印代碼的目的地
適用情況:活動已結束、頁面已移動、PDF 已替換,或季節已更迭。
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "destination_data": { "url": "https://example.com/spring" } }'
暫停代碼,或為它設定結束日期
# Scans show a "paused" page instead of redirecting
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID -H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" -d '{ "paused": true }'
# Stops working after the date; null clears it
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID -H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" -d '{ "expires_at": "2026-12-31T23:59:59Z" }'
- 只有動態代碼可以重新指定目的地;靜態代碼一律會回應 400 not_dynamic。Wi-Fi、vCard 和純文字代碼的內容直接包含在圖樣中,因此永遠無法設為動態;POST /codes/:id/dynamic 會以 400 not_dynamic_capable 拒絕這些代碼。對於 url、phone、email、sms 和 location 代碼,Free 方案會將第一個設為動態,其餘設為靜態;付費方案則全部設為動態。只要帳戶仍有可用額度,POST /codes/:id/dynamic 就能將靜態代碼轉為動態。之後請重新呈現並重新列印,因為圖像會改變。
- 掃描器會在下次掃描時看到新的目的地。不必等待快取更新。
在自己的網域上列印代碼
適用情況:您想讓代碼使用 go.example.com/menu,而不是 qrflow.codes/q/x7k2p9a。
- 在 Account 頁面的 Your own link domain 下方,新增 go.example.com,並在 DNS 供應商處建立畫面顯示的 CNAME。通常幾分鐘內就會完成驗證。
- 從此之後,每個新動態代碼的 short_url 都會使用該網域。現有代碼也會切換:其圖像編碼的是 qrflow.codes/q/...,該網址仍會繼續重新導向,因此已列印的代碼不會失效。
- 使用 slug 為代碼設定易讀名稱:PATCH { "slug": "menu" } 會建立 go.example.com/menu。請在列印前完成。
- Business 方案可使用多個網域;GET /domains 會列出網域及其 ids。請在 POST 或 PATCH 中傳入 domain_id,為個別代碼選擇網域。
為連結命名並選擇網域
curl https://qrflow.codes/api/v1/domains -H "Authorization: Bearer $QRFLOW_KEY"
# { "default_base": "https://go.example.com", "domains": [ { "id": "…", "host": "go.example.com", "is_default": true, … }, { "id": "…", "host": "qr.example.fr", … } ] }
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID -H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "slug": "menu", "domain_id": "<id of qr.example.fr>" }'
# short_url is now https://qr.example.fr/menu
在自己的管理介面中顯示掃描圖表
適用情況:您想在自己的數據旁邊查看每日、各國或各裝置的掃描次數。
const stats = await qr.scans(code.id, { from: "2026-09-01", to: "2026-09-30", group: "day" });
// stats.total -> 412
// stats.rows -> [{ key: "2026-09-01", scans: 18 }, { key: "2026-09-02", scans: 25 }, ...]
// Feed rows straight into Recharts, Chart.js, or a <table>.
const byCountry = await qr.scans(code.id, { group: "country" }); // [{ key: "US", scans: 300 }, { key: "MX", scans: 41 }]
const byDevice = await qr.scans(code.id, { group: "device" }); // mobile, desktop, tablet
- 單次請求最多涵蓋 92 天;較長的範圍請分次查詢。日期採用 UTC。
- 若要取得即時數據而不必輪詢,請為掃描事件訂閱 webhook:每隔幾分鐘就會以批次方式收到每次掃描及其詳細資料。
在 Next.js 中接收並驗證 webhooks
適用情況:您想在自己的資料庫中近乎即時地得知代碼何時被掃描或變更。
- 在 Account › Webhooks 建立 webhook,或使用 POST /webhooks。將密鑰 (whsec_...) 複製到 QRFLOW_WEBHOOK_SECRET;密鑰只會顯示一次。
- 解析前先將原始本文讀取為文字;簽章涵蓋的是完全相同的位元組。
- 驗證後,再依事件類型處理。請迅速回應 2xx;耗時工作請在回應後處理,或放入佇列。
- 按下 webhook 上的 Test,接收已簽署的 ping 並確認設定正確。
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(raw: string, header: string, secret: string): boolean {
const t = /t=(\d+)/.exec(header)?.[1], v1 = /v1=([a-f0-9]+)/.exec(header)?.[1];
if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(\`${t}.${raw}\`).digest("hex");
return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
export async function POST(req: Request) {
const raw = await req.text();
if (!verify(raw, req.headers.get("x-qrflow-signature") ?? "", process.env.QRFLOW_WEBHOOK_SECRET!)) {
return new Response("bad signature", { status: 401 });
}
const evt = JSON.parse(raw) as { id: string; event: string; created_at: string; data: any };
// evt.id is stable across retries: store it and skip duplicates.
switch (evt.event) {
case "scan": // evt.data.scans[]: code_id, label, slug, scanned_at, device, country, city, referrer, browser, os, language
break;
case "code.created": // evt.data.code, evt.data.source
case "code.updated": // evt.data.code, evt.data.changed[]
case "code.deleted": // evt.data.code { id, label, short_code, slug }
break;
case "ping": // the Test button
break;
}
return new Response(null, { status: 204 });
}
- 在本機開發時,使用通道公開開發伺服器(cloudflared tunnel --url http://localhost:3000, 或 ngrok),並在開發期間將該 https URL 用於 webhook。
- npm 套件會替您處理:
import { parseWebhook } from "qrflow"\會在一次呼叫中完成驗證和解析(使用 WebCrypto,因此也能在 Workers 和 Deno 中執行)。Python 用戶端內建 verify_webhook。
在 Python 中接收 webhooks
適用情況:使用 Flask、FastAPI 或 Django 接收相同事件。
import os, json
from flask import Flask, request, abort
from qrflow import verify_webhook # https://qrflow.codes/sdk/qrflow.py
app = Flask(__name__)
@app.post("/qrflow")
def hook():
raw = request.get_data() # bytes, before any parsing
if not verify_webhook(raw, request.headers.get("X-QRFLOW-Signature", ""), os.environ["QRFLOW_WEBHOOK_SECRET"]):
abort(401)
evt = json.loads(raw)
if evt["event"] == "scan":
for s in evt["data"]["scans"]:
print(s["code_id"], s["scanned_at"], s["country"], s["device"])
return "", 204
從 CSV 建立數千個代碼
適用情況:每個 SKU、座位、資產標籤或郵寄品各建立一個代碼。
import { parse } from "csv-parse/sync";
import { readFileSync } from "node:fs";
const rows = parse(readFileSync("skus.csv"), { columns: true }) as Array<{ sku: string; url: string }>;
const out: Array<{ sku: string; id: string; short_url: string }> = [];
for (let i = 0; i < rows.length; i += 2000) { // Business: 2,000 per request
const chunk = rows.slice(i, i + 2000);
const { codes, rejected, remaining_this_month } = await qr.bulkCreate(
chunk.map((r) => ({ destination: r.url, label: r.sku })),
);
codes.forEach((c, j) => out.push({ sku: chunk[j].sku, id: c.id, short_url: c.short_url }));
if (rejected.length) console.warn(rejected); // rows that were not web addresses
console.log(remaining_this_month, "left this month");
}
- Bulk 只會建立動態 url 代碼,而且所有代碼使用相同顏色。傳回的代碼會依照您提交的順序排列,但會略過遭拒的資料列;若不確定,請依標籤比對。
- 每次 bulk 請求只會觸發一個 code.created 事件,其中包含 codes[],而不是每個代碼各觸發一個事件。
讓使用者連結自己的 QRFLOW 帳戶 (OAuth)
適用情況:您正在為其他人打造產品,並希望代碼建立在他們自己的 QRFLOW 帳戶中,而不是您的帳戶。
- 註冊一次用戶端:使用 client_name 和 redirect_uris 呼叫 POST https://qrflow.codes/api/oauth/register。您會取得 client_id(機密用戶端還會取得 client_secret)。
- 將使用者導向 /oauth/authorize,並附上 response_type=code、client_id、redirect_uri、scope、state 和 PKCE (code_challenge、code_challenge_method=S256)。
- 在 /api/oauth/token 交換授權碼。儲存 refresh token;access token 的有效期限為一小時。
- 使用 Authorization: Bearer <access_token> 呼叫 /api/v1。所有功能都與使用金鑰時完全相同,並依照使用者的方案執行。
curl -X POST https://qrflow.codes/api/oauth/register -H "Content-Type: application/json" \
-d '{ "client_name": "Acme Menus", "redirect_uris": ["https://app.example.com/oauth/qrflow"], "token_endpoint_auth_method": "none" }'
# { "client_id": "dyn_…", "redirect_uris": [...], "grant_types": ["authorization_code","refresh_token"], … }
https://qrflow.codes/oauth/authorize?response_type=code&client_id=dyn_…&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fqrflow
&scope=profile%20codes%3Aread%20codes%3Awrite%20analytics%3Aread&state=…&code_challenge=…&code_challenge_method=S256
- Scopes 與 API 金鑰的六種 scope 相同。只要求您需要的最低權限;同意畫面會列出這些權限。
- 如果您的應用程式是聊天助理或代理,請在 authorize 請求中加入 resource=https://qrflow.codes/mcp,並改為與 MCP 伺服器通訊;權杖會綁定至該伺服器。
Zapier、Make、n8n:完全不需要寫程式
適用情況:您想將掃描或新代碼傳送到試算表、Slack 頻道或 CRM。
- 建立 catch-hook 觸發程序(Zapier:Webhooks by Zapier › Catch Hook;Make:Custom webhook;n8n:Webhook 節點),並複製其 https URL。
- 在 Account › Webhooks 新增該 URL 並選擇事件。按下 Test;工具中會顯示 ping,並提供其 payload 格式。
- 將 data.scans[](掃描事件)或 data.code(code.*)對應到試算表、訊息或記錄。
- 若要從這些工具建立代碼,請使用其 HTTP 模組,透過 Authorization 標頭呼叫 POST /codes。請將金鑰保存在工具的憑證儲存區。
- Zapier 現在提供 QRFLOW.codes 應用程式:其 Create QR Code、Update QR Code 和 Find 步驟,以及即時 New Scan 觸發程序,都不需要設定 webhook 或 API 金鑰。請參閱 QRFLOW with Zapier。以下步驟適用於 Make、n8n 和其他工具。
- 這些工具無法驗證簽章。它們提供的 URL 無法猜測,這就是您可用的保護措施;請勿將 URL 公開。
- 如果清單已經存放在 Google Sheets,您可能完全不需要 webhook:QRFLOW for Google Sheets 外掛程式可在 Premium 方案中為每一列建立代碼,並將短連結和掃描次數寫回試算表,無須 API 金鑰。請參閱 Google Sheets 外掛程式。
氛圍式編碼
可直接貼上的提示詞
只要事先告知規則,程式設計助理就能建置正確的功能。這些提示詞已包含相關規則。貼上一段、填入方括號中的內容,助理就會先閱讀 Markdown 參考文件,再開始撰寫程式碼。
在我的應用程式中加入 QR code
Claude、ChatGPT、Cursor、Codex、Windsurf、Copilot Chat:貼到聊天中
Add QR codes to this project using the QRFLOW.codes API.
Read https://qrflow.codes/llms-full.txt before writing code; it is the complete reference.
Rules:
- The API key is in the environment variable QRFLOW_KEY. It must only be used server-side (route handler, server action, edge function). Never expose it to the browser.
- Create dynamic codes: POST https://qrflow.codes/api/v1/codes with { "type": "url", "destination_data": { "url": ... }, "label": ... }.
- Save the returned code.id and code.short_url on my record. short_url is what gets printed or displayed.
- Show the image by proxying GET /codes/:id/image.svg through my server, or by encoding short_url with a QR library on the client.
- Handle errors from the JSON body: { "error", "message" }. Map 402 to "upgrade needed", 429 to a retry with the Retry-After header.
What I want: [describe the feature, e.g. "every event in my events table gets a QR code that opens its public page; show it on the event admin page with a download button"].
讓您的程式碼儲存庫了解 QRFLOW
加入 CLAUDE.md、AGENTS.md、.cursorrules 或 .github/copilot-instructions.md
## QR codes (QRFLOW.codes)
- Docs: https://qrflow.codes/llms-full.txt (Markdown), https://qrflow.codes/api/v1/openapi.json (OpenAPI 3.1).
- Base URL https://qrflow.codes/api/v1, header Authorization: Bearer $QRFLOW_KEY. Server-side only.
- Codes are created with POST /codes { type: "url", destination_data: { url }, label }. Store code.id and code.short_url.
- Change the destination with PATCH /codes/:id { destination_data: { url } }. Never change slug/domain_id after printing.
- Image: GET /codes/:id/image.svg (needs the key). Prefer paused: true over DELETE when a print exists.
- Webhooks arrive as POST with X-QRFLOW-Signature (t=,v1=HMAC-SHA256 of "t.rawBody"); verify with the raw body.
在 Lovable、Bolt、v0、Replit 和其他應用程式建置工具中
以前端為主、並提供後端(Supabase、無伺服器函式)的建置工具
Integrate QRFLOW.codes QR codes. The API refuses browser calls, so create a backend function (Supabase Edge Function / serverless function) that holds the secret QRFLOW_KEY and calls POST https://qrflow.codes/api/v1/codes with { "type": "url", "destination_data": { "url": "<the page URL>" }, "label": "<name>" }. Return code.id and code.short_url to the UI and save them in the database. Render the QR in the UI by encoding short_url with a QR library; add a "Download for print" button that fetches /codes/:id/image.svg through the same backend function. Reference: https://qrflow.codes/llms-full.txt
管理我的代碼的自訂 GPT
ChatGPT › 建立 GPT › Actions
Import from URL: https://qrflow.codes/api/v1/openapi.json
Authentication: API Key › Bearer › paste a Business key with the scopes you want the GPT to have.
Then the GPT can list, create, re-point and report on your codes. For a no-setup version, add the MCP connector instead (Developer mode › Plugins › https://qrflow.codes/mcp).
連接器啟用後可以提出的要求
已連接 QRFLOW MCP 伺服器的 Claude、ChatGPT、Claude Code
"Make a QR code for https://example.com/fall-menu, call it Fall menu, frame caption 'Scan for menu'."
"Which of my codes got the most scans this month? Show a breakdown by country for the top one."
"Point the 'Lobby poster' code at https://example.com/events/october."
"Name the 'Business card' code's link 'hi' on my domain."
"Pause every code with 'Summer' in the label."
"Make 40 codes, one per table, going to https://example.com/order?table=1 through 40."
"Show me the PNG of the 'Front door' code."
MCP 伺服器
在 Claude、ChatGPT、Cursor 和 Claude Code 中使用
QRFLOW 是位於 https://qrflow.codes/mcp 的 MCP 伺服器。連接一次並登入,之後就可以提出像是 「為我們的秋季菜單頁面建立 QR code,命名為 menu 並使用我的網域」、「將大廳海報上的代碼指向新頁面」 或 「上週傳單的掃描次數是多少,按國家分類?」 這類要求。助理會在相同規則下使用此 API 提供的相同工具,而代碼會以 mcp 為來源,出現在您的儀表板中。
不是開發人員?請參閱使用 AI 助理建立 QR code,其中以淺白文字說明各助理的確切操作步驟。
由 Glama 獨立評分並每小時進行健康檢查,也列於 awesome-remote-mcp-servers 目錄和官方 MCP Registry,名稱為 codes.qrflow/qrflow。
連接
Customize › Connectors › Add custom connector › 貼上網址,或按下 QRFLOW 目錄項目上的 Connect。Claude 會開啟 QRFLOW 登入頁面;按下 Allow。所有方案皆可使用。
https://qrflow.codes/mcp
Settings › Security and login › 開啟 Developer mode,接著前往 Settings › Plugins › + › 貼上網址;系統提示時登入。適用於 Plus、Pro、Team、Enterprise 和 Edu。
https://qrflow.codes/mcp
執行一個指令,然後輸入 /mcp 登入。加入 Business 金鑰作為標頭即可略過登入。
claude mcp add --transport http qrflow https://qrflow.codes/mcp
# or, with a key:
claude mcp add --transport http qrflow https://qrflow.codes/mcp --header "Authorization: Bearer $QRFLOW_KEY"
Cursor、Windsurf、VS Code,以及任何 MCP 用戶端
在該 URL 新增 HTTP 伺服器。OAuth 登入會在瀏覽器中進行;或者傳入含有金鑰的 Authorization 標頭。
{
"mcpServers": {
"qrflow": { "type": "http", "url": "https://qrflow.codes/mcp" }
}
}
您自己的代理(Anthropic 或 OpenAI SDK)
將 MCP connector 或工具指向該 URL,並使用 Business 金鑰作為 bearer;不需要瀏覽器登入流程。
// Anthropic Messages API, MCP connector
mcp_servers: [{ type: "url", url: "https://qrflow.codes/mcp", name: "qrflow", authorization_token: process.env.QRFLOW_KEY }]
助理可以做什麼
| 工具 | 功能 | Scope |
|---|---|---|
| list_code_kinds | 列出每種代碼及其欄位和所需方案。助理在建立特殊項目之前會先呼叫此工具。 | profile |
| list_domains | 列出您的連結網域、預設網域及其 ids。 | domains:read |
| get_qr_image | 提供助理可顯示或儲存的 PNG,以及供列印使用的 SVG URL。 | codes:read |
| get_account | 顯示帳戶的方案、功能和限制。 | profile |
安全機制
- 助理只會持有您帳戶的權杖;該權杖是在您於 QRFLOW 頁面按下 Allow 後核發。您可以隨時前往 Account › Connected apps 中斷連線。
- 權杖會綁定至 MCP 伺服器;無法重複用於 REST API。
- 所有寫入操作都會經過與儀表板相同的驗證:目的地允許清單、方案檢查和合理使用上限。
- 具破壞性的工具會清楚說明自身行為:
delete_qr_code會指示模型在已有列印品時優先暫停代碼。 - 探索文件位於
/.well-known/oauth-authorization-server和/.well-known/oauth-protected-resource;註冊遵循 RFC 7591;僅支援 PKCE S256。
SDK 和 OpenAPI 規格
- TypeScript / JavaScript:
npm install qrflow(npm)。零相依套件,支援 ESM 和 CommonJS,提供完整型別;可在 Node 18+、Bun、Deno 和 Workers 上執行。會自動重試 429,並提供verifyWebhook/parseWebhook。 - Python 3.9+,僅使用標準函式庫:qrflow.py。
- OpenAPI 3.1:/api/v1/openapi.json。匯入 Postman 或 Insomnia、以任何語言產生用戶端,或將其附加至 ChatGPT Action。
- 兩個用戶端都會拋出具型別的錯誤(
QRFlowError,包含status、code、message、retryAfter),並提供 webhook 驗證器。如果你想自行納入原始碼,單檔 TypeScript 原始碼仍位於 /sdk/qrflow.ts。
| TypeScript | Python | 呼叫 |
|---|---|---|
| me() | me() | GET /me |
| catalog() | catalog() | GET /catalog |
| listCodes({ limit, q }) | list_codes(limit, q) | GET /codes |
| getCode(id) | get_code(id) | GET /codes/:id |
| createCode(input) | create_code(**fields) | POST /codes |
| updateCode(id, patch) | update_code(id, **patch) | PATCH /codes/:id |
| deleteCode(id) | delete_code(id) | DELETE /codes/:id |
| makeDynamic(id) | make_dynamic(id) | POST /codes/:id/dynamic |
| scans(id, { from, to, group }) | scans(id, from_, to, group) | GET /codes/:id/scans |
| bulkCreate(rows, colors) | bulk_create(rows, **colors) | POST /codes/bulk |
| domains() | domains() | GET /domains |
| listWebhooks() / createWebhook() / testWebhook(id) / deleteWebhook(id) | list_webhooks() / create_webhook() / test_webhook(id) / delete_webhook(id) | /webhooks |
| imageUrl(id, size) | image_url(id, size) | 圖片網址(使用金鑰擷取) |
| verifyWebhook(raw, header, secret) | verify_webhook(raw, header, secret) | 驗證傳送內容的簽章 |
端點參考
基礎 URL https://qrflow.codes/api/v1。本文和回應皆為 JSON。日期採用 UTC 時區的 ISO 8601 格式。PATCH 僅傳送有變更的欄位。
GETprofile
方案、功能旗標、適用於此帳戶的限制,以及金鑰的範圍。
curl https://qrflow.codes/api/v1/me \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "id": "…", "email": "ops@example.com", "plan": "business", "paid": true,
"features": { "dynamic_codes": true, "custom_domain": true, "link_names": true, "gs1": true, "api_keys": true },
"limits": { "saved_codes": 25000, "bulk_per_month": 10000, "bulk_per_request": 2000, "link_domains": 5, "requests_per_minute": 600 },
"auth": "api_key", "scopes": ["codes:read", "codes:write"] }
GETpublic
原生類型(url、wifi、vcard、email、phone、sms、text、location)和約 50 種子類型(Instagram、Google 評論、Wi-Fi、應用程式商店……),各自列出所需欄位和適用方案。不需要金鑰。
curl https://qrflow.codes/api/v1/catalog
GETcodes:read
由新到舊排序。?limit= 最多 100;?q= 可搜尋標籤。
curl "https://qrflow.codes/api/v1/codes?limit=20&q=menu" \
-H "Authorization: Bearer $QRFLOW_KEY"
POSTcodes:write
規則與網站上的「儲存」相同:付費方案中的 url、phone、email、sms 和 location 代碼為動態代碼;Wi-Fi、vCard 和 text 則將內容直接編入圖樣。將子類型 id 放入 destination_data.subtype,即可建立例如 Google 評論代碼。選填的 domain_id 可指定代碼要使用哪個連結網域(GET /domains 會列出這些網域)。
curl -X POST https://qrflow.codes/api/v1/codes \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "type": "url", "destination_data": { "url": "https://example.com/menu" }, "label": "Table tents", "frame_style": "caption-below", "frame_caption": "Scan for menu" }'
{ "code": { "id": "…", "label": "Table tents", "kind": "url", "dynamic": true, "short_code": "x7k2p9a",
"short_url": "https://go.example.com/x7k2p9a", "scans": 0, "image_url": "https://qrflow.codes/api/v1/codes/…/image.svg", … } }
GETcodes:read
包含掃描次數、短連結和圖片網址的代碼。
curl https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY"
PATCHcodes:write
可更新以下任意欄位:destination_data(僅限動態代碼,印刷品仍然有效)、label、paused、expires_at(ISO 格式或 null)、slug(你網域上的連結名稱)、domain_id(此代碼使用的連結網域;null = 帳戶預設值)、fg_color、bg_color、frame_style、frame_caption、frame_caption2。僅傳送要變更的欄位。
curl -X PATCH https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "destination_data": { "url": "https://example.com/menu-fall" }, "slug": "menu" }'
DELETEcodes:write
永久刪除,包括掃描記錄。動態代碼的印刷連結將停止解析。如果印刷品仍在外流通,建議使用 paused: true。
curl -X DELETE https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY"
204 No Content
POSTcodes:write
印刷圖樣會變更(現在會編碼短連結),因此之後請重新產生圖片。
curl -X POST https://qrflow.codes/api/v1/codes/$ID/dynamic \
-H "Authorization: Bearer $QRFLOW_KEY"
GETcodes:read
可供印刷的 SVG,包含外框和顏色。?size= 設定模組網格的寬度(px);檔案本身可無損縮放。
curl https://qrflow.codes/api/v1/codes/$ID/image.svg \
-H "Authorization: Bearer $QRFLOW_KEY" -o code.svg
GETanalytics:read
?from= 和 ?to=(ISO 日期,最多 92 天,預設為最近 30 天),以及 ?group= day、device、country、city、browser、os 或 referrer。數據與分析頁面相同。
curl "https://qrflow.codes/api/v1/codes/$ID/scans?from=2026-09-01&to=2026-09-21&group=day" \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "code_id": "…", "from": "…", "to": "…", "group": "day", "total": 412,
"rows": [ { "key": "2026-09-01", "scans": 18 }, { "key": "2026-09-02", "scans": 25 }, … ] }
POSTcodes:write
單次呼叫最多可建立 2,000 個 URL 代碼,且全部都是動態代碼。會計入與 Bulk 頁面相同的每月批次額度(Business 方案為 10,000)。非網址的資料列會列在 rejected;其餘資料列則會建立代碼。
curl -X POST https://qrflow.codes/api/v1/codes/bulk \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "rows": [ { "destination": "https://example.com/t/1", "label": "Table 1" }, { "destination": "https://example.com/t/2", "label": "Table 2" } ] }'
{ "codes": [ … ], "rejected": [], "remaining_this_month": 9998 }
GETcodes:read
用於零售包裝的代碼。每項產品包含一個 GTIN、印在包裝上的網址,以及其背後的連結。使用 ?q= 搜尋名稱和 GTIN。Business 方案。
curl https://qrflow.codes/api/v1/products \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "products": [ { "gtin": "00860001234565", "name": "Wildflower Honey 12 oz",
"digital_link": "https://id.example.com/01/00860001234565",
"page_url": "https://id.example.com/p/00860001234565",
"links": [ { "link_type": "gs1:pip", "url": "…", "is_default": true, "batch": null } ] } ] }
POSTcodes:write
gtin 和 name 為必填;brand 和 url 為選填。寫入前會驗證檢查碼,並將 8、12、13 和 14 位數格式統一正規化為 14 位數。若 GTIN 已由你持有,會回傳 409,而不會建立第二項產品。
curl -X POST https://qrflow.codes/api/v1/products \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{"gtin":"00860001234565","name":"Wildflower Honey 12 oz","brand":"Sunny Acres","url":"https://sunnyacres.example/honey"}'
{ "product": { "gtin": "00860001234565", "digital_link": "https://id.example.com/01/00860001234565", … } }
PUTcodes:write
一個 GTIN 可同時連結至多個地點,並為每個地點標示用途。電話會使用預設連結;要求指定類型的應用程式則會取得該類型的連結。具冪等性:相同的 link_type 和 batch 會取代該連結,而非新增第二個,因此夜間指令碼可重複執行。傳入 batch 可將連結限定於單一批次,藉此發布召回資訊,而不影響同一批次以外的產品。
curl -X PUT https://qrflow.codes/api/v1/products/00860001234565/links \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{"link_type":"gs1:recallStatus","url":"https://sunnyacres.example/recall-a42","title":"Recall notice","batch":"A42","is_default":true}'
GETanalytics:read
依 GTIN 統計最近 ?days= 天(1 到 365,預設 30)的數據,並按國家、裝置、連結類型和批次分類。went_nowhere 計算未找到目的地的掃描次數,應為零。
curl "https://qrflow.codes/api/v1/products/00860001234565/scans?days=30" \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "gtin": "00860001234565", "days": 30, "total": 412, "went_nowhere": 0,
"by_link_type": [ { "key": "gs1:pip", "scans": 390 }, { "key": "gs1:recallStatus", "scans": 22 } ],
"by_batch": [ { "key": "A42", "scans": 22 } ] }
GETdomains:read
你已連結的網域、其狀態,以及動態代碼預設使用的網域(default_base)。將網域的 id 作為代碼的 domain_id 傳入,即可讓該代碼使用其他網域。
curl https://qrflow.codes/api/v1/domains \
-H "Authorization: Bearer $QRFLOW_KEY"
GETwebhooks:manage
你的 webhooks、其事件、最近狀態和失敗次數。
curl https://qrflow.codes/api/v1/webhooks \
-H "Authorization: Bearer $QRFLOW_KEY"
POSTwebhooks:manage
url 必須是位於公開主機上的 https 網址;events 可為 scan、code.created、code.updated、code.deleted。簽署密鑰只會回傳一次。
curl -X POST https://qrflow.codes/api/v1/webhooks \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/hooks/qrflow", "events": ["scan", "code.updated"] }'
{ "webhook": { "id": "…", "url": "…", "events": ["scan", "code.updated"], "active": true, "secret": "whsec_…" } }
POSTwebhooks:manage
立即傳送已簽署的 ping,並回報回應。
curl -X POST https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $QRFLOW_KEY"
DELETEwebhooks:manage
停止所有傳送,包括已排入佇列的重試。
curl -X DELETE https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $QRFLOW_KEY"
204 No Content
GETpublic
外框 id 及各自所需內容(標題、第二行),依照自訂工具中的分類分組。不需要金鑰。
curl https://qrflow.codes/api/v1/frames
Code 物件
所有操作代碼的端點都會回傳相同結構。請忽略不熟悉的欄位;之後可能會新增欄位。
| 欄位 | 類型 | 說明 |
|---|---|---|
| id | uuid | 穩定的 id。其他呼叫都會用到。 |
| label | string | null | 控制面板中的名稱。最多 120 個字元。可使用 ?q= 搜尋。 |
| kind | string | 目錄 id:url、wifi、instagram、googlereview,... kind_label 是易讀名稱。 |
| type | string | 編碼類型:url、text、wifi、vcard、email、phone、sms、location。 |
| destination_data | object | 你傳送的欄位(加上 kind 的 subtype)。destination 是其單行摘要。 |
| dynamic | boolean | 若掃描會經過 QRFLOW,且目的地可變更,則為 True。dynamic_capable 表示此類型在付費方案中是否可設為動態。 |
| short_code | string | 七個字元,永不變更。 |
| short_url | string | 動態代碼要印出的網址。若已設定,會包含你的網域和 slug。 |
| domain_id | uuid | null | 此代碼使用的連結網域;null 表示帳戶預設值。 |
| fg_color, bg_color | hex | 模組和背景顏色。 |
| has_logo | boolean | 已在控制面板新增標誌;image.svg 會包含該標誌。 |
| frame_style, frame_caption, frame_caption2 | string | null | 外框 id 和標題,與自訂工具中的設定相同。 |
| scans | integer | 累計掃描次數。 |
| created_at, updated_at | ISO 8601 | UTC。 |
| manage_url | url | 控制面板中的代碼頁面,可用於「在 QRFLOW 中開啟」連結。 |
| image_url | url | GET /codes/:id/image.svg。需要 Authorization 標頭;不是公開圖片網址。 |
| svg_download_url, png_download_url | url | 相同的 SVG(外框、顏色、標誌)和純 PNG,透過有效期為 24 小時且不需標頭的簽署連結提供:適用於 <img> 標籤、指令碼和需要儲存檔案的助理。download_expires_at 表示連結何時失效;每次讀取代碼都會取得新的連結。 |
其他結構:Scans(code_id, from, to, group, total, rows[key, scans])、Domain(id, host, status, active, is_default, verified_at, grace_until)、Webhook(id, url, events, active, last_status, last_delivery_at, consecutive_failures,另含 secret 一次)、Me(id, email, plan, paid, features, limits, auth, scopes)和 Error(error, message)。OpenAPI 文件列出所有屬性的型別。
Business
Webhooks
QRFLOW 會在事件發生時呼叫你的 https 網址。請在 Account › Webhooks 建立 webhook,或使用 POST /webhooks;簽署密鑰只會提供一次。每個帳戶最多可建立 10 個。
| 事件 | 時機 | data |
|---|---|---|
| scan | 批次傳送:每隔幾分鐘傳送自上次傳送後的所有新掃描,每次最多 500 筆。 | count, from, to, scans[],包含 code_id、label、short_code、slug、scanned_at、device、country、city、referrer、browser、os、language |
| code.created | API 和助理建立後立即傳送;從控制面板建立則會在幾分鐘內傳送。批次請求會傳送一個包含 bulk: true 和 codes[] 的事件。 | code, source |
| code.updated | 傳送時機相同。涵蓋目的地、標籤、暫停、到期日、連結名稱、網域、顏色、外框,以及轉換為動態代碼。 | code, changed[](已變更的欄位名稱) |
| code.deleted | 傳送時機相同。 | code: { id, label, short_code, slug } |
| ping | 按下 Test 時。 | webhook_id, message |
接收內容
每個 payload 都是 { id, event, created_at, data }。同一次傳送的重試會使用相同的 id,因此你可以用它去重。
{
"id": "9b1c6d2e-…",
"event": "scan",
"created_at": "2026-09-21T18:05:00.000Z",
"data": {
"count": 2,
"from": "2026-09-21T18:00:00.000Z",
"to": "2026-09-21T18:04:12.331Z",
"scans": [
{ "code_id": "…", "label": "Table tents", "short_code": "x7k2p9a", "slug": "menu", "scanned_at": "2026-09-21T18:03:40.101Z",
"device": "mobile", "country": "US", "city": "Las Vegas", "referrer": null, "browser": "Safari", "os": "iOS", "language": "en-US" },
{ "code_id": "…", "label": "Table tents", "short_code": "x7k2p9a", "slug": "menu", "scanned_at": "2026-09-21T18:04:12.331Z",
"device": "mobile", "country": "MX", "city": "Tijuana", "referrer": null, "browser": "Chrome", "os": "Android", "language": "es-MX" }
]
}
}
{
"id": "2f0a…",
"event": "code.updated",
"created_at": "2026-09-21T18:06:00.000Z",
"data": {
"code": { "id": "…", "label": "Table tents", "kind": "url", "dynamic": true, "short_url": "https://go.example.com/menu", "scans": 412, "…": "…" },
"changed": ["destination_data"]
}
}
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: QRFLOW-Webhooks/1.0 (+https://qrflow.codes/developers)
X-QRFLOW-Event: scan
X-QRFLOW-Signature: t=1758477900,v1=5f1c…e9
驗證簽章
X-QRFLOW-Signature: t=<unix seconds>,v1=<hex>。使用你的密鑰,對 ${t}.${rawBody} 計算 HMAC-SHA256,並以常數時間比較結果與 v1;若 t 超過五分鐘,則拒絕請求。請使用收到的原始位元組,絕不可使用重新序列化的物件。Next.js 和 Python 的可用接收端範例位於 recipes 中,兩個 SDK 也都包含此輔助函式。
傳送規則
- 請在 8 秒內回覆任何 2xx 狀態碼。回覆後再處理工作。
- 其他回應會在 1、5、15、60、240 和 720 分鐘後重試。
- 連續失敗 20 次後,webhook 會停用並以電子郵件通知帳戶擁有者。修復接收端後重新啟用;已排入佇列的重試會繼續執行。
- 網址必須是位於公開主機上的 https 網址。localhost、私人網段和 qrflow.codes 本身都會遭拒。開發時請使用通道。
- 按下 Test 可接收已簽署的
ping,並查看伺服器回覆的狀態。
錯誤
每個錯誤都是 { "error": "<code>", "message": "<what to do>" },並使用下方的狀態碼。訊息是寫給使用者看的;請顯示訊息。
| 狀態 | error | 說明 |
|---|
症狀、原因、修正方式
疑難排解
每次呼叫都收到 401 invalid_token
原因標頭錯誤,或金鑰已失效。
修正方式請使用完全相同的 Authorization: Bearer qrf_live_… 格式(中間是空格,不是冒號)。確認金鑰未在 Account › API keys 中撤銷。如果你是從聊天或文件複製金鑰,請留意末尾的句點或智慧引號。
使用可在 MCP 伺服器運作的權杖呼叫 /api/v1 時收到 401
原因為 https://qrflow.codes/mcp 簽發的權杖僅適用於該伺服器。
修正方式REST 請使用 API 金鑰,或不帶 resource= 再執行一次 OAuth 流程,以取得 REST API 的權杖。
建立金鑰或 webhook 時收到 402 upgrade_required
原因兩者都是 Business 功能。
修正方式請在 /pricing 升級,或使用 MCP 伺服器;所有方案都可透過登入使用該伺服器。
OAuth 應用程式呼叫 POST /codes 時收到 402
原因使用者的方案不包含應用程式要求的功能(動態代碼、網域)。
修正方式先讀取 GET /me 的 features,再調整處理方式:仍然建立代碼(Free 方案會建立靜態代碼),或告知使用者需要哪種方案。
403 insufficient_scope
原因金鑰建立時就已固定其範圍。 修正:建立一個具有所需範圍的新金鑰,並撤銷舊金鑰。若使用 OAuth,請在 authorize 請求中要求所需範圍。
PATCH destination_data 時出現 400 not_dynamic
原因:代碼是靜態的:Wi-Fi/vCard/文字類型,或是在已使用唯一一個免費動態代碼後,於 Free 方案建立的代碼。
修正:對於 url/phone/email/sms/location,請在帳戶仍有額度時呼叫 POST /codes/:id/dynamic,然後重新下載並列印(圖片會改變)。Wi-Fi、vCard 和文字代碼永遠無法設為動態;請建立一個會開啟頁面的 url 代碼。
設定 slug 時出現 400 no_domain
原因:連結名稱會使用你的網域。
修正:先在 Account 頁面連接並驗證網域。在 qrflow.codes/q 上,路徑一律是 short_code。
slug 出現 409 conflict
原因:你的其他代碼已使用該名稱。
修正:呼叫 GET /codes?q= 尋找該代碼,或選擇其他名稱。名稱僅限帳戶內唯一,並非全域唯一。
瀏覽器主控台出現 CORS 錯誤
原因:API 僅接受伺服器對伺服器的呼叫(以及 Canva)。這是刻意設計的:放在網頁中的金鑰等同於外洩。
修正:將呼叫移至 route handler、server action、edge function 或後端,再由頁面呼叫該端點。
圖片上有 QRFLOW 標記
原因:該代碼是由未登入的人建立。此標記僅用於匿名下載。
修正:任何帳戶都能移除標記,包括免費帳戶。已儲存代碼的圖片不會帶有標記。
新增網域後,short_url 仍顯示 qrflow.codes/q/…
原因:網域尚未驗證,或 CNAME 設定錯誤。
修正:在 Account 頁面或呼叫 GET /domains 檢查狀態(狀態必須是 verified)。驗證完成後,現有代碼會自動切換。
在 <img> 標籤中,image_url 回傳 401
原因:它需要 Authorization 標頭,而 <img> 無法傳送標頭。
修正:使用同一個 Code 物件中的 svg_download_url 或 png_download_url:這些簽署連結無需標頭,且有效期為 24 小時。若需要永久連結,請透過伺服器代理 image_url(請參閱 Next.js 範例),或自行編碼 short_url。
我需要 PNG,不是 SVG
原因:SVG 包含外框和標誌;PNG 則是純代碼。
修正:GET /codes/:id/image.png(使用 bearer 或簽署的 png_download_url)會回傳 256 到 2048 px 的 PNG。若要取得含外框的 PNG,請使用 sharp 或 resvg 轉換 SVG(sharp(svgBuffer).png().toBuffer())。
助理說圖片端點拒絕了請求,於是自行繪製代碼
原因:它擷取了需要 bearer 的 image_url。
修正:現在每個代碼都會附帶 png_download_url 和 svg_download_url,get_qr_image 也會回傳這些連結;助理無需登入即可使用 curl 擷取。自行繪製、編碼相同 short_url 的代碼仍可正常運作,也會計入掃描次數,但不含外框和標誌。
Webhook 一直沒有送達
原因:URL 規則或接收端設定有問題。
修正:URL 必須是位於公開主機上的 https(不可使用 localhost、私人 IP 或 qrflow.codes)。按下 webhook 上的 Test 按鈕:結果會顯示伺服器回應的狀態。掃描事件會批次處理,最多可能需要約五分鐘;來自儀表板的 code.* 事件也會排隊幾分鐘,而 API 和 MCP 寫入則會立即送達。
簽章一直無法驗證
原因:你簽署的是重新序列化後的本文。
修正:在解析 JSON 之前,使用收到的原始位元組進行驗證。在 Express 中,於該路由使用 express.raw({ type: 'application/json' });在 Next.js App Router 中使用 await req.text();在 Flask 中使用 request.get_data()。接著計算 ${t}.${raw}\ 的 HMAC-SHA256。
Webhook 自行停用
原因:連續失敗二十次。
修正:修復接收端後,再將其設為啟用(Account › Webhooks,或刪除後重新建立)。發生時你會收到電子郵件通知。排隊中的重試會繼續執行。
Webhook 重複送達
原因:若 2xx 回應太慢(超過 8 秒),就會視為失敗並重試。
修正:先回應,再處理。使用 payload 的 id 去重;該 id 在重試期間保持不變。
匯入期間出現 429 rate_limited
原因:每個金鑰每分鐘 600 次請求。
修正:使用 POST /codes/bulk(單次請求可建立 2,000 個代碼),不要每個代碼都單獨 POST;或依 Retry-After 指定的秒數暫停。
我刪除了代碼,列印的海報現在顯示「Code not found」
原因:刪除是永久性的,連結也會失效。
修正:無法復原。下次請使用 PATCH { paused: true };暫停的代碼會顯示友善頁面,之後也可以恢復。
降級後,我的金鑰停止運作
原因:離開 Business 方案後,金鑰仍可使用 30 天,之後會回應 402。
修正:重新訂閱;資料並未刪除,相同的金鑰會再次生效。
清單中沒有的問題?請寄信至 hello@qrflow.codes,並附上完整請求內容和收到的 JSON 錯誤。Business 帳戶可享優先處理。
限制與合理使用
| 限制 | |
|---|---|
| 每個金鑰每分鐘的請求數 | 600。超過後會回傳 429,並附上 Retry-After。 |
| 每個帳戶的金鑰數 | 10 |
| 每個帳戶的 Webhook 數 | 10 |
| 已儲存代碼(合理使用) | Premium 為 1,000 個,Business 為 25,000 個;API 會在達到該數量兩倍時停止。 |
| Bulk | Premium 每月 500 個(每次請求 500 個);Business 每月 10,000 個(每次請求 2,000 個)。 |
| 連結網域 | Premium 為 1 個,Business 為 5 個 |
| 掃描次數 | 無限制。Premium 每個代碼每月達 100,000 次掃描、Business 達 1,000,000 次時會收到確認電子郵件;不會進行節流。 |
| 掃描分析時間範圍 | 每次請求 92 天 |
| 清單頁面大小 | 100(?limit=) |
| Label / captions / slug | 120 / 60 / 40 個字元 |
| Webhook 逾時與重試 | 8 秒;於 1、5、15、60、240 和 720 分鐘後重試;連續失敗 20 次後停用。 |
| 離開 Business 方案後 | 金鑰和 webhook 仍可使用 30 天,之後回傳 402。資料不會刪除。 |
合理使用量是方案定價所涵蓋的用量。達到該數量時不會進行節流;API 會在達到兩倍用量時停止,並會先由專人寄信通知。若需要更高用量,請寄信至 hello@qrflow.codes。
安全性:保護你和掃描代碼的人
QRFLOW 如何保護你的帳戶
- 金鑰只會顯示一次,並以 SHA-256 雜湊值儲存。QRFLOW 的任何人都無法還原金鑰;若遺失,請建立新金鑰。
- 每個請求都限定於金鑰所屬的帳戶。其他帳戶的代碼 id 會回傳 404,不會洩漏資料。
- 每個金鑰的範圍固定,因此報表儀表板用的金鑰無法建立或刪除代碼。
- 每個金鑰每分鐘可發出 600 次請求;超過後會明確回傳 429,不會拖慢其他人的服務。
- 目的地採用允許清單:http、https、mailto、tel、sms、geo,以及少數應用程式 scheme(whatsapp、tg、signal、spotify、app stores)。建立時會拒絕 javascript:、data: 和 file:,因此遭入侵的整合無法將你的代碼變成攻擊工具。
- Webhook URL 必須是位於公開主機上的 https;QRFLOW 絕不呼叫私人網路或自身。每次傳送都會簽署,每個 payload 都有穩定的 id。
- OAuth 用戶端必須使用 PKCE S256 註冊,且權杖會綁定至核發對象的伺服器;發給 MCP 伺服器的權杖無法在 REST API 上重放。
- 任何人都可以在 Account 頁面撤銷金鑰或中斷應用程式連線;變更會立即生效。
你應採取的措施
- 使用環境變數,絕不要將金鑰寫入原始碼。若金鑰進入 git 歷史記錄,請撤銷它。
- 僅在伺服器端使用。API 會拒絕瀏覽器來源,但包裝 API 的自有端點也需要驗證,否則任何人都能使用你的額度建立代碼。
- 為每個整合建立獨立金鑰,並只授予所需範圍;金鑰名稱應使用整合名稱。撤銷其中一個金鑰時,只會影響一項整合。
- 驗證 webhook 簽章,並拒絕超過五分鐘的時間戳記。
- 若使用者資料會放入標籤或目的地,請記得 QRFLOW 會儲存這些資料;盡可能避免在標籤中放入個人資料。
掃描會記錄哪些資料,以及不會記錄哪些資料
- 每次重新導向都會儲存裝置類型、國家、城市、來源網址、瀏覽器、作業系統和語言(這些資料取自請求),以及代碼 + 日期 + IP + user agent 的單向雜湊值,讓擁有者能計算不重複訪客數。無法從雜湊值還原地址。
- 不會在掃描者的裝置上設定 cookie,掃描記錄也不會保留 IP 位址本身。已知的機器人和連結預覽爬蟲會略過。
- 刪除代碼會一併刪除其掃描記錄。刪除帳戶則會刪除所有資料。
- 完整說明:https://qrflow.codes/privacy 和 https://qrflow.codes/terms.
版本管理與穩定性
API 會在路徑中標示版本:/api/v1。在 v1 中,我們會新增欄位、端點、種類和事件;不會移除或重新命名任何項目,程式碼應忽略回應中的未知欄位。
若 v1 必須進行破壞性變更,將以 /api/v2 發布,而 v1 至少會繼續運作十二個月。棄用通知會提前 90 天寄給金鑰擁有者。
MCP 伺服器的工具也遵循相同規則:只會新增參數,每個工具都會保留原有名稱。
/api/v1/openapi.json 中的 OpenAPI 文件和 /llms-full.txt 中的 Markdown 都是從提供 API 的程式碼產生,因此描述的是目前線上實際提供的內容。
開發者常見問題
使用 QRFLOW API 需要付費嗎?
API 金鑰包含在 Business 方案中,每月 $29,按月計費。MCP 伺服器(Claude、ChatGPT、Cursor、Claude Code)和供你自有應用程式使用的 OAuth,則可透過登入在所有方案中使用;可建立的內容依方案而定。GET /catalog、GET /frames 和 /preview.svg 完全不需要金鑰。
我可以透過 API 免費產生 QR code 嗎?
不能使用金鑰。若只需要純靜態圖片,qrflow.codes 的免費產生器或任何開源 QR 函式庫都能勝任。API 提供動態代碼、自有網域、分析、批次處理和 webhook,這些功能屬於付費帳戶。
我可以從瀏覽器呼叫 API 嗎?
不行。API 會拒絕瀏覽器來源,避免金鑰出現在網頁中。請從 route handler、server action、edge function 或後端呼叫 API,再由頁面呼叫該端點。
可以取得哪些圖片格式?
SVG 可包含你的顏色、外框、說明文字和標誌(GET /codes/:id/image.svg,標稱尺寸為 256 到 4096 px);另有純 PNG(GET /codes/:id/image.png,256 到 2048 px)。兩者都可使用 bearer,或使用每個 Code 物件都附帶的簽署 svg_download_url / png_download_url;這些連結無需標頭,有效期為 24 小時。MCP 工具 get_qr_image 會內嵌回傳 PNG,並附上兩個連結。
QR code 列印後還能修改嗎?
可以,但必須是動態代碼(付費方案中的 url、phone、email、sms、location)。使用新的 destination_data 呼叫 PATCH /codes/:id;圖片不會改變,但下一次掃描會前往新的目的地。Wi-Fi、vCard 和文字代碼的內容直接儲存在圖片中,因此無法修改。
short_url 和目的地有什麼不同?
short_url 是圖片中包含的連結(go.example.com/menu)。目的地是該連結重新導向的位置(https://example.com/menu-fall)。列印一次 short_url 後,你可以隨時變更目的地。
代碼可以使用我的自有網域嗎?
可以。Premium 可連接 1 個網域,Business 可連接 5 個;你需要新增 CNAME,並在 Account 頁面完成驗證。Business 可透過 domain_id 為每個代碼選擇網域。連結名稱(slug)可在該網域上建立易讀路徑。
掃描記錄會保存哪些掃描者資料?
請求中的裝置類型、國家、城市、來源網址、瀏覽器、作業系統和語言,以及用於計算不重複訪客數的單向每日雜湊值。不使用 cookie,也不儲存 IP 位址。資料足以製作圖表,但不足以識別任何人。詳情:https://qrflow.codes/privacy#scans
有 npm 或 PyPI 套件嗎?
npm:npm install qrflow\(https://www.npmjs.com/package/qrflow),零相依套件,支援 ESM 和 CommonJS,提供完整 TypeScript 型別,可在 Node 18+、Bun、Deno 和 Workers 上執行;它包裝所有端點、重試 429,並包含 verifyWebhook/parseWebhook。Python:https://qrflow.codes/sdk/qrflow.py 提供單一檔案用戶端(僅使用標準函式庫),並包含 verify_webhook;PyPI 套件將於之後推出。
支援 Claude、ChatGPT、Cursor 和 Claude Code 嗎?
支援。QRFLOW 是 MCP 伺服器,網址為 https://qrflow.codes/mcp.。將它新增為連接器,登入一次,然後用一般文字提出需求即可。十一種工具涵蓋建立、編輯、暫停、命名、批次處理、分析、圖片和網域。
我可以讓自己的使用者將 QRFLOW 帳戶連接到我的應用程式嗎?
可以,使用 OAuth 2.0。請在 /api/oauth/register 註冊用戶端(不需要帳戶),使用 PKCE 將使用者導向 /oauth/authorize,並使用他們的權杖呼叫 API。產生的代碼會存入他們帳戶中,並依照其方案計費。
如何在 localhost 上測試 Webhook?
使用通道(cloudflared 或 ngrok)公開你的開發伺服器,並將其 https 位址設為 Webhook URL,然後在 Account › Webhooks 按下 Test,即可收到已簽署的 ping。Webhook URL 必須是公開的 https 位址;localhost 和私人位址都會遭到拒絕。
如果我取消 Business 方案,我的整合會怎麼樣?
金鑰和 Webhook 會繼續運作 30 天,之後會回應 402。代碼、掃描和網域會保留在帳戶中。重新訂閱後,所有功能都會恢復,且沿用相同的金鑰。
如何透過 API 建立 Google 評論、Instagram、Wi-Fi 或 PDF 代碼?
GET /catalog 會列出所有類型及其欄位。接著使用該類型的 type 和欄位呼叫 POST /codes;對於以下類型,請加上 subtype:{ type: 'url', destination_data: { subtype: 'googlereview', placeId: 'ChIJ…' } }, { type: 'wifi', destination_data: { ssid, password, encryption: 'WPA' } }, { type: 'url', destination_data: { subtype: 'instagram', handle: 'acme' } }。
API 可以將標誌上傳到代碼嗎?
目前還不行。請在控制面板中新增標誌;image.svg 會包含標誌,而 has_logo 會告訴你標誌是否存在。顏色、外框和說明文字都可以透過 API 設定。
API 穩定嗎?
v1 只會新增功能,不會移除或重新命名。破壞性變更會以 v2 推出,v1 至少會維持可用十二個月,並透過電子郵件提前 90 天通知。
提供給代理程式、工具及閱讀本文的助理
機器可讀格式
本頁所有內容都有可供軟體擷取的格式。所有內容皆由提供 API 的程式碼產生,因此永遠不會過時。
| URL | 說明 | |
|---|---|---|
| llms-full.txt | https://qrflow.codes/llms-full.txt | 本完整參考文件的 Markdown 版本:概念、所有端點、所有 MCP 工具、操作指南、疑難排解及常見問題。與本頁由相同來源產生。 |
| developers.md | https://qrflow.codes/developers.md | 相同文件,適用於擷取 a.md 的工具。 |
| llms.txt | https://qrflow.codes/llms.txt | 提供給助理的網站索引,並指向此處。 |
| 單頁 API 說明 | https://qrflow.codes/qr-code-api | 說明 API 的功能、何時改用用戶端程式庫會更合適,以及費用。這是本參考文件的精簡版,供評估時參考,而非用於建置。 |
| openapi.json | https://qrflow.codes/api/v1/openapi.json | OpenAPI 3.1。可匯入 Postman、Insomnia、程式碼產生器或 ChatGPT Action。 |
| MCP 伺服器 | https://qrflow.codes/mcp | Streamable HTTP、使用動態註冊的 OAuth,或以 Business 金鑰作為 bearer。 |
| server.json | https://qrflow.codes/.well-known/mcp/server.json | MCP 登錄檔資訊清單。 |
| OAuth 探索 | https://qrflow.codes/.well-known/oauth-authorization-server | RFC 8414 中繼資料;受保護資源文件就在旁邊。 |
| npm 套件 | https://www.npmjs.com/package/qrflow | npm install qrflow。具型別的用戶端、零相依套件、Webhook 驗證。Python 單檔用戶端位於 https://qrflow.codes/sdk/qrflow.py. |
| GitHub | https://github.com/nativecodeapps/qrflow-sdk | 用戶端、OpenAPI 快照,以及適用於 Next.js、Workers、Express、FastAPI 和 Flask Webhook 的可執行範例。歡迎提交問題和 PR。 |
有任何問題、想法,或希望我們新增某種代碼:hello@qrflow.codes。條款:/terms。隱私權:/privacy。