适用场景与接口定位商品条码查询PRO接口slug: barcode-gs1是一款面向国内官方商品条码数据的查询服务数据直接来源于中国物品编码中心准备数据库。其典型应用场景包括电商平台商品上架前的条码合规核验确认条码是否已在编码中心准备供应链溯源场景需要获取厂商名称、上市日期、准备天数等官方登记信息内部系统对条码数据进行缓存更新确保数据权威性需要政企数据互认的物料管理系统避免使用第三方非官方数据源。与通用条码查询接口如barcode-lookup不同本接口仅覆盖6/690 开头的国内准备条码进口商品或未准备条码会返回found: false。因此在使用前应先确认业务所涉及的条码范围避免预期偏差。接口能力边界QPS 限制与令牌桶机制本接口的速率限制为2 QPS每秒最多2次请求。这意味着在同一秒内发起的第3个请求会被拒绝HTTP 429 Too Many Requests。该限制针对每个API Key授权用户或每个IP匿名用户分别计算。授权用户可在请求头中携带X-API-Key或Authorization素材中建议使用X-API-Key享有授权额度除QPS限制外还有每日总次数限制具体值以文档为准。匿名用户每个IP每天最多20次调用超出后返回额度耗尽错误。超时与重试策略官方未明确给出接口响应超时时间但根据经验条码查询后端依赖官方数据库一般响应在200ms~2s之间。建议客户端设置连接超时5秒、读取超时10秒避免长时间等待导致连接池耗尽。当遇到限流429或临时服务不可用503时应采用指数退避重试策略例如首次等待1秒、第二次2秒、第三次4秒最大重试3次。数据更新频率返回字段中包含product_create_date、qr_active_date、company_register_date等时间戳但这些数据以编码中心数据库同步为准并非实时触发。接口本身不提供数据变更推送如需频繁校验条码状态变化建议自行设计定时同步任务间隔建议不小于1小时。请求参数与鉴权方式请求方法及地址GET https://v1.apizero.cn/api/barcode-gs1Query 参数参数名必填类型说明示例值code是string商品条形码8/12/13/14位纯数字或16位AI(01)GTIN-146921168509256注意code 需经过 URL 编码若包含非数字字符但本接口仅接收数字因此无需额外编码若使用 16 位含括号的 AI 格式需先去除括号或按文档规则处理。鉴权方式匿名调用不携带任何鉴权头适用于测试或极低频率场景每天20次。授权调用在请求头中添加X-API-Key: {你的API Key}可获得更高的每日额度具体以平台文档为准。素材中提供的 curl 示例使用的是 Header 方式实际上也支持在 Query 参数中传递api_key需确认文档但推荐使用 Header 以避免 URL 泄露。可复制的 curl 示例以下示例使用环境变量$APIZERO_API_KEY传递密钥如未设置则自动降级为匿名调用。# 授权模式推荐 curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/barcode-gs1?code6921168509256# 匿名模式每日20次 curl -sS -X GET https://v1.apizero.cn/api/barcode-gs1?code6907992700199若$APIZERO_API_KEY未定义第一种写法会发送空 Header服务端可能按匿名处理或报错。建议在脚本中明确判断export API_KEYyour_real_key_here curl -sS -H X-API-Key: $API_KEY https://v1.apizero.cn/api/barcode-gs1?code6921168509256返回值详解成功响应HTTP 200的 JSON 结构如下{ code: 0, msg: 成功, request_id: mp0vcq0fab827132, data: { barcode: 6907992700199, found: true, registered: true, name: 伊利儿童奶酪棒香草冰淇淋味再制干酪, brand: 伊利, general_name: 奶酪易腐坏, feature: 伊利儿童奶酪棒香草冰淇淋味再制干酪, manufacturer: 内蒙古伊利实业集团股份有限公司, category: 奶酪易腐坏(10000028), category_code: null, specification: 90克, net_content: 90克, price: null, country: null, address: null, images: [https://www.gds.org.cn/userfile/.../06907992700199.1.jpg], sale_date: null, product_create_date: 2019年11月18日, qr_active_date: null, company_register_date: null, use_days: 2366, registration_message: 该商品条码已经在中国物品编码中心注册编码信息已按规定通报。 } }关键字段说明code: 业务状态码0 表示成功非0 表示错误见下一节。found: 布尔值表示是否找到该条码信息。若为falsedata 中可能只有barcode和found字段。registered: 准备状态仅当foundtrue时有效。images: 官方商品图片数组可能为空。use_days: 商品自创建日期到查询日期的天数可用于计算商品在库时长。category: 分类名称及编码如奶酪易腐坏(10000028)可用于分类统计。注意当foundfalse时不要依赖其他字段的值应优先检查registration_message。常见错误与处理HTTP状态码code字段含义处理建议2000成功正常解析 data2001001参数错误code格式非法检查入参位数与格式401-鉴权失败检查 API Key 是否正确429-请求频率超限等待1秒后重试403-额度耗尽升级授权或等待次日重置503-服务暂时不可用指数退避重试注意部分错误可能直接返回非200状态码此时响应体不一定包含code字段。建议在代码中统一判断 HTTP 状态码后再解析 JSON。典型错误场景QPS 超限在循环中连续调用不加延迟触发 429。解决方案使用 Semaphore 或限流库控制并发配合固定间隔至少500ms。匿名额度用尽每天20次很快用完测试阶段应尽量使用授权 Key。条码未准备foundfalse是一个正常业务结果不属于错误但需提醒业务方注意。工程化注意事项1. 连接池与 HTTP 复用建议使用长连接Keep-Alive复用 TCP 连接减少 TLS 握手开销。在 Node.js 中可使用agent: new http.Agent({ keepAlive: true })在 Python 中使用requests.Session。注意连接池大小建议设为 5~10避免占用过多文件描述符。2. 缓存策略条码信息属于低频变化数据尤其是厂商名称、准备日期等可设置24小时本地缓存。当缓存命中时直接返回避免重复调用占用 QPS。缓存的失效策略建议采用“缓存后24小时过期”或“定期全量更新”。3. 限流客户端实现由于 QPS 只有 2不建议在业务代码中直接并发调用。可以使用令牌桶算法每 0.5 秒放行一个请求。示例伪代码import time import threading class TokenBucket: def __init__(self, rate_per_sec2): self.capacity 2 self.tokens self.capacity self.last_refill time.monotonic() self.lock threading.Lock() def consume(self): with self.lock: now time.monotonic() elapsed now - self.last_refill self.tokens min(self.capacity, self.tokens elapsed * 2) self.last_refill now if self.tokens 1: self.tokens - 1 return True else: return False4. 日志与监控每次请求记录request_id到日志中便于排查问题时与后端沟通。同时监控 HTTP 429 和 503 的频率如果频率升高应检查是否接近额度上限或系统有异常。5. 多 Key 轮询如果单日调用量较大可以申请多个 API Key 轮流使用但需注意每个 Key 的 QPS 同样受限于 2/s且跨 Key 的请求仍可能会被源站统一限流需以实际文档为准。建议优先评估是否可以通过缓存降低调用量。参考文档商品条码查询PRO 接口文档原始文档 Markdown 源请注意文档中可能包含详细的额度说明、变更日志等建议开发前仔细阅读。