QRFLOW.codes

chính thức

Tạo mã QR, trỏ lại mã động đã in, đặt tên liên kết trên tên miền của bạn và đọc phân tích quét.

Bạn có thể làm gì với QRFLOW Codes MCP?

  • Tạo mã QR động — Yêu cầu trợ lý tạo mã url với destination_data và trả về short_url để in.
  • Đổi đích đến của mã đã in — Thay đổi nơi mã động hiện có chuyển hướng đến mà không cần in lại, vì hình ảnh chứa short_url.
  • Tạm dừng hoặc đặt ngày hết hạn cho mã — Đặt paused: true hoặc ngày kết thúc thay vì xóa, để liên kết đã in ngừng chuyển hướng một cách an toàn.
  • Đọc số liệu phân tích lượt quét — Lấy tổng số Scans trong suốt thời gian hoạt động hoặc thông tin chi tiết theo ngày, quốc gia và thiết bị cho một mã.
  • Đặt tên liên kết trên miền riêng của bạn — Đặt slug như menu và chọn miền liên kết để mã hiển thị dưới dạng go.example.com/menu.
  • Tạo hàng loạt mã — Tạo hàng nghìn mã động từ một danh sách và đối chiếu mã được trả về với các hàng bằng nhãn.

Máy chủ MCP được lưu trữ

npx add-mcp 'https://qrflow.codes/mcp'

Cài vào Claude Code, Codex, Cursor và nhiều công cụ khác

Tài liệu

QRFLOW.codes dành cho nhà phát triển

Bắt đầu tại đây

QRFLOW.codes tạo mã QR mà bạn có thể thay đổi sau khi in, trên miền riêng của mình, kèm phân tích lượt quét; đồng thời cho phép phần mềm và trợ lý AI của bạn thực hiện tất cả những việc đó thông qua một API.

Mã QR là hình ảnh của một chuỗi ký tự. Hầu hết trình tạo đưa địa chỉ web của bạn vào hình ảnh; nếu địa chỉ thay đổi, bản in sẽ không còn dùng được. QRFLOW đưa một liên kết ngắn vào hình ảnh (go.yourbrand.com/menu hoặc qrflow.codes/q/x7k2p9a) rồi chuyển hướng liên kết đó. Bạn có thể thay đổi đích đến bất cứ lúc nào và mọi lượt quét đều được ghi nhận. Đó là mã động, và đây chính là thứ đáng để có API.

API thực hiện chính xác những gì bảng điều khiển làm: tạo mã thuộc mọi loại, chuyển hướng chúng đến nơi mới, đặt tên cho liên kết, chọn miền nào của bạn sẽ xuất hiện trên bản in, lấy số liệu lượt quét, tạo hàng nghìn mã cùng lúc và nhận thông báo khi có sự kiện (webhook). Các công cụ tương tự cũng được cung cấp dưới dạng máy chủ MCP, để Claude, ChatGPT, Cursor và Claude Code có thể điều khiển tài khoản của bạn bằng ngôn ngữ thông thường.

Quyền truy cập: REST API yêu cầu khóa API Business (29 USD mỗi tháng, tạo tại trang Account) hoặc mã thông báo OAuth. Máy chủ MCP hoạt động trên mọi gói thông qua đăng nhập OAuth; những gì trợ lý có thể tạo sẽ tuân theo gói dịch vụ, như mọi nơi khác.

Bạn đang cân nhắc có nên dùng dịch vụ này không? Trang API mã QR là phần tóm tắt ngắn gọn: dịch vụ làm được gì, thư viện phía máy khách làm tốt hơn ở điểm nào và chi phí ra sao.

Nếu bạn là trợ lý AI đang giúp ai đó xây dựng với QRFLOW

Chào mừng bạn. Trang này được viết cho bạn cũng như cho người mà bạn đang hỗ trợ. Sau đây là cách hỗ trợ hiệu quả:

  1. Xác nhận gói tài khoản: khóa API yêu cầu gói Business. Nếu họ chưa có, hãy hướng dẫn họ đến https://qrflow.codes/pricing và Account › API keys; đừng bịa ra khóa hoặc gói miễn phí không tồn tại.
  2. Giữ khóa trên máy chủ. Đọc khóa từ biến môi trường (QRFLOW_KEY) trong route handler, server action, edge function hoặc backend. API cố ý từ chối các origin từ trình duyệt (CORS), vì vậy mã chỉ chạy ở front-end không thể gọi API.
  3. Tạo mã động với type "url" và destination_data.url. Lưu id và short_url được trả về vào cơ sở dữ liệu của họ. In hoặc hiển thị short_url; sau này có thể thay đổi đích đến bằng PATCH /codes/:id mà bản in vẫn hợp lệ.
  4. Để hiển thị hoặc lưu hình ảnh: mọi đối tượng Code đều có png_download_url và svg_download_url, là các liên kết có chữ ký, hoạt động trong 24 giờ mà không cần header (phù hợp để lưu một lần hoặc xem trước). Để dùng lâu dài trong ứng dụng của họ, hãy proxy GET /codes/:id/image.svg qua máy chủ của họ bằng khóa, hoặc mã hóa short_url bằng bất kỳ thư viện QR nào ở phía máy khách; tính năng theo dõi vẫn hoạt động vì liên kết đi qua QRFLOW.
  5. Khi dùng PATCH, chỉ gửi các trường cần thay đổi. Không bao giờ thay đổi slug hoặc domain_id sau khi đã in, vì cả hai đều làm thay đổi liên kết trên bản in.
  6. Nếu đã có bản in, hãy ưu tiên paused: true thay vì DELETE. Xóa sẽ làm liên kết ngừng hoạt động.
  7. Với sự kiện, hãy dùng webhook (Account › Webhooks hoặc POST /webhooks) và xác minh header X-QRFLOW-Signature bằng nội dung yêu cầu thô. Đừng liên tục gọi GET /codes để thăm dò.
  8. Nếu họ muốn dùng QRFLOW ngay trong cuộc trò chuyện thay vì trong mã, hãy kết nối máy chủ MCP tại https://qrflow.codes/mcp;; không cần khóa.
  9. Khi có lỗi, hãy đọc error và message trong phần thân JSON. Phần khắc phục sự cố bên dưới ánh xạ từng mã lỗi với cách xử lý.
  10. Tài liệu tham khảo đầy đủ ở định dạng Markdown có tại https://qrflow.codes/llms-full.txt và tài liệu OpenAPI 3.1 tại https://qrflow.codes/api/v1/openapi.json.. Cả hai đều được tạo từ cùng nguồn với trang này.

Dành cho mọi người: phần này giúp chúng tôi bảo đảm trợ lý mà bạn đang làm việc cùng đưa ra phiên bản an toàn của mọi câu trả lời. Đây cũng là một bản tóm tắt hữu ích.

Bạn cần gói nào

Khóa API là tính năng duy nhất chỉ dành cho Business. Mọi thao tác trợ lý thực hiện qua máy chủ MCP và mọi thao tác ứng dụng bên thứ ba thực hiện qua OAuth đều hoạt động trên mọi gói và tuân theo các tính năng của gói đó. Xem giá đầy đủ và chính sách sử dụng hợp lý tại: /pricing.

FreePremium $4Business $29
Khóa API (REST từ mã của bạn)KhôngKhôngCó, tối đa 10 khóa
Máy chủ MCP (Claude, ChatGPT, Cursor, Claude Code)Có, đăng nhậpCóCó, đăng nhập hoặc dùng khóa
OAuth cho ứng dụng của bạn (người dùng kết nối QRFLOW của họ)CóCóCó
Mã động (thay đổi đích đến sau khi in)Một mãMọi mãMọi mã
Miền liên kết riêngKhông1 miền5 miền, chọn cho từng mã
Tên liên kết (go.brand.com/menu)KhôngCóCó
Phân tích lượt quétKhôngCóCó
WebhookKhôngKhôngCó, tối đa 10
Tạo hàng loạtKhông500/tháng, 500 mỗi yêu cầu10.000/tháng, 2.000 mỗi yêu cầu
Mã đã lưu (sử dụng hợp lý)Một vài mã1.00025.000
Thành viên nhóm115
Giá$0$4/tháng$29/tháng

Mười hai từ làm nên tất cả

Khái niệm

Chỉ cần đọc một lần là bạn sẽ hiểu mọi endpoint bên dưới.

Static code

Nội dung nằm bên trong hình ảnh. Mã Wi-Fi, danh thiếp liên hệ (vCard) và văn bản thuần luôn là mã tĩnh; trên gói Free, mọi mã đều là mã tĩnh. Mã tĩnh không cần máy chủ, không bao giờ hết hạn, và không thể thay đổi hoặc đếm lượt quét.

Dynamic code

