适用场景与接口概览商品条码查询接口API 通过 EAN-13 / UPC-A / UPC-E / EAN-8 等主流条码标准返回商品名称、品牌、规格、参考价及图片 URL。典型场景包括电商 ERP 扫码补全、个人记账 App 扫码录入、物流仓储核销、自动售货机商品识别等。该接口采用 RESTful 风格单次请求平均响应时间约 100ms不含图片加载国内日常消费品覆盖率超过 95%。但作为接口它在调用频率和每日额度上存在明确的边界开发者在接入时需严格遵循这些限制以保证服务稳定。接口能力边界每日调用额度鉴权状态每日次数说明未登录无 API Key20 次面向临时体验场景请勿依赖生产环境登录用户携带 API Key200 次适合个人开发测试或低流量应用额度按自然日 UTC8 零点重置。超出后请求会返回code: 1003额度耗尽错误。QPS每秒请求数限制要点QPS 限制基于滑动窗口算法严格按秒级计算。如果瞬时并发超过 2/s多余请求会被直接拒绝不会排队等待。建议在客户端实现本地限速例如令牌桶避免触发 429。图片不计费特性图片资源通过modeimage参数提供由接口控制不占用每天的调用次数。但请注意图片 URL 本身是懒加载代理前端img标签加载时产生的 HTTP 请求不计入调用次数。商品文本数据JSON 响应则始终按次计费。请求参数与鉴权Query 参数参数名必填类型说明barcode是string8~13 位纯数字条码支持 EAN-13、UPC-A、EAN-8、UPC-Emode否string保留参数modeimage仅返回图片二进制不计费示例?barcode6921168509256Header 鉴权Authorization可选值为X-API-Key: $API_KEY格式。未携带 API Key 时系统自动使用未登录模式日 20 次额度。携带有效 API Key 后按登录用户额度计日 200 次。可复制的 curl 请求示例以下示例使用环境变量$APIZERO_API_KEY传递鉴权密钥请将其替换为你自己的 API Key若无则删除-H行仅体验 20 次额度curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/barcode-lookup?barcode6921168509256预期响应片段{ code: 0, data: { barcode: 6921168509256, brand: 农夫山泉, category: null, description: null, found: true, image: https://v1.apizero.cn/api/barcode-lookup?modeimagebarcode6921168509256, manufacturer: 农夫山泉股份有限公司, name: 农夫山泉 饮用天然水550ml, price: 1.5, spec: 550ml }, msg: 成功, request_id: mqx8x12345abc }返回值字段解读字段类型说明codeint业务状态码0 成功非 0 详见错误码msgstring提示信息request_idstring请求标识可用于日志联调data.barcodestring查询的条码data.foundbool是否在库中查到商品data.namestring商品名称未找到时为 nulldata.brandstring品牌data.manufacturerstring生产商/经销商data.specstring规格如“550ml”data.pricenumber参考价人民币元非实时市场价data.imagestring商品图片 URL始终返回有效地址可降级data.categorystring/null商品分类当前可能为 null以文档为准data.descriptionstring/null商品描述当前可能为 null以文档为准注意当foundfalse时data中除barcode外大多字段为null此时image返回默认占位图。常见错误码与处理HTTP Statuscodemsg含义处理建议2000成功请求正常无2001001参数错误barcode 格式不符非 8~13 位数字校验输入后重试4291002请求频率过高超出 QPS 2/s增加本地限速指数退避重试4291003超出当日调用次数当日额度耗尽20或200次等待次日重置或检查 API Key 是否携带4011004API Key 无效Authorization 格式错误或 Key 过期核对 Key 字符串5009999服务端异常后端临时故障隔几秒后重试若持续则反馈限流重试策略建议工程化import time import requests def query_barcode(barcode: str, api_key: str, max_retries: int 3) - dict: url https://v1.apizero.cn/api/barcode-lookup headers {X-API-Key: api_key} if api_key else {} params {barcode: barcode} for attempt in range(max_retries): resp requests.get(url, headersheaders, paramsparams) if resp.status_code 429: retry_after int(resp.headers.get(Retry-After, 1)) if attempt max_retries - 1: time.sleep(retry_after 1) continue resp.raise_for_status() return resp.json() raise Exception(Max retries exceeded)工程化注意事项本地限速由于 QPS 只有 2/s建议在微服务或 App 中使用令牌桶Token Bucket限制每秒请求数。例如 Go 的golang.org/x/time/rate或 Java 的RateLimiter。额度监控每日调用次数无内置剩余量查询接口建议客户端自行统计已消耗次数在接近限额前切换备用方案如降级为本地缓存的商品数据或请求用户升级。图片懒加载与降级image字段始终返回 URL但若商品不存在则为默认占位图。前端img应绑定onerror事件替换为通用图标避免破图影响体验。重试退避遇到 HTTP 429 时响应中可能包含Retry-After头部单位秒。若没有建议按指数退避1s、2s、4s…重试最多 3 次。请求唯一标识request_id可用于关联服务端日志排查问题时连同request_id一并提供。参数校验在客户端提前校验 barcode 长度和纯数字格式避免因参数错误浪费调用次数。并发场景若多个线程/协程同时调用务必在发送请求前统一通过限流器控制速率否则易触发 QPS 限制。参考文档官方文档页https://apizero.cn/aidocs/barcode-lookup原始文档rawhttps://apizero.cn/aidocs/barcode-lookup/raw.md本文不包含任何商业引导所有调用限制信息以官方文档最新版本为准。