二维码 API 指南：用程序化方式生成和管理二维码（2026 年）

大多数二维码使用场景（几十张菜单码、名片码或者营销码），用二维码生成平台的后台界面就完全够用。点一下、粘贴 URL、下载图片，搞定。

当需求规模超出了“一个人坐在后台里点鼠标”能处理的程度时，二维码 API 才真正发挥价值：按客户的码、按订单的码、和其他系统的集成、和数据库联动的批量生成。如果做得好，二维码 API 让你能把码当作基础设施来用：由你自己的软件来生成、管理和追踪。

本指南讲清楚：什么时候二维码 API 值得投入工程力量、它们通常支持哪些操作、可以怎么写代码，以及如何把不同服务商的 API 拿来作横向比较。

30 秒速览版

二维码 API 在以下情况是值得的：

1. 你需要按客户、按订单程序化地生成码（活动票、会员卡、防伪序列号）。
2. 你要把二维码生成集成到一个更大的系统里（你的 CRM、库存管理系统、电商平台）。
3. 你要生成的量已经让后台操作变得痛苦，通常是每月几十张以上。
4. 你要按库存、时间或用户行为程序化地更新跳转目的地。

下面这些情况则属于杀鸡用牛刀：

1. 你只需要少量营销码。后台更快。
2. 码不会变，而且数量很少。本地静态生成工具就够了。
3. 你没有工程资源去集成、维护和监控 API。

常见的二维码 API 操作

大多数二维码 API 都暴露五到六个核心操作。具体的接口名称各家不同，但形状大同小异。

1. 生成一张新的二维码。

向服务商 POST 一个目的地 URL（以及可选的元数据）；拿回一个码 ID 和一张可下载的二维码图片 URL。

2. 修改一张已有动态码的目的地。

向该码的接口发起 PUT 或 PATCH，改变它的跳转目标。适合做库存驱动的目的地、按时段路由，或者 A/B 测试。

3. 获取某张码的数据分析。

GET 一张码的扫码量、时间序列、地理分布、设备占比。适合做后台集成或者报表。

4. 列出或搜索已有的码。

GET 你账户下码的分页列表，可按日期、标签或目的地筛选。适合做管理界面。

5. 删除或归档一张码。

DELETE 会彻底删除这张码（它会停止解析）。有些服务商提供“归档”作为更柔和的方式：不删除，但暂停。

6. 批量操作。

很多服务商都提供批量接口：一次创建 N 张码、一次更新所有匹配某个筛选条件的码、一次为多张码导出数据。这些操作有自己的速率限制和定价含义。

认证方式

二维码 API 通常使用以下三种认证模式之一：

请求头里的 API key。最简单的方式：每个请求都带上 Authorization Bearer token 头。容易实现；关键在于做好密钥轮换和吊销卫生。

OAuth 2.0。更复杂，但更适合多用户或合作伙伴集成。基于 token，有 scope 控制，有时效限制。

HMAC 签名请求。部分服务商在高安全性场景下使用。客户端用一个密钥和一个时间戳给每个请求签名，可以防止重放攻击。

大多数场景下，你会用到的就是 API key 模式。把 key 放在环境变量里，绝对不要提交到代码库，并且定期轮换。

代码示例

下面的示例使用一个通用的二维码 API 模式。请把 base URL 替换成你服务商的真实接口，字段名根据情况调整。

用 JavaScript（Node.js）生成一张码：

一个典型的 Node fetch 调用，POST 一段 JSON，里面包含目的地 URL、标签、码类型。响应里会有 code_id 和 image_url，你可以存下来后续引用。

用 Python 生成一张码：

Python 里等价的写法是用 requests 库 POST 同样的 JSON payload。API key 用环境变量，遇到非 2xx 响应时抛异常。

更新一张码的目的地：

向这张码的接口发起一个 PATCH 请求，带上新的目的地 URL，所有已经印出去的码现在都会跳转到新的目的地。

获取扫码数据：

向这张码的数据接口发一个 GET 请求，可以带上日期范围的查询参数，拿回扫码量和各种维度的拆分。

这些都是示意性的模式。具体的接口和请求/响应格式，请始终以服务商自己的文档为准。

常见的 API 使用场景

下面这些是真实世界里二维码 API 集成里反复出现的模式：

按订单或按客户的码。

电商：每个订单发货时都带一张专属二维码，指向该客户的专属落地页（再次下单、求评、物流追踪等）。在结账时由 API 生成，图片嵌进包装模板里。