Hình ảnh chứa một liên kết ngắn mà QRFLOW chuyển hướng. Mã url, phone, email, sms và location là mã động trên gói Premium và Business. Bạn có thể đổi đích đến, tạm dừng, đặt thời hạn, đổi tên và đếm lượt quét mà không cần động đến bản in.

short_url

Chuỗi chính xác được mã hóa trong mã động và là nội dung cần in. Chuỗi này là https://qrflow.codes/q/<short_code> cho đến khi bạn kết nối miền; sau đó là https://<your domain>/<slug or short_code>.. Mọi đối tượng Code đều chứa chuỗi này.

short_code

Bảy ký tự ngẫu nhiên, duy nhất cho mỗi mã, được gán khi tạo và không bao giờ thay đổi. Đây là đường dẫn dự phòng khi mã không có tên liên kết.

slug (link name)

Đường dẫn dễ đọc trên miền riêng của bạn: go.example.com/menu. Dài từ 3 đến 40 ký tự chữ thường, chữ số và dấu gạch ngang; duy nhất trong tài khoản của bạn và chỉ dùng được khi đã kết nối miền. Hãy đặt đường dẫn trước khi in: thay đổi đường dẫn sẽ làm thay đổi liên kết trên bản in.

Link domain

Tên máy chủ bạn sở hữu (go.example.com), được trỏ đến QRFLOW bằng CNAME và xác minh trên trang Account. Gói Premium có một miền; gói Business có năm miền và có thể chọn miền cho từng mã bằng domain_id. Miền đang hoạt động lâu đời nhất là miền mặc định.

Kind, type and subtype

type là định dạng mã hóa: url, text, wifi, vcard, email, phone, sms, location. kind là tên thân thiện hơn cho loại nội dung người dùng muốn (instagram, googlereview, whatsapp, pdf, menu, appstore,...). Hầu hết kind là mã url có destination_data.subtype được thiết lập. GET /catalog liệt kê mọi kind cùng các trường tương ứng; trường kind trên Code cho biết đó là loại nào.

destination_data

Các trường dành cho từng type, dưới dạng chuỗi: { url } cho trang web, { ssid, password, encryption } cho Wi-Fi, { placeId } cho bài đánh giá Google, { handle } cho Instagram. Với mã động, bạn có thể thay thế các trường này bất cứ lúc nào.

Scans

Mỗi lượt chuyển hướng ghi nhận loại thiết bị, quốc gia, thành phố, trang giới thiệu, trình duyệt, hệ điều hành và ngôn ngữ từ chính yêu cầu, đồng thời tạo một mã băm hằng ngày một chiều để đếm khách truy cập duy nhất. Không đặt cookie và không lưu địa chỉ IP. scans trên Code là tổng số lượt quét trong suốt thời gian hoạt động; GET /codes/:id/scans phân tích chi tiết số liệu này.

Source

Mỗi mã ghi nhớ nguồn tạo ra nó: dashboard, api:<key name>, mcp, canva, app:<connected app> (ví dụ app:Google Sheets) hoặc bulk; nếu được tạo qua yêu cầu hàng loạt thì có tiền tố bulk:. Thông tin này hiển thị trên bảng điều khiển và trong payload webhook, giúp bạn phân biệt mã do tích hợp của mình tạo với mã được tạo thủ công.

Workspace

Chủ tài khoản Business có thể mời tối đa bốn thành viên nhóm. Khóa và webhook thuộc tài khoản của chủ sở hữu; mọi mã do bất kỳ ai trong không gian làm việc tạo ra đều hiển thị với cả nhóm.

Năm phút

Bắt đầu nhanh

Lấy khóa

  1. Trên gói Business, mở Account › API keys.
  2. Đặt tên theo mục đích sử dụng ("Shop backend", "Reporting") và chọn phạm vi quyền. Không thể thay đổi phạm vi quyền sau này; hãy tạo khóa mới nếu cần thêm quyền.
  3. Sao chép khóa một lần. Khóa có dạng qrf_live_…. Đặt khóa vào biến môi trường có tên QRFLOW_KEY.
  4. Gửi khóa dưới dạng Authorization: Bearer $QRFLOW_KEY trong mọi yêu cầu. Đó là toàn bộ quy trình xác thực.

Khóa dành cho máy chủ. Không bao giờ đưa khóa vào trang web, ứng dụng di động hoặc bảng tính dùng chung; hãy thu hồi và cấp lại nếu khóa bị lộ.

Cùng năm bước đó trong curl, TypeScript và Python. Mỗi ví dụ tạo một mã động, tải hình ảnh xuống, thay đổi đích đến và đọc số liệu lượt quét.

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

Xác thực

Khóa API (Business)

Mỗi tài khoản có tối đa 10 khóa, mỗi khóa được phép gửi 600 yêu cầu mỗi phút; khóa được lưu dưới dạng băm và chỉ hiển thị một lần. Mỗi khóa có các phạm vi quyền được chọn khi tạo:

Phạm viQuyền
profileGET /me: gói dịch vụ, tính năng, giới hạn. Mọi khóa đều có quyền này.
codes:readLiệt kê và đọc mã, tải hình ảnh xuống.
codes:writeTạo, thay đổi, chuyển thành mã động, xóa và tạo hàng loạt.
analytics:readGET /codes/:id/scans.
domains:readGET /domains (cần thiết để sử dụng domain_id hợp lý).
codes:read / codes:writeCũng áp dụng cho sản phẩm GS1: các endpoint /products dùng chung phạm vi quyền của mã, vì vậy khóa quản lý mã cũng quản lý mã bao bì.
webhooks:manageLiệt kê, tạo, kiểm tra và xóa webhook.

OAuth 2.0 (mọi gói, dành cho ứng dụng và trợ lý)

Khi mã cần thuộc về tài khoản của người dùng của bạn thay vì tài khoản của bạn, hoặc khi ứng dụng khách là trợ lý trò chuyện, hãy dùng OAuth. Ứng dụng khách tự đăng ký; bắt buộc dùng PKCE S256 cho ứng dụng khách công khai; có thể liên kết mã thông báo với máy chủ MCP bằng resource=. Hướng dẫn OAuth trình bày chi tiết quy trình.

EndpointURLGhi chú
Authorizationhttps://qrflow.codes/oauth/authorizeGửi người dùng đến đây; họ đăng nhập và nhấn Allow.
Tokenhttps://qrflow.codes/api/oauth/tokenCác grant authorization_code và refresh_token. Access token có hiệu lực 1 giờ, refresh token có hiệu lực 90 ngày.
Revokehttps://qrflow.codes/api/oauth/revokeRFC 7009. Người dùng cũng có thể ngắt kết nối tại Account › Connected apps.
Register a clienthttps://qrflow.codes/api/oauth/registerĐăng ký động theo RFC 7591, không cần tài khoản. Ứng dụng khách công khai nhận dyn_client_id và phải dùng PKCE S256.
Discoveryhttps://qrflow.codes/.well-known/oauth-authorization-serverRFC 8414. Tài liệu tài nguyên MCP có tại /.well-known/oauth-protected-resource.

Access token có hiệu lực 1 giờ, refresh token có hiệu lực 90 ngày. Người dùng có thể xem các ứng dụng đã kết nối tại Account › Connected apps và ngắt kết nối bất cứ lúc nào. Mã thông báo được cấp cho https://qrflow.codes/mcp sẽ bị từ chối tại /api/v1, và ngược lại.

Những điều mọi người thực sự muốn làm

Công thức xây dựng

Mỗi công thức đều hoàn chỉnh và được sao chép trực tiếp từ mã đang hoạt động. Chọn công thức phù hợp với ngăn xếp công nghệ của bạn; cấu trúc luôn giống nhau: gọi API phía máy chủ bằng khóa, lưu id và short_url, rồi hiển thị hình ảnh.

Next.js: một route tạo mã và một route hiển thị mã

Khi nào dùng: Bạn có ứng dụng Next.js (App Router) và muốn có nút tạo mã QR cùng một trang hiển thị mã đó.

  1. Đặt khóa trong .env.local dưới tên QRFLOW_KEY. Không bao giờ thêm tiền tố NEXT_PUBLIC_.
  2. Thêm một POST route handler để tạo mã và trả về id cùng short_url.
  3. Thêm một GET route để proxy hình ảnh, nhờ đó trình duyệt không bao giờ thấy khóa.
  4. Lưu id và short_url vào bản ghi riêng của bạn (đơn hàng, bàn, sản phẩm, sự kiện).
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 hoạt động tương tự: gọi fetch với khóa bên trong action.
  • Với Pages Router, đặt cùng đoạn mã trong pages/api/qr.ts với req/res.

Hiển thị QR mà không qua proxy: tự render short_url

Khi nào: Bạn muốn hình ảnh xuất hiện ngay trong trình duyệt và không cần khung hoặc logo của QRFLOW.

