二维码生成与识别接入实战：从开通到调试的完整指南（附返回示例）
技术简介
二维码（QR Code）是一种矩阵式二维码，可在单张图片中编码网址、文本、电子名片、WiFi 信息、支付串、溯源码等数据，扫描设备识别后即可快速还原出承载内容。本教程讲解一类「二维码生成 + 二维码识别」API 服务的接入方式：开发者通过标准 HTTP 请求，即可把任意文本内容生成为二维码图片；也可对已有图片（base64、图片地址、上传）中的二维码进行识别解码，返回二维码承载的文本信息。适合需要在自有系统、公众号、App、Web 应用中集成二维码能力的场景。
能力概览
- 二维码生成：将文本、电子名片、WiFi 网络、电子邮件、短信、电话号码、网址等内容生成二维码图片；支持调整大小、图片格式，支持前景色/背景色自定义，可在二维码中间嵌入 Logo。
- 二维码识别：对图片中的二维码进行解码，支持一张图同时识别多个二维码；提供三种输入方式——图片 base64、图片地址、图片上传。
- 统一返回结构：全部接口返回 JSON，业务数据统一放在返回包裹的
showapi_res_body中，便于统一解析与异常处理。
适用场景
- 宣传海报与活动物料：把活动链接、报名链接编码进海报，扫码直达。
- 电子名片与简历：将联系方式、主页地址编码成二维码随印随扫。
- 餐桌牌同步点餐：每桌生成桌码，顾客扫码进入点餐页面。
- 二维码上网：将 WiFi 名称与密码编码，扫码自动连接。
- 产品溯源：把批次号、溯源码编码到产品包装，扫码查看来源。
- 扫码支付、会议签到、教育培训资料分发：把跳转信息与内容地址编码进二维码，简化线下到线上的触达。
接入流程
- 开通并获取凭证：在服务商控制台创建应用，获取
appcode作为身份凭证。 - 确认接入点：生成与识别分别对应不同接入点，先明确本次要调用哪一个。
- 构造请求：按接口文档拼装参数——生成用
content及可选样式参数，识别用图片 base64 或图片地址。 - 携带鉴权头调用：请求头统一设置为
Authorization: APPCODE <appcode>。 - 解析返回：先判断统一返回码，再读取业务体，取得二维码地址或识别结果。
- 工程加固：补充超时、重试、幂等、结果缓存、日志脱敏等处理。
调用示例与返回结构
以下示例使用伪域名与示例凭证，实际调用时替换为你的接入地址与 appcode。鉴权统一走请求头。
生成二维码
请求方式：POST /qrcode/create，请求头 Authorization: APPCODE <appcode>。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| content | string | 是 | 需要生成二维码的内容（文本/网址等） |
| size | number | 否 | 图片大小，1–10，越大边框越粗 |
| imgExtName | string | 否 | 图片格式，jpeg / jpg / png |
| logo_base64 | string | 否 | 二维码中间嵌入的 Logo 图片 base64（仅 png，建议 POST 调用） |
| forecolor_rgb | string | 否 | 前景色色号，默认 #000000（黑色） |
| background_rgb | string | 否 | 背景色色号，默认 #FFFFFF（白色） |
返回示例：
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"ret_code": "0",
"flag": "true",
"msg": "操作成功!",
"imgUrl": "https://example.com/qrCode/xxx.jpg"
}
}
识别二维码
请求方式：POST /qrcode/scan，请求头 Authorization: APPCODE <appcode>，请求体二选一传入图片。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| img_base64 | string | 二选一 | 要识别图片的 base64 编码 |
| img_url | string | 二选一 | 要识别图片的地址 |
返回示例：
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"ret_code": 0,
"remark": "",
"result": [
"https://example.com/page"
]
}
}
说明：
result为二维码解码结果的数组，支持一张图返回多个二维码；当图片中未找到二维码时返回空集合。
在线调试实录
在服务商提供的调试面板中，可输入样例参数直接发起调用，实时观察请求与响应，用于确认鉴权方式、参数拼装与返回结构后，再移植到业务代码中。建议先用最小参数（仅 content）验证连通，再逐步叠加可选参数，缩小问题定位范围。
调用限制与规范
- 请求方式以 POST 为主；识别图片建议不超过 1.5MB，支持 jpg / png / bmp 格式。
- base64 内容较长时需注意编码，部分语言（如 PHP）需对特殊字符做 URLencode 处理。
- 生成的二维码图片地址会定期清理，业务侧应及时保存或转存到自有存储。
- 识别接口在图片中无二维码时会返回空集合，需按约定处理并避免误判为异常。
- 建议控制并发与调用频率，避免瞬时高频冲击服务触发频控。
- 建议为每次调用设置超时时间（如 10–35 秒），并配合失败重试与结果缓存。
能力边界与免责
- 接口只负责二维码的生成与解码，不负责识别结果的语义校验与真伪判断。
- 对过度损坏、过小、严重遮挡或对比度异常的二维码，识别结果无法保证每次成功，需结合业务侧二次确认。
- 请遵守相关法律法规与平台规范，仅将二维码能力用于合法用途；二维码内容合规由调用方自行负责。
- 本服务不涉及对图片内容的人工审核，业务方需自行把关所生成与识别内容的合规性。
错误码排查
- 统一返回码
showapi_res_code：0表示成功，非0表示调用异常，showapi_res_error携带错误说明。 - 识别业务码
ret_code：0无异常；10参数错误；20文件格式错误；30操作失败请勿重复提交；40文件下载失败；50文件内容过大；60图片解析失败；70OCR 识别失败；80服务超时；90未知错误。 - 鉴权/额度类错误：凭证无效、授权未生效、调用次数超限、订阅过期、用户欠费等，按返回信息核对凭证、授权状态与订阅余量即可。
技术 FAQ
- 生成的二维码扫不出来？ 检查
content是否为空或过长，size是否过小导致模块密度过高，或图片被压缩失真。 - base64 太长报错？ 确认是否做了 URLencode，或改用图片地址方式传入。
- 识别返回空结果？ 确认图片中确有二维码、图片清晰未损坏，且尺寸与格式符合限制。
- 返回码非 0 怎么排查？ 先看
showapi_res_error描述，再核对鉴权与参数，最后确认订阅状态与余量。 - 二维码图片链接过期？ 生成成功后及时转存到自有存储即可。
内容小结
本文覆盖「二维码生成 + 识别」API 的接入全流程：能力、场景、接入步骤、调用示例与返回结构、限制规范、错误码与 FAQ。核心要点：统一 APPCODE 鉴权；生成用 content 加可选样式参数；识别用 base64 或图片地址二选一；统一解析返回包裹；做好超时、重试与结果缓存。按此流程即可快速在业务中集成二维码能力。