按票或按参会者的活动码。

活动票务：每张票都有一张唯一的二维码，在入场时验证。同一个 API 后续可以发放退款/转让码，或者活动后的跟进码。

按产品的溯源码。

制造和快消行业：可变数据印刷给每个单品打上一张唯一码，关联到这批货的批次、原产地和溯源数据。部分法规（比如FSMA 204 和 FDA UDI）是强制要求的。

按门店或按地区的码。

连锁业务：API 给每个门店生成一张码，目的地设成该门店的页面或签到流程。门店开业、关闭或者信息变更时，通过 API 同步更新。

库存驱动的目的地。

零售：货架标签上的二维码指向商品的详情页，但当商品打折、缺货，或者被新型号替代时，目的地会变化。API 在库存事件触发时更新跳转目的地。

会员和奖励码。

酒店和零售：每个客户的会员卡上有一张唯一二维码，指向该客户的会员档案。API 在注册时发码，并随时间更新路由逻辑。

防伪码。

奢侈品：每件商品都有一张唯一码。API 追踪扫码模式：如果“同一张”码出现了从多个不同地点的扫码（对一张真正唯一的码来说这是不可能的），就标记为潜在的仿冒。

速率限制和批量操作

二维码 API 有速率限制：限制你每秒、每分钟或每小时可以发起多少次请求。

典型的速率限制：

• 免费/爱好者档：每分钟 60 次。
• 中档付费：每分钟 1,000-10,000 次。
• 企业级：按需自定义（通常每分钟 100,000 次以上，或者无限但有合理使用政策）。

批量生成有两种做法：

1. 顺序生成 + 速率限制处理。用循环逐个调用 API，捕获 429（Too Many Requests）响应并退避重试。简单，几千张以内基本都能跑。
2. 批量接口。很多服务商支持在一个请求里接受码的数组。在高量级下效率高得多。

对真正高量级（几百万张）的场景，一些服务商会提供异步批量生成：提交一个任务、轮询完成状态、下载结果 CSV。企业方案一般都有；有时低档也提供。

Webhook 还是轮询

二维码 API 通常支持两种接收扫码事件的方式：

轮询。你的应用定期调用数据接口，检查有没有新的扫码。实现简单，但有延迟，而且在没有新事件时也会浪费调用。

Webhook。每发生一次扫码，服务商会向你服务器上的某个 URL 发起 POST 请求（或者按你配置的节奏发）。实时、高效，但需要你的服务器暴露一个公开的接口，并且要校验入站请求。

对于实时场景（活动票务、欺诈检测、即时客户触达），Webhook 是必需的。对于定期报表，轮询就够了。

横向比较各家服务商的二维码 API

主流的二维码服务商基本都提供 API，但成熟度差距非常大。

要比较的维度：

• 文档质量。文档清楚、有示例的 API 能省下大量工程时间。试着读一遍文档，想象一下实现最简单的用例，你就知道它好不好用。
• 速率限制。把服务商的限额对照自己的预期量。
• 定价模式。按码计费、按请求计费、带配额的月度订阅，或者几种的组合。
• Webhook 支持。实时场景的必选项。
• 批量接口可用性。高量级集成时能省下大量时间。
• SDK 可用性。你常用语言的官方 SDK 可以大幅缩短接入时间。
• 码的长寿政策。和后台使用情况一样，如果你停付费，你的码会发生什么？

服务商情况（写作时）：

• Uniqode和qr-code-generator.com（Bitly Inc。）有成熟的、企业级的 API，功能覆盖广。价格也相应较高。
• QR Tiger在更亲民的价位上提供了一个扎实的 API。
• QR Cake在付费方案里提供 API 访问；文档和 SDK 可用性在持续改善。
• Bitly 的 QR API如果你已经在用 Bitly 做短链，集成起来确实很强。

承诺之前请先对照当下的文档和定价。API 会变。最佳二维码生成器那篇文章覆盖了更广的服务商版图。

安全注意事项

二维码 API 有几个特有的安全坑值得提醒一下：

1. API key 的存储。

绝对不要把 key 提交到代码库。请用环境变量、密钥管理工具（AWS Secrets Manager、HashiCorp Vault、Doppler），或者你平台自带的 secret 能力。员工离职或者 key 不小心泄露时，要轮换。

2. 目的地 URL 校验。

如果你应用的用户可以为二维码指定目的地 URL（比如多租户应用里客户自己创建码），请校验这些 URL。不要允许任意目的地，防止 open-redirect 攻击。