Dùng thư viện QR nào cũng được, vì mã chính là liên kết rút gọn

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.
  • Đây là cách nhanh nhất để xem trước. Để in, hãy tải xuống /codes/:id/image.svg: tệp này chứa màu sắc, khung, chú thích và logo đã lưu, đồng thời là ảnh vector.
  • Nếu sau này bạn thay đổi slug hoặc domain_id, short_url sẽ thay đổi; hãy render lại.

Express hoặc bất kỳ máy chủ Node nào

Khi nào: Một backend Node thuần.

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

Khi nào: Môi trường chỉ hỗ trợ fetch, không có các mô-đun tích hợp sẵn của 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_...
  • Gói npm qrflow\ chỉ dùng fetch và WebCrypto, nên chạy được trên tất cả các môi trường này mà không cần chỉnh sửa.

Python: FastAPI, Flask, Django, một tập lệnh

Khi nào: Backend của bạn dùng 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")

Một mã QR cho mỗi đơn hàng, bàn, sản phẩm, vé hoặc sự kiện

Khi nào: Mỗi hàng trong một bảng của bạn cần có mã riêng, được tạo tự động.

  1. Thêm hai cột vào bảng: qrflow_code_id (uuid) và qr_short_url (text).
  2. Khi tạo một hàng, gửi POST /codes với URL công khai của hàng đó và nhãn mô tả hàng ("Order 10432", "Table 7"). Lưu id và short_url.
  3. Khi trang của hàng được chuyển đi (sang miền mới, đường dẫn mới), PATCH destination_data. Các mã đã in vẫn hoạt động.
  4. Khi ngừng sử dụng hàng đó, PATCH { paused: true } nếu đã in mã; chỉ DELETE nếu chưa in.
  5. Cần tạo hàng nghìn mã cùng lúc (mỗi bàn một thực đơn cho 300 nhà hàng)? Dùng POST /codes/bulk theo từng lô và ghép các mã trả về với hàng tương ứng bằng nhãn hoặc thứ tự.
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 });
  • Mức sử dụng hợp lý là 25,000 mã đã lưu trên gói Business; API sẽ dừng ở mức gấp đôi con số đó. Nếu bạn cần một mã cho mỗi biên lai mãi mãi, hãy liên hệ với chúng tôi trước: hello@qrflow.codes.

Thay đổi đích đến của mã đã in

Khi nào: Chiến dịch kết thúc, trang được chuyển đi, PDF được thay thế hoặc mùa thay đổi.

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" } }'

Tạm dừng hoặc đặt ngày kết thúc

# 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" }'
  • Chỉ mã động mới có thể đổi đích đến; mọi mã tĩnh đều trả về 400 not_dynamic. Mã Wi-Fi, vCard và văn bản thuần chứa nội dung ngay trong mẫu mã nên không bao giờ có thể là mã động; vì vậy, POST /codes/:id/dynamic từ chối chúng với lỗi 400 not_dynamic_capable. Với mã url, phone, email, sms và location, gói Free biến mã đầu tiên thành mã động và các mã còn lại thành mã tĩnh; mọi mã đều là mã động trên gói trả phí. POST /codes/:id/dynamic chuyển mã tĩnh thành mã động khi tài khoản vẫn còn hạn mức. Sau đó, hãy render và in lại vì hình ảnh sẽ thay đổi.
  • Máy quét sẽ thấy đích đến mới ở lần quét tiếp theo. Không cần chờ bộ nhớ đệm hết hạn.

In mã trên miền của riêng bạn

Khi nào: Bạn muốn mã chứa go.example.com/menu thay vì qrflow.codes/q/x7k2p9a.

  1. Trên trang Account, trong mục Your own link domain, thêm go.example.com và tạo bản ghi CNAME mà trang hiển thị tại nhà cung cấp DNS của bạn. Quá trình xác minh thường hoàn tất trong vài phút.
  2. Từ đó trở đi, short_url của mọi mã động mới sẽ dùng miền đó. Các mã hiện có cũng được chuyển đổi: hình ảnh của chúng đã mã hóa qrflow.codes/q/..., địa chỉ này vẫn tiếp tục chuyển hướng nên không ảnh hưởng đến mã đã in.
  3. Đặt tên dễ đọc cho liên kết bằng slug: PATCH { "slug": "menu" } sẽ tạo go.example.com/menu. Hãy làm việc này trước khi in.
  4. Với gói Business có nhiều miền, GET /domains liệt kê các miền cùng id; truyền domain_id trong POST hoặc PATCH để chọn miền cho từng mã.

Đặt tên cho liên kết và chọn miền

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

Biểu đồ lượt quét trong trang quản trị của bạn

Khi nào: Bạn muốn xem lượt quét theo ngày, quốc gia hoặc thiết bị bên cạnh số liệu của riêng mình.

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
  • Mỗi yêu cầu bao gồm tối đa 92 ngày; hãy lặp lại yêu cầu nếu cần khoảng thời gian dài hơn. Ngày giờ tính theo UTC.
  • Để xem số liệu trực tiếp mà không cần thăm dò liên tục, hãy đăng ký webhook cho sự kiện quét: bạn sẽ nhận được thông tin chi tiết của mọi lượt quét theo từng đợt, cách nhau vài phút.

Nhận webhook trong Next.js và xác minh chúng

Khi nào: Bạn muốn biết khi mã được quét hoặc thay đổi, lưu vào cơ sở dữ liệu của riêng mình gần như theo thời gian thực.

  1. Tạo webhook trong Account › Webhooks hoặc bằng POST /webhooks. Sao chép secret (whsec_...) một lần vào QRFLOW_WEBHOOK_SECRET.
  2. Đọc nội dung thô dưới dạng văn bản trước khi phân tích cú pháp; chữ ký được tính trên chính xác các byte đó.
  3. Xác minh, rồi xử lý theo event. Phản hồi 2xx nhanh; thực hiện tác vụ chậm sau khi phản hồi hoặc trong hàng đợi.
  4. Nhấn Test trên webhook để nhận ping có chữ ký và xác nhận cấu hình hoạt động.
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 });
}
  • Khi phát triển cục bộ, hãy mở máy chủ dev của bạn qua một tunnel (cloudflared tunnel --url http://localhost:3000, hoặc ngrok) và dùng URL https đó cho webhook trong quá trình xây dựng.
  • Gói npm sẽ xử lý việc này cho bạn: import { parseWebhook } from "qrflow"\ xác minh và phân tích cú pháp chỉ bằng một lệnh gọi (dùng WebCrypto nên cũng chạy được trên Workers và Deno). Thư viện Python có sẵn verify_webhook.

Nhận webhook trong Python

Khi nào: Flask, FastAPI hoặc Django nhận cùng các sự kiện đó.

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

Tạo hàng nghìn mã từ CSV

Khi nào: Một mã cho mỗi SKU, chỗ ngồi, thẻ tài sản hoặc thư quảng cáo.

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");
}
  • Tạo hàng loạt chỉ hỗ trợ mã url động, tất cả dùng cùng màu sắc. Mã được trả về theo thứ tự bạn gửi, trừ các hàng bị từ chối; nếu không chắc, hãy ghép theo nhãn.
  • Webhook gửi một sự kiện code.created cho mỗi yêu cầu tạo hàng loạt, với codes[] thay vì một sự kiện cho mỗi mã.

Cho phép người dùng kết nối tài khoản QRFLOW của riêng họ (OAuth)

Khi nào: Bạn đang xây dựng sản phẩm cho người khác và muốn mã được tạo trong tài khoản QRFLOW của họ, không phải của bạn.

  1. Đăng ký ứng dụng khách một lần: POST https://qrflow.codes/api/oauth/register với client_name và redirect_uris. Bạn sẽ nhận được client_id (và client_secret đối với ứng dụng khách bảo mật).
  2. Chuyển người dùng đến /oauth/authorize với response_type=code, client_id, redirect_uri, scope, state và PKCE (code_challenge, code_challenge_method=S256).
  3. Đổi mã tại /api/oauth/token. Lưu refresh token; access token có hiệu lực trong một giờ.
  4. Gọi /api/v1 với Authorization: Bearer <access_token>. Mọi thứ hoạt động giống hệt như khi dùng khóa, theo gói của người dùng.
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
  • Các scope giống với sáu scope của khóa API. Chỉ yêu cầu những quyền tối thiểu cần thiết; màn hình chấp thuận sẽ liệt kê chúng.
  • Nếu ứng dụng của bạn là trợ lý trò chuyện hoặc agent, hãy thêm resource=https://qrflow.codes/mcp vào yêu cầu authorize và kết nối với máy chủ MCP; token sẽ được ràng buộc với máy chủ đó.

Zapier, Make, n8n: hoàn toàn không cần viết mã