3. Webhook 签名校验。

如果你用 webhook，服务商一般会用一个 secret 给 payload 签名。每一个入站 webhook 都要校验签名。没有这一步，攻击者就可以伪造扫码事件。

4. 你这边的速率限制。

如果你把二维码生成开放给终端用户（比如面向客户的应用），要在自己这边实现速率限制。否则一个恶意用户就能把你在服务商那边的速率配额耗光。

5. 码目的地的审计。

对于长期生效的码（包装上、名片上），要记录每一次目的地变更。万一攻击者拿到了你的服务商账户、把目的地改成了钓鱼 URL，这份审计日志就是你的取证记录。

常见的二维码 API 错误

错误 1：把二维码生成当成一次性配置。码需要被持续管理：更新、归档、监控。请按持续运营来设计，而不是只为最初创建那一刻。

错误 2：没测过速率限制。在黑五大促的当口才撞上服务商的速率上限，是一个非常糟糕的发现问题的时机。

错误 3：存了二维码图片而没存码 ID。永远要存服务商的码 ID（这样你以后才能更新或删除这张码）。图片只是一次缓存渲染。

错误 4：没有重试逻辑。API 偶尔会失败。如果不加上指数退避的重试，临时性的故障就会变成永久性的业务故障。

错误 5：忽略 webhook 签名校验。一个不做签名校验的 webhook 接口，就是一个谁都可以伪造调用的公开 URL。

错误 6：在码里硬编码服务商的域名。请用自定义域名（你的子域名指向服务商的基础设施），这样以后想换服务商时不用改任何已经印出去的码。

错误 7：生成了指向 staging URL 的码。印在包装上或者寄给客户的码指向 staging URL，这是一个真实的风险。请校验目的地。

错误 8：URL 变了忘了更新目的地。如果网站改版导致 URL 结构发生变化，所有动态码的目的地都需要更新。非常容易遗漏。

常见问题

用动态二维码一定要 API 吗？不需要。大多数动态二维码服务商的后台已经能处理绝大多数场景，完全不用接 API。API 适合大规模程序化生成。

不用服务商的 API，能自己生成二维码吗？静态码可以。像 qrcode（Python、JavaScript）和 pyqrcode 这样的库可以在本地生成静态二维码图片，完全不依赖外部服务。但带可改目的地和数据分析的动态码就需要一个服务商。

用二维码 API 是免费的吗？有些服务商提供免费档，但请求量有限。大多数付费方案包含 API 访问。比较时既看每次请求的价格，也看每张码的价格。

能在一个应用里同时用多家二维码 API 吗？技术上可以。每张码绑死在生成它的那家服务商上。混用会让管理变复杂，通常统一一家更好。

怎么从一家二维码 API 服务商迁移到另一家？在新服务商上生成新码。旧码会继续指向旧服务商的服务器，直到被删除（或者旧订阅到期后停止跳转）。如果你用了自定义域名，可以直接改 DNS 指向新服务商的基础设施，不用重新生码，这是最适合迁移的做法。

能通过 API 生成几百万张二维码吗？可以，在企业方案上，配合相应的速率限制和批量接口。在承诺之前请确认你选的方案确实支持。

二维码 API 都支持 webhook 吗？大多数企业级和很多中档方案支持。免费和入门档常常不支持。在把 webhook 用到生产场景之前，请先确认。

接入一个二维码 API 要多长时间？简单场景（在已有应用里生成一张码）：几个小时。生产级集成，带错误处理、重试、监控和 webhook 处理：几天。完整的企业级集成，带批量操作、自定义域名和 SSO：几周。

如果 API 宕机了，我的二维码还能用吗？生成和编辑会受影响。已经生成好的码，只要服务商的跳转基础设施还在线，就会继续解析。这部分通常和 API 基础设施是分开的，可靠性目标也更高。

我能完全在自己的基础设施上跑一个二维码服务吗？静态码可以，每种主流语言都有相应的库。带跳转和数据分析的动态码，你也可以自己造，但你就是在跑一个小型 SaaS 了。对绝大多数团队来说，付费给服务商比自己造便宜。

最后一句话

对那些规模已经超出后台手工管理能力的业务来说，二维码 API 是基础设施。模式已经很成熟：生成、更新、获取数据、归档。选一家 API 成熟度匹配你需求的服务商，谨慎接入，并把码当作一份需要长期管理的资源来对待。

了解 QR Cake 的定价和 API 访问