Khi nào: Bạn muốn lượt quét hoặc mã mới được gửi vào bảng tính, kênh Slack hoặc CRM.

  1. Tạo trình kích hoạt catch-hook (Zapier: Webhooks by Zapier › Catch Hook; Make: Custom webhook; n8n: nút Webhook) và sao chép URL https của nó.
  2. Trong Account › Webhooks, thêm URL đó và chọn các sự kiện. Nhấn Test; ping sẽ xuất hiện trong công cụ và cho biết cấu trúc payload.
  3. Ánh xạ data.scans[] (đối với scan) hoặc data.code (đối với code.*) vào bảng tính, tin nhắn hoặc bản ghi.
  4. Để tạo mã từ các công cụ đó, dùng mô-đun HTTP của chúng để gửi POST /codes cùng header Authorization. Lưu khóa trong kho thông tin xác thực của công cụ.
  • Zapier hiện có ứng dụng QRFLOW.codes: các bước Create QR Code, Update QR Code và Find, cùng trình kích hoạt New Scan tức thì, không cần cấu hình webhook hoặc khóa API. Xem QRFLOW với Zapier. Các bước bên dưới dành cho Make, n8n và các công cụ khác.
  • Những công cụ này không thể xác minh chữ ký. URL chúng cung cấp khó đoán, đó là biện pháp bảo vệ bạn có; đừng đăng URL ở bất kỳ đâu.
  • Nếu danh sách đã có trong Google Sheets, có thể bạn không cần webhook: tiện ích bổ sung QRFLOW for Google Sheets tạo mã cho từng hàng và ghi liên kết rút gọn cùng số lượt quét trở lại trang tính, trên gói Premium, không cần khóa API. Xem tiện ích bổ sung Google Sheets.

Lập trình bằng AI

Prompt để dán

Trợ lý lập trình sẽ xây dựng đúng thứ bạn cần nếu được cung cấp các quy tắc ngay từ đầu. Các prompt này bao gồm những quy tắc đó. Dán một prompt, điền phần trong ngoặc vuông, rồi trợ lý sẽ đọc tài liệu tham khảo Markdown trước khi viết dòng mã đầu tiên.

Thêm mã QR vào ứng dụng của tôi

Claude, ChatGPT, Cursor, Codex, Windsurf, Copilot Chat: dán vào cuộc trò chuyện

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"].

Hướng dẫn repo của bạn về QRFLOW

Thêm vào CLAUDE.md, AGENTS.md,.cursorrules hoặc.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.

Trong Lovable, Bolt, v0, Replit và các trình tạo ứng dụng khác

Các trình tạo ưu tiên giao diện người dùng, có cung cấp backend (Supabase, hàm serverless)

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 tùy chỉnh để quản lý mã của tôi

ChatGPT › Create a 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).

Những điều cần nói sau khi kết nối

Claude, ChatGPT, Claude Code khi đã kết nối với máy chủ QRFLOW MCP

"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."

Máy chủ MCP

Sử dụng với Claude, ChatGPT, Cursor và Claude Code

QRFLOW là máy chủ MCP tại https://qrflow.codes/mcp. Kết nối một lần, đăng nhập, rồi yêu cầu những việc như "tạo mã QR cho trang thực đơn mùa thu của chúng ta, đặt tên là menu trên miền của tôi", "chuyển mã trên áp phích ở sảnh sang trang mới" hoặc "tuần trước tờ rơi có bao nhiêu lượt quét, theo quốc gia?". Trợ lý có cùng các công cụ mà API này cung cấp, theo cùng quy tắc, và mã sẽ xuất hiện trong trang tổng quan của bạn với mcp là nguồn.

Không phải nhà phát triển? Phiên bản diễn giải bằng ngôn ngữ thông thường, kèm hướng dẫn chính xác cho từng trợ lý, có tại Tạo mã QR bằng trợ lý AI của bạn.

Được Glama chấm điểm độc lập và kiểm tra tình trạng hoạt động mỗi giờ; đồng thời được liệt kê trong thư mục awesome-remote-mcp-servers và MCP Registry chính thức với tên codes.qrflow/qrflow.

Kết nối

Customize › Connectors › Add custom connector › dán địa chỉ, hoặc nhấn Connect trong danh sách thư mục của QRFLOW. Claude sẽ mở trang đăng nhập QRFLOW; nhấn Allow. Dùng được trên mọi gói.

https://qrflow.codes/mcp

Settings › Security and login › bật Developer mode, sau đó Settings › Plugins › + › dán địa chỉ; đăng nhập khi được yêu cầu. Dành cho Plus, Pro, Team, Enterprise và Edu.

https://qrflow.codes/mcp

Chạy một lệnh, sau đó dùng /mcp để đăng nhập. Thêm khóa Business làm header để bỏ qua bước đăng nhập.

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, mọi MCP client

Thêm máy chủ HTTP tại URL. Đăng nhập OAuth diễn ra trong trình duyệt; hoặc truyền header Authorization cùng khóa.

{
  "mcpServers": {
    "qrflow": { "type": "http", "url": "https://qrflow.codes/mcp" }
  }
}

Agent của riêng bạn (Anthropic hoặc OpenAI SDK)

Trỏ MCP connector hoặc tool đến URL và dùng khóa Business làm bearer; không cần quy trình đăng nhập qua trình duyệt.

// Anthropic Messages API, MCP connector
mcp_servers: [{ type: "url", url: "https://qrflow.codes/mcp", name: "qrflow", authorization_token: process.env.QRFLOW_KEY }]

Trợ lý có thể làm gì

Công cụChức năngScope
list_code_kindsMọi loại mã cùng các trường và gói cần thiết. Trợ lý gọi công cụ này trước khi tạo loại mã ít phổ biến.profile
list_domainsCác miền liên kết của bạn, miền mặc định và id của chúng.domains:read
get_qr_imageẢnh PNG để trợ lý hiển thị hoặc lưu, cùng URL SVG để in.codes:read
get_accountGói, tính năng và giới hạn của tài khoản.profile

Cách bảo mật hoạt động

  • Trợ lý chỉ giữ token cho tài khoản của bạn, được cấp sau khi bạn nhấn Allow trên trang QRFLOW. Bạn có thể ngắt kết nối bất cứ lúc nào trong Account › Connected apps.
  • Token được ràng buộc với máy chủ MCP; không thể phát lại để gọi REST API.
  • Mọi thao tác ghi đều qua cùng quy trình xác thực như trên trang tổng quan: đích đến trong danh sách cho phép, kiểm tra gói và giới hạn sử dụng hợp lý.
  • Các công cụ có tính phá hủy được mô tả cẩn thận: delete_qr_code hướng dẫn mô hình ưu tiên tạm dừng nếu mã đã được in.
  • Tài liệu khám phá có tại /.well-known/oauth-authorization-server và /.well-known/oauth-protected-resource; đăng ký theo RFC 7591; chỉ hỗ trợ PKCE S256.

SDK và đặc tả OpenAPI

  • TypeScript / JavaScript: npm install qrflow (npm). Không có dependency, hỗ trợ ESM và CommonJS, đầy đủ kiểu dữ liệu; chạy trên Node 18+, Bun, Deno và Workers. Tự động thử lại khi gặp 429 và cung cấp verifyWebhook / parseWebhook.
  • Python 3.9+, chỉ dùng thư viện chuẩn: qrflow.py.
  • OpenAPI 3.1: /api/v1/openapi.json. Nhập vào Postman hoặc Insomnia, tạo client bằng bất kỳ ngôn ngữ nào hoặc đính kèm vào ChatGPT Action.
  • Cả hai client đều ném lỗi có kiểu (QRFlowError với status, code, message, retryAfter) và cung cấp trình xác minh webhook. Mã nguồn TypeScript một tệp vẫn có tại /sdk/qrflow.ts nếu bạn muốn đưa mã này vào dự án của mình.
TypeScriptPythonLệnh gọi
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)Địa chỉ hình ảnh (tải bằng khóa)
verifyWebhook(raw, header, secret)verify_webhook(raw, header, secret)Kiểm tra chữ ký của các lần gửi

Tham khảo endpoint

URL cơ sở https://qrflow.codes/api/v1. Nội dung và phản hồi là JSON. Ngày giờ theo ISO 8601, múi giờ UTC. Với PATCH, chỉ gửi các trường cần thay đổi.

GETprofile

Gói, cờ tính năng và giới hạn áp dụng cho tài khoản này, cùng với các phạm vi của khóa.

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

Các kiểu gốc (url, wifi, vcard, email, phone, sms, text, location) và khoảng 50 kiểu con (Instagram, Google review, Wi-Fi, cửa hàng ứng dụng…), mỗi kiểu có các trường cần thiết và gói yêu cầu. Không cần khóa.

curl https://qrflow.codes/api/v1/catalog

GETcodes:read

Mới nhất trước.?limit= tối đa 100,?q= tìm kiếm nhãn.

curl "https://qrflow.codes/api/v1/codes?limit=20&q=menu" \
  -H "Authorization: Bearer $QRFLOW_KEY"

POSTcodes:write

Áp dụng các quy tắc giống như khi lưu trên trang web: mã url, phone, email, sms và location là mã động trên các gói trả phí; Wi-Fi, vCard và text chứa nội dung trong mẫu. Đặt id kiểu con vào destination_data.subtype để tạo, chẳng hạn, mã Google review. domain_id tùy chọn sẽ chọn miền liên kết mà mã sử dụng (GET /domains liệt kê các miền đó).

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

Mã cùng số lượt quét, liên kết ngắn và địa chỉ hình ảnh.

curl https://qrflow.codes/api/v1/codes/$ID \
  -H "Authorization: Bearer $QRFLOW_KEY"

PATCHcodes:write

Có thể cập nhật bất kỳ trường nào sau đây: destination_data (chỉ mã động; bản in vẫn hợp lệ), label, paused, expires_at (ISO hoặc null), slug (tên liên kết trên miền của bạn), domain_id (miền liên kết mà mã này sử dụng; null = miền mặc định của tài khoản), fg_color, bg_color, frame_style, frame_caption, frame_caption2. Chỉ gửi các trường bạn muốn thay đổi.

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

Xóa vĩnh viễn, bao gồm cả lịch sử quét. Liên kết đã in của mã động sẽ ngừng hoạt động. Nếu bản in vẫn đang được sử dụng, hãy ưu tiên paused: true.

curl -X DELETE https://qrflow.codes/api/v1/codes/$ID \
  -H "Authorization: Bearer $QRFLOW_KEY"
204 No Content

POSTcodes:write

Mẫu đã in sẽ thay đổi (giờ đây mã hóa liên kết ngắn), vì vậy hãy kết xuất lại hình ảnh sau đó.

curl -X POST https://qrflow.codes/api/v1/codes/$ID/dynamic \
  -H "Authorization: Bearer $QRFLOW_KEY"

GETcodes:read

SVG sẵn sàng để in, có khung và màu sắc.?size= đặt chiều rộng lưới mô-đun theo px; dù sao thì tệp cũng có thể phóng to thu nhỏ mà không mất chất lượng.

curl https://qrflow.codes/api/v1/codes/$ID/image.svg \
  -H "Authorization: Bearer $QRFLOW_KEY" -o code.svg

GETanalytics:read

?from= và?to= (ngày ISO, tối đa 92 ngày, mặc định là 30 ngày gần nhất) và?group= day, device, country, city, browser, os hoặc referrer. Các số liệu giống như trên trang phân tích.

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

Tối đa 2.000 mã URL trong một lần gọi, tất cả đều là mã động. Tính vào cùng hạn mức hàng tháng cho thao tác hàng loạt như trang Bulk (10.000 trên gói Business). Các hàng không phải địa chỉ web sẽ được trả về trong rejected; các hàng còn lại sẽ được tạo.

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

Các mã dùng trên bao bì bán lẻ. Mỗi sản phẩm gồm một GTIN, địa chỉ in trên bao bì và các liên kết phía sau. Tìm kiếm tên và GTIN bằng?q=. Gói 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

Bắt buộc có gtin và name; brand và url là tùy chọn. Chữ số kiểm tra được xác minh trước khi ghi dữ liệu, và các dạng 8, 12, 13 và 14 chữ số đều được chuẩn hóa thành 14 chữ số. GTIN bạn đã có sẽ trả về lỗi 409 thay vì tạo sản phẩm thứ hai.

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

Một GTIN có thể dẫn đến nhiều địa điểm cùng lúc, mỗi địa điểm được gắn nhãn theo mục đích sử dụng. Điện thoại sẽ nhận liên kết mặc định; ứng dụng yêu cầu một loại cụ thể sẽ nhận liên kết thuộc loại đó. Có tính lũy đẳng: cùng link_type và batch sẽ thay thế liên kết đó thay vì thêm liên kết thứ hai, nên một tập lệnh chạy hằng đêm có thể chạy hai lần. Truyền batch để giới hạn liên kết vào một lô; nhờ đó có thể công bố thông tin thu hồi mà không ảnh hưởng đến phần còn lại của đợt sản xuất.

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

Số lượt quét theo từng GTIN trong?days= gần nhất (1 đến 365, mặc định 30), phân tích theo quốc gia, thiết bị, loại liên kết và lô. went_nowhere đếm các lượt quét không tìm thấy đích đến và giá trị này nên bằng 0.

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

Các miền đã kết nối, trạng thái của chúng và miền mà mã động sử dụng theo mặc định (default_base). Truyền id của một miền làm domain_id trên mã để mã đó sử dụng một miền khác.

curl https://qrflow.codes/api/v1/domains \
  -H "Authorization: Bearer $QRFLOW_KEY"

GETwebhooks:manage

Các webhook của bạn cùng với sự kiện, trạng thái gần nhất và số lần thất bại.

curl https://qrflow.codes/api/v1/webhooks \
  -H "Authorization: Bearer $QRFLOW_KEY"

POSTwebhooks:manage

url phải là https trên máy chủ công khai; events có thể là scan, code.created, code.updated, code.deleted. Bí mật ký được trả về một lần duy nhất.

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

Gửi ping đã ký ngay bây giờ và báo cáo phản hồi.

curl -X POST https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer $QRFLOW_KEY"

DELETEwebhooks:manage

Dừng mọi lần gửi, bao gồm cả các lần thử lại đang xếp hàng.

curl -X DELETE https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer $QRFLOW_KEY"
204 No Content

GETpublic

Các id khung và yêu cầu của từng khung (chú thích, dòng thứ hai), được nhóm như trong trình tùy chỉnh. Không cần khóa.

curl https://qrflow.codes/api/v1/frames

Đối tượng Code

Mọi endpoint thao tác với mã đều trả về cùng một cấu trúc. Bỏ qua các trường bạn chưa biết; các trường mới sẽ được bổ sung theo thời gian.

TrườngKiểuÝ nghĩa
iduuidId ổn định. Dùng id này trong mọi lệnh gọi khác.
labelstring | nullTên trong bảng điều khiển. Tối đa 120 ký tự. Có thể tìm kiếm bằng?q=.
kindstringId trong danh mục: url, wifi, instagram, googlereview,... kind_label là tên dễ đọc.
typestringKiểu mã hóa: url, text, wifi, vcard, email, phone, sms, location.
destination_dataobjectCác trường bạn đã gửi (cộng với subtype cho các kiểu). destination là phần tóm tắt một dòng của dữ liệu này.
dynamicbooleanTrue khi lượt quét đi qua QRFLOW và có thể thay đổi đích đến. dynamic_capable cho biết kiểu này có thể là mã động trên gói trả phí hay không.
short_codestringBảy ký tự, không bao giờ thay đổi.
short_urlstringNội dung cần in cho mã động. Bao gồm miền và slug của bạn nếu đã đặt.
domain_iduuid | nullMiền liên kết mà mã này sử dụng; null nghĩa là miền mặc định của tài khoản.
fg_color, bg_colorhexMàu mô-đun và màu nền.
has_logobooleanĐã thêm logo trong bảng điều khiển; image.svg sẽ bao gồm logo đó.
frame_style, frame_caption, frame_caption2string | nullId khung và chú thích, như trong trình tùy chỉnh.
scansintegerTổng số lượt quét trong suốt thời gian hoạt động.
created_at, updated_atISO 8601UTC.
manage_urlurlTrang của mã trong bảng điều khiển, dùng cho liên kết 'Open in QRFLOW'.
image_urlurlGET /codes/:id/image.svg. Cần có header Authorization; đây không phải URL hình ảnh công khai.
svg_download_url, png_download_urlurlCùng một SVG (khung, màu sắc, logo) và một PNG thông thường, thông qua các liên kết có chữ ký hoạt động trong 24 giờ mà không cần header: dành cho thẻ <img>, tập lệnh và trợ lý lưu tệp. download_expires_at cho biết thời điểm hết hạn; mỗi lần đọc mã sẽ trả về các liên kết mới.

Các cấu trúc khác: 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, cộng thêm secret một lần), Me (id, email, plan, paid, features, limits, auth, scopes) và Error (error, message). Tài liệu OpenAPI định kiểu cho mọi thuộc tính.

Business

Webhook

QRFLOW gọi URL https của bạn khi có sự kiện xảy ra. Tạo webhook trong Account › Webhooks hoặc bằng POST /webhooks; bạn chỉ nhận được bí mật ký một lần. Tối đa 10 webhook cho mỗi tài khoản.

Sự kiệnThời điểmdata
scanTheo lô: vài phút một lần, gồm tất cả lượt quét mới kể từ lần gửi trước, tối đa 500 lượt mỗi lần gọi.count, from, to, scans[] với code_id, label, short_code, slug, scanned_at, device, country, city, referrer, browser, os, language
code.createdNgay lập tức từ API và trợ lý; trong vòng vài phút từ bảng điều khiển. Một yêu cầu hàng loạt gửi một sự kiện với bulk: true và codes[].code, source
code.updatedThời điểm tương tự. Bao gồm đích đến, nhãn, trạng thái tạm dừng, thời hạn, tên liên kết, miền, màu sắc, khung và chuyển đổi sang mã động.code, changed[] (tên các trường đã thay đổi)
code.deletedThời điểm tương tự.code: { id, label, short_code, slug }
pingKhi bạn nhấn Test.webhook_id, message

Nội dung nhận được

Mọi payload đều là { id, event, created_at, data }. id ổn định qua các lần thử lại của cùng một lần gửi, vì vậy bạn có thể dùng nó để loại bỏ bản trùng lặp.

{
  "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ác minh chữ ký

X-QRFLOW-Signature: t=<unix seconds>,v1=<hex>. Tính HMAC-SHA256 trên ${t}.${rawBody} bằng bí mật của bạn rồi so sánh với v1 theo cách so sánh thời gian hằng; từ chối nếu t đã cũ hơn năm phút. Dùng các byte thô bạn nhận được, không bao giờ dùng đối tượng đã được tuần tự hóa lại. Có các trình nhận hoạt động cho Next.js và Python trong phần công thức; cả hai SDK đều có helper này.

Quy tắc gửi

  • Phản hồi bất kỳ mã 2xx nào trong vòng 8 giây. Thực hiện công việc sau khi phản hồi.
  • Mọi phản hồi khác sẽ được thử lại sau 1, 5, 15, 60, 240 và 720 phút.
  • Hai mươi lần thất bại liên tiếp sẽ tắt webhook và gửi email cho chủ tài khoản. Bật lại sau khi đã sửa trình nhận; các lần thử lại đang xếp hàng sẽ tiếp tục.
  • URL phải là https trên máy chủ công khai. localhost, các dải địa chỉ riêng và chính qrflow.codes đều bị từ chối. Hãy dùng tunnel trong quá trình phát triển.
  • Nhấn Test để nhận ping đã ký và xem trạng thái mà máy chủ của bạn phản hồi.

Lỗi

Mọi lỗi đều là { "error": "<code>", "message": "<what to do>" } với mã trạng thái bên dưới. Thông báo được viết cho người dùng; hãy hiển thị thông báo đó.

Trạng tháierrorÝ nghĩa

Triệu chứng, nguyên nhân, cách khắc phục

Khắc phục sự cố

401 invalid_token ở mọi lệnh gọi

Nguyên nhânHeader không đúng hoặc khóa chưa được kích hoạt.

Cách khắc phụcGửi chính xác Authorization: Bearer qrf_live_… (có dấu cách, không phải dấu hai chấm). Kiểm tra xem khóa có bị thu hồi trong Account › API keys hay không. Nếu bạn sao chép khóa từ cuộc trò chuyện hoặc tài liệu, hãy kiểm tra xem có dấu chấm ở cuối hoặc dấu ngoặc kép kiểu chữ hay không.

401 trên /api/v1 với token hoạt động trên máy chủ MCP

Nguyên nhânToken được cấp cho https://qrflow.codes/mcp chỉ dùng được với máy chủ đó.

Cách khắc phụcDùng khóa API cho REST hoặc chạy một luồng OAuth thứ hai không có resource= để lấy token cho REST API.

402 upgrade_required khi tạo khóa hoặc webhook

Nguyên nhânCả hai đều là tính năng của Business.

Cách khắc phụcNâng cấp tại /pricing hoặc dùng máy chủ MCP, hoạt động trên mọi gói thông qua đăng nhập.

402 trên POST /codes từ ứng dụng OAuth

Nguyên nhânGói của người dùng không bao gồm tính năng mà ứng dụng yêu cầu (mã động, miền).

Cách khắc phụcTrước tiên, đọc các tính năng trong GET /me rồi điều chỉnh: vẫn tạo mã (mã sẽ là mã tĩnh trên Free) hoặc cho người dùng biết gói cần có những gì.

403 insufficient_scope

Nguyên nhânPhạm vi được cố định khi tạo khóa. Sửa: Tạo khóa mới với các phạm vi bạn cần rồi thu hồi khóa cũ. Với OAuth, hãy yêu cầu phạm vi trong yêu cầu authorize.

400 not_dynamic khi tôi PATCH destination_data

Lý do: Mã này là mã tĩnh: loại Wi-Fi/vCard/văn bản, hoặc mã được tạo bằng gói Free sau khi đã dùng mã động miễn phí duy nhất.

Cách khắc phục: Với url/phone/email/sms/location, hãy POST /codes/:id/dynamic khi tài khoản còn hạn mức, sau đó tải xuống và in lại (hình ảnh sẽ thay đổi). Mã Wi-Fi, vCard và văn bản không bao giờ có thể là mã động; thay vào đó, hãy tạo mã url mở một trang.

400 no_domain khi tôi đặt slug

Lý do: Tên liên kết nằm trên miền của bạn.

Cách khắc phục: Trước tiên, hãy kết nối và xác minh miền trên trang Account. Trên qrflow.codes/q, đường dẫn luôn là short_code.

409 conflict trên slug

Lý do: Một mã khác của bạn đã dùng tên đó.

Cách khắc phục: Dùng GET /codes?q= để tìm mã đó hoặc chọn tên khác. Tên chỉ áp dụng trong tài khoản, không áp dụng trên toàn hệ thống.

Lỗi CORS trong bảng điều khiển trình duyệt

Lý do: API chỉ chấp nhận các lệnh gọi từ máy chủ đến máy chủ (và Canva). Đây là chủ ý: khóa đặt trong trang web sẽ bị lộ.

Cách khắc phục: Chuyển lệnh gọi vào route handler, server action, edge function hoặc backend, rồi gọi từ trang web.

Hình ảnh có dấu QRFLOW

Lý do: Mã được tạo bởi người chưa đăng nhập. Dấu này chỉ xuất hiện khi tải xuống ẩn danh.

Cách khắc phục: Bất kỳ tài khoản nào cũng xóa được dấu này, kể cả gói miễn phí. Hình ảnh của mã đã lưu không bao giờ có dấu này.

short_url vẫn hiển thị qrflow.codes/q/… sau khi tôi thêm miền

Lý do: Miền chưa được xác minh hoặc CNAME của miền bị sai.

Cách khắc phục: Kiểm tra trạng thái trên trang Account hoặc dùng GET /domains (trạng thái phải là verified). Các mã hiện có sẽ tự động chuyển sang miền đó khi miền được xác minh.

image_url trả về 401 trong thẻ <img>

Lý do: Cần có tiêu đề Authorization, nhưng <img> không thể gửi tiêu đề này.

Cách khắc phục: Dùng svg_download_url hoặc png_download_url từ cùng đối tượng Code: đây là các liên kết có chữ ký, hoạt động trong 24 giờ mà không cần tiêu đề. Nếu cần liên kết lâu dài, hãy chuyển tiếp image_url qua máy chủ của bạn (xem hướng dẫn Next.js) hoặc tự mã hóa short_url.

Tôi cần PNG, không phải SVG

Lý do: SVG có khung và logo; PNG là mã thuần.

Cách khắc phục: GET /codes/:id/image.png (bearer hoặc png_download_url có chữ ký) trả về PNG có kích thước từ 256 đến 2048 px. Để tạo PNG có khung, hãy chuyển đổi SVG bằng sharp hoặc resvg (sharp(svgBuffer).png().toBuffer()).

Trợ lý của tôi báo rằng điểm cuối hình ảnh từ chối yêu cầu rồi tự vẽ mã

Lý do: Trợ lý đã tải image_url, vốn cần bearer.

Cách khắc phục: Mỗi mã hiện có png_download_url và svg_download_url, còn get_qr_image trả về các liên kết này; trợ lý có thể dùng curl để tải chúng mà không cần đăng nhập. Mã được vẽ cục bộ và mã hóa cùng short_url vẫn hoạt động, vẫn ghi nhận lượt quét, nhưng không có khung và logo.

Webhook không bao giờ đến

Lý do: Quy tắc URL hoặc máy chủ nhận.

Cách khắc phục: URL phải dùng https trên máy chủ công khai (không dùng localhost, IP riêng hoặc qrflow.codes). Nhấn Test trên webhook: kết quả sẽ hiển thị trạng thái máy chủ của bạn phản hồi. Các sự kiện quét được gom theo lô và có thể mất khoảng năm phút; các sự kiện code.* từ bảng điều khiển cũng được xếp hàng trong vài phút, còn các thao tác ghi qua API và MCP được gửi ngay.

Chữ ký không bao giờ được xác minh

Lý do: Bạn đã ký phần nội dung được tuần tự hóa lại.

Cách khắc phục: Xác minh bằng chính xác các byte thô bạn nhận được, trước khi phân tích JSON. Trong Express, dùng express.raw({ type: 'application/json' }) trên route đó; trong Next.js App Router, dùng await req.text(); trong Flask, dùng request.get_data(). Sau đó tính HMAC-SHA256 của ${t}.${raw}\.

Webhook tự tắt

Lý do: Có hai mươi lần thất bại liên tiếp.

Cách khắc phục: Sửa máy chủ nhận, rồi bật lại webhook (Account › Webhooks hoặc xóa rồi tạo lại). Bạn đã được gửi email khi việc này xảy ra. Các lần thử lại đang chờ sẽ tiếp tục.

Webhook được gửi trùng lặp

Lý do: Phản hồi 2xx chậm (quá 8 giây) được tính là thất bại và sẽ được thử lại.

Cách khắc phục: Phản hồi trước, xử lý sau. Khử trùng lặp dựa trên id trong payload; id này không đổi qua các lần thử lại.

429 rate_limited khi nhập dữ liệu

Lý do: 600 yêu cầu mỗi phút cho mỗi khóa.

Cách khắc phục: Dùng POST /codes/bulk (2,000 mã trong một yêu cầu) thay vì POST từng mã, hoặc chờ số giây được chỉ định trong Retry-After.

Tôi đã xóa mã và áp phích đã in giờ hiển thị 'Code not found'

Lý do: Xóa là thao tác vĩnh viễn và làm liên kết ngừng hoạt động.

Cách khắc phục: Không thể hoàn tác. Lần sau, hãy dùng PATCH { paused: true }; mã tạm dừng sẽ hiển thị trang thân thiện và có thể được bật lại.

Khóa của tôi ngừng hoạt động sau khi tôi hạ cấp

Lý do: Khóa vẫn hoạt động trong 30 ngày sau khi rời gói Business, sau đó trả về 402.

Cách khắc phục: Đăng ký lại; không có gì bị xóa và các khóa cũ sẽ hoạt động trở lại.

Không tìm thấy vấn đề của bạn trong danh sách? Hãy liên hệ hello@qrflow.codes, kèm theo yêu cầu chính xác và lỗi JSON bạn nhận được. Tài khoản Business được ưu tiên hỗ trợ.

Giới hạn và sử dụng hợp lý

Giới hạn
Số yêu cầu mỗi phút, cho mỗi khóa600. Vượt quá giới hạn sẽ trả về 429 kèm Retry-After.
Số khóa mỗi tài khoản10
Số webhook mỗi tài khoản10
Số mã đã lưu (sử dụng hợp lý)1,000 với Premium, 25,000 với Business; API dừng ở mức gấp đôi giới hạn đó.
Bulk500/tháng (500 mỗi yêu cầu) với Premium; 10,000/tháng (2,000 mỗi yêu cầu) với Business.
Miền liên kết1 với Premium, 5 với Business
Lượt quétKhông giới hạn. Với Premium, email thông báo khi một mã đạt 100,000 lượt quét mỗi tháng; với Business là 1,000,000 lượt; không có lượt nào bị giới hạn.
Khoảng thời gian phân tích lượt quét92 ngày mỗi yêu cầu
Kích thước trang danh sách100 (?limit=)
Nhãn / chú thích / slug120 / 60 / 40 ký tự
Thời gian chờ và số lần thử lại của webhook8 giây; thử lại sau 1, 5, 15, 60, 240 và 720 phút; tắt sau 20 lần thất bại liên tiếp.
Sau khi rời gói BusinessKhóa và webhook vẫn hoạt động trong 30 ngày, sau đó trả về 402. Không có gì bị xóa.

Mức sử dụng hợp lý là cơ sở định giá gói. Không có gì bị giới hạn ở mức đó; API dừng ở mức gấp đôi và chúng tôi sẽ gửi email cho bạn trước. Nếu cần khối lượng cao hơn: hello@qrflow.codes.

Bảo mật cho bạn và những người quét mã

QRFLOW bảo vệ tài khoản của bạn như thế nào

  • Khóa chỉ hiển thị một lần và được lưu dưới dạng hàm băm SHA-256. Không ai ở QRFLOW có thể xem lại khóa; nếu mất khóa, hãy tạo khóa mới.
  • Mỗi yêu cầu được giới hạn trong tài khoản sở hữu khóa đó. ID mã từ tài khoản khác sẽ trả về 404, không bao giờ làm lộ dữ liệu.
  • Phạm vi được cố định cho từng khóa, vì vậy khóa dành cho bảng điều khiển báo cáo không thể tạo hoặc xóa mã.
  • 600 yêu cầu mỗi phút cho mỗi khóa; vượt quá giới hạn sẽ trả về 429 rõ ràng, không làm chậm mọi người.
  • Đích đến được đưa vào danh sách cho phép: http, https, mailto, tel, sms, geo và một danh sách ngắn các lược đồ ứng dụng (whatsapp, tg, signal, spotify, app stores). javascript:, data: và file: bị từ chối ngay khi tạo, nên một tích hợp bị xâm phạm không thể biến mã của bạn thành công cụ tấn công.
  • URL webhook phải dùng https trên máy chủ công khai; QRFLOW không bao giờ gọi mạng riêng hoặc chính nó. Mỗi lần gửi đều có chữ ký và mỗi payload đều có id ổn định.
  • Ứng dụng OAuth đăng ký bằng PKCE S256 và token được ràng buộc với máy chủ đã cấp chúng; token dành cho máy chủ MCP không thể được phát lại trên REST API.
  • Bất kỳ ai cũng có thể thu hồi khóa hoặc ngắt kết nối ứng dụng trên trang Account; thay đổi có hiệu lực ngay lập tức.

Bạn cần làm gì ở phía mình

  • Dùng biến môi trường, không dùng mã nguồn. Nếu khóa xuất hiện trong lịch sử git, hãy thu hồi khóa đó.
  • Chỉ gọi từ phía máy chủ. API từ chối các nguồn trình duyệt, nhưng các điểm cuối của riêng bạn dùng để bọc API cũng cần xác thực; nếu không, bất kỳ ai cũng có thể tạo mã và tính phí vào tài khoản của bạn.
  • Cấp cho mỗi tích hợp một khóa riêng với các phạm vi cần thiết và đặt tên theo tích hợp đó. Khi thu hồi, bạn chỉ ảnh hưởng đến một tích hợp.
  • Xác minh chữ ký webhook và từ chối dấu thời gian cũ hơn năm phút.
  • Nếu dữ liệu người dùng được đưa vào nhãn hoặc đích đến, hãy nhớ QRFLOW lưu trữ chúng; nếu có thể, đừng đưa dữ liệu cá nhân vào nhãn.

Lượt quét ghi nhận những gì và không ghi nhận những gì

  • Mỗi lần chuyển hướng lưu loại thiết bị, quốc gia, thành phố, nguồn giới thiệu, trình duyệt, hệ điều hành và ngôn ngữ được suy ra từ yêu cầu, cùng với hàm băm một chiều của mã + ngày + IP + user agent để chủ sở hữu có thể đếm số khách truy cập duy nhất. Không thể đảo ngược hàm băm để tìm ra địa chỉ.
  • Không đặt cookie trên thiết bị của người quét và không lưu địa chỉ IP cùng với lượt quét. Bỏ qua bot đã biết và trình thu thập dữ liệu xem trước liên kết.
  • Xóa mã sẽ xóa các lượt quét của mã đó. Xóa tài khoản sẽ xóa mọi thứ.
  • Toàn văn: https://qrflow.codes/privacy và https://qrflow.codes/terms.

Phiên bản và tính ổn định

API được đánh phiên bản trong đường dẫn: /api/v1. Trong v1, chúng tôi bổ sung trường, điểm cuối, loại và sự kiện; không xóa hoặc đổi tên bất kỳ thứ gì, và mã của bạn nên bỏ qua các trường không xác định trong phản hồi.

Nếu có thay đổi buộc phải phá vỡ v1, thay đổi đó sẽ được phát hành dưới dạng /api/v2 và v1 tiếp tục hoạt động ít nhất mười hai tháng. Chủ sở hữu khóa sẽ được gửi email thông báo về các tính năng sắp ngừng hỗ trợ trước 90 ngày.

Máy chủ MCP tuân theo cùng quy tắc với các công cụ: chỉ bổ sung đối số và giữ nguyên tên của mọi công cụ.

Tài liệu OpenAPI tại /api/v1/openapi.json và tài liệu Markdown tại /llms-full.txt được tạo từ mã phục vụ API, nên mô tả chính xác những gì đang hoạt động hiện nay.

Câu hỏi thường gặp của nhà phát triển

Tôi có phải trả phí để dùng API QRFLOW không?

Khóa API đi kèm gói Business, giá $29 mỗi tháng, thanh toán theo tháng. Máy chủ MCP (Claude, ChatGPT, Cursor, Claude Code) và OAuth cho ứng dụng của riêng bạn hoạt động trên mọi gói thông qua đăng nhập; những gì chúng có thể tạo sẽ tuân theo gói của bạn. GET /catalog, GET /frames và /preview.svg không cần khóa.

Tôi có thể tạo mã QR miễn phí qua API không?

Không thể dùng khóa. Để tạo hình ảnh tĩnh đơn giản, công cụ tạo miễn phí tại qrflow.codes hoặc bất kỳ thư viện QR mã nguồn mở nào đều đáp ứng được. API dành cho mã động, miền riêng, phân tích, tạo hàng loạt và webhook — những tính năng có trong tài khoản trả phí.

Tôi có thể gọi API từ trình duyệt không?

Không. API từ chối các nguồn trình duyệt để khóa không bao giờ bị lộ trong trang web. Hãy gọi API từ route handler, server action, edge function hoặc backend, rồi gọi thành phần đó từ trang web.

Tôi nhận được những định dạng hình ảnh nào?

SVG có màu sắc, khung, chú thích và logo của bạn (GET /codes/:id/image.svg, kích thước danh nghĩa từ 256 đến 4096 px) và PNG thuần (GET /codes/:id/image.png, từ 256 đến 2048 px). Cả hai đều cần bearer hoặc svg_download_url / png_download_url có chữ ký mà mọi đối tượng Code đều có; các liên kết này hoạt động trong 24 giờ mà không cần tiêu đề. Công cụ MCP get_qr_image trả về PNG nội tuyến cùng cả hai liên kết.

Tôi có thể thay đổi mã QR sau khi in không?

Có, nếu đó là mã động (url, phone, email, sms, location trên gói trả phí). Dùng PATCH /codes/:id với destination_data mới; hình ảnh không thay đổi, nhưng lượt quét tiếp theo sẽ chuyển đến địa chỉ mới. Mã Wi-Fi, vCard và văn bản chứa nội dung ngay trong hình ảnh nên không thể thay đổi.

short_url khác đích đến như thế nào?

short_url là liên kết nằm trong hình ảnh (go.example.com/menu). Đích đến là nơi liên kết đó chuyển hướng đến (https://example.com/menu-fall). Bạn chỉ cần in short_url một lần và có thể thay đổi đích đến bao nhiêu lần tùy ý.

Mã có thể dùng miền riêng của tôi không?

Có. Premium kết nối được 1 miền, Business kết nối được 5 miền; bạn thêm CNAME rồi xác minh trên trang Account. Với Business, bạn chọn miền cho từng mã bằng domain_id. Tên liên kết (slug) tạo đường dẫn dễ đọc trên miền đó.

Lượt quét ghi nhận thông tin gì về người quét?

Loại thiết bị, quốc gia, thành phố, nguồn giới thiệu, trình duyệt, hệ điều hành và ngôn ngữ lấy từ yêu cầu, cùng với hàm băm hằng ngày một chiều để đếm khách truy cập duy nhất. Không có cookie và không lưu địa chỉ IP. Đủ để tạo biểu đồ, nhưng không đủ để nhận dạng bất kỳ ai. Chi tiết: https://qrflow.codes/privacy#scans

Có gói npm hoặc PyPI không?

npm: npm install qrflow\ (https://www.npmjs.com/package/qrflow), không có phần phụ thuộc, hỗ trợ ESM và CommonJS, có đầy đủ kiểu TypeScript, chạy trên Node 18+, Bun, Deno và Workers; gói này bao bọc mọi điểm cuối, thử lại khi gặp 429 và có verifyWebhook/parseWebhook. Python: ứng dụng khách một tệp tại https://qrflow.codes/sdk/qrflow.py (chỉ dùng thư viện chuẩn) có verify_webhook; gói PyPI sẽ ra mắt sau.

Có hoạt động với Claude, ChatGPT, Cursor và Claude Code không?

Có. QRFLOW là máy chủ MCP tại https://qrflow.codes/mcp. Thêm máy chủ này làm trình kết nối, đăng nhập một lần rồi yêu cầu bằng ngôn ngữ thông thường. Mười một công cụ hỗ trợ tạo, chỉnh sửa, tạm dừng, đặt tên, tạo hàng loạt, phân tích, hình ảnh và miền.

Người dùng của tôi có thể kết nối tài khoản QRFLOW của họ với ứng dụng của tôi không?

Có, với OAuth 2.0. Đăng ký một client tại /api/oauth/register (không cần tài khoản), chuyển người dùng đến /oauth/authorize bằng PKCE, rồi gọi API bằng token của họ. Mã sẽ được lưu trong tài khoản của họ theo gói dịch vụ.

Làm cách nào để kiểm thử webhook trên localhost?

Mở máy chủ phát triển của bạn qua một tunnel (cloudflared hoặc ngrok) và dùng địa chỉ https của tunnel làm URL webhook, sau đó nhấn Test trong Account › Webhooks để nhận một ping có chữ ký. URL webhook phải là https công khai; localhost và các địa chỉ riêng tư sẽ bị từ chối.

Điều gì xảy ra với tích hợp của tôi nếu tôi hủy Business?

Khóa và webhook tiếp tục hoạt động trong 30 ngày, sau đó trả về 402. Mã, lượt quét và tên miền vẫn nằm trong tài khoản. Đăng ký lại sẽ bật mọi thứ trở lại với cùng các khóa.

Làm cách nào để tạo mã Google review, Instagram, Wi-Fi hoặc PDF qua API?

GET /catalog liệt kê mọi loại cùng các trường tương ứng. Sau đó POST /codes với type và các trường của loại đó, thêm subtype cho các loại như sau: { 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 có thể tải logo lên mã không?

Chưa. Hãy thêm logo trong bảng điều khiển; image.svg sẽ bao gồm logo và has_logo cho biết logo có ở đó hay không. Có thể thiết lập màu sắc, khung và chú thích thông qua API.

API có ổn định không?

v1 chỉ bổ sung; không bao giờ xóa hoặc đổi tên. Thay đổi gây lỗi sẽ được phát hành dưới dạng v2, trong khi v1 tiếp tục hoạt động ít nhất mười hai tháng và có thông báo trước 90 ngày qua email.

Dành cho agent, công cụ và trợ lý đọc nội dung này

Có thể đọc bằng máy

Mọi nội dung trên trang này đều có phiên bản mà phần mềm có thể tải về. Tất cả được tạo từ mã phục vụ API, nên luôn được cập nhật.

URLNội dung
llms-full.txthttps://qrflow.codes/llms-full.txtToàn bộ tài liệu tham khảo này dưới dạng Markdown: khái niệm, mọi endpoint, mọi công cụ MCP, công thức, hướng dẫn khắc phục sự cố và FAQ. Được tạo từ cùng nguồn với trang này.
developers.mdhttps://qrflow.codes/developers.mdCùng tài liệu này, dành cho các công cụ tải a.md.
llms.txthttps://qrflow.codes/llms.txtChỉ mục trang web dành cho trợ lý, trỏ đến đây.
API trên một tranghttps://qrflow.codes/qr-code-apiAPI làm được gì, khi nào thư viện phía client là lựa chọn phù hợp hơn và chi phí ra sao. Bản tóm tắt của tài liệu tham khảo này, dành cho việc cân nhắc thay vì xây dựng.
openapi.jsonhttps://qrflow.codes/api/v1/openapi.jsonOpenAPI 3.1. Nhập vào Postman, Insomnia, trình tạo mã hoặc ChatGPT Action.
Máy chủ MCPhttps://qrflow.codes/mcpStreamable HTTP, OAuth với đăng ký động hoặc khóa Business làm bearer.
server.jsonhttps://qrflow.codes/.well-known/mcp/server.jsonTệp kê khai registry MCP.
Khám phá OAuthhttps://qrflow.codes/.well-known/oauth-authorization-serverMetadata RFC 8414; tài liệu protected-resource nằm ngay bên cạnh.
Gói npmhttps://www.npmjs.com/package/qrflownpm install qrflow. Client có kiểu dữ liệu, không phụ thuộc thư viện nào, xác minh webhook. Client Python trong một tệp tại https://qrflow.codes/sdk/qrflow.py.
GitHubhttps://github.com/nativecodeapps/qrflow-sdkClient, bản chụp OpenAPI và ví dụ có thể chạy cho webhook Next.js, Workers, Express, FastAPI và Flask. Hoan nghênh các issue và PR.

Câu hỏi, ý tưởng hoặc loại mã chúng tôi nên bổ sung: hello@qrflow.codes. Điều khoản: /terms. Quyền riêng tư: /privacy.