商品条码查询 API 接入教程：药品与商品信息字段解析

一、技术简介

商品条码（EAN/UPC）是商品在全球流通中的统一身份标识，广泛印刷于包装、标签与收银小票上。零售收银、电商建品、仓储入库、供应链追溯等环节，都会遇到「扫一下条码，立刻还原出商品信息」的需求：输入一串条码数字，业务系统就能拿到商品名称、品牌、规格、生产厂家、参考售价、产地、分类等结构化字段，用于自动建档、订单校验、扫码比价等场景。

商品条码查询 API 就是为这一需求提供的 HTTP 接口：调用方传入合法的条码数字串，服务端返回该条码对应的商品信息，以 JSON 格式输出，请求方式为 GET/POST，便于在 Web 后端、移动应用、扫码设备、ERP 系统等终端中直接集成。除常规商品信息外，该接口还提供药品条码专用接入点，可返回用法用量、禁忌、注意事项、批准文号等用药字段，适用于药店收银、医药电商等场景。

本文从能力边界、接入流程、参数设计、返回结构、错误处理与工程实践六个维度，完整介绍该接口两个接入点的接入与使用方法。

二、能力概览

接口覆盖常见的商品条码体系，并提供两个业务接入点：

条码类型支持范围：

常规商品返回字段按用途可分为以下几组：

• 基础标识：code（查询的条码本身）、ret_code（业务返回码）、flag（成功标记）、remark（结果描述）。
• 商品信息：goodsName（商品名称）、trademark（品牌/商标）、spec（规格型号）、keyword（商品关键词）、goodsType（商品分类层级路径）。
• 厂商信息：manuName（生产厂商名称）、manuAddress（厂商地址）。
• 产地与分类：ycg（产地/原产国）、gpc（GPC 分类码）、gpcType（GPC 分类名称）。
• 扩展信息：price（参考售价）、img（商品主图 URL）、imgList（多图数组）、note（备注信息，含尺寸、英文名称等）。

不同品类的商品返回字段完整度存在差异：食品、日化等快消品字段较全；部分工业用品或新品可能仅返回名称与厂商，参考售价、图片、分类等字段为空。调用方在数据建模时应将所有业务字段视为可空，不可假设必填。

三、适用场景

3.1 电商与零售商品建档

商家在 ERP 或商品管理系统中录入条码后，系统自动调用接口回填商品名称、品牌、规格、厂商，节省重复录入时间，并保证商品名称与主数据一致。

3.2 仓储与物流收货校验

仓库扫码收货时，通过条码反查商品信息，与采购单、上架标签进行比对，防止错收、错发。接口返回的商品分类字段可辅助快速判断货物归属库区。

3.3 扫码比价与商品百科

比价类应用、商品百科类小程序在用户扫描实物条码后，展示商品名称、参考售价和商品图片，为用户提供即时信息参考。

3.4 药品与保健品信息核对

药品条码接入点返回用法用量、禁忌、注意事项、批准文号等字段，可用于药店收银系统、医药电商详情页、药品信息核对场景，辅助核对药品名称与生产厂家信息。注意该接入点返回内容不构成用药建议，面向消费者展示时应附加「请遵医嘱」提示。

3.5 渠道管理与品牌核查

品牌方在渠道管理中，通过条码查询返回的厂商名称与授权经销信息交叉比对，辅助识别窜货行为。

四、接入流程

4.1 获取访问凭证

在云市场控制台开通该接口后，控制台会分配一个专属的 AppCode。后续所有请求都需要在 HTTP Header 中携带该凭证：

Authorization: APPCODE <您的AppCode>

AppCode 等同于密钥，请勿泄露到前端、公开仓库或日志中。

4.2 确定调用地址

开通服务后，云市场控制台会提供该 API 的 HTTPS 调用地址（Endpoint），并区分商品条码与药品条码两个接入点。在代码中建议将其配置为环境变量或配置项，不要硬编码。

4.3 组织请求参数

接口仅需一个业务参数 code，即待查询的条形码数字串。请求方式为 GET/POST，参数通过 Query 或表单传递。生产环境建议把调用地址与凭证统一收敛到服务端配置，避免散落在代码各处。

4.4 解析返回结果

接口返回 JSON，业务数据位于 showapi_res_body 对象内。系统级字段（showapi_res_code、showapi_res_error、showapi_res_id）用于网关层排障；业务层判断以 ret_code 是否为 0 为准。

五、调用示例与返回结构

5.1 请求参数

请求 Header：

5.2 cURL 示例

curl -G "$API_ENDPOINT" \
  -H "Authorization: APPCODE <您的AppCode>" \
  --data-urlencode "code=6938166920785"

其中 $API_ENDPOINT 替换为云市场控制台提供的调用地址。

5.3 Python 示例

import os
import requests

API_ENDPOINT = os.environ["API_ENDPOINT"]
APP_CODE = os.environ["APP_CODE"]

def query_barcode(code: str) -> dict:
    headers = {
   
        "Authorization": f"APPCODE {APP_CODE}",
    }
    resp = requests.get(
        API_ENDPOINT,
        headers=headers,
        params={
   "code": code},
        timeout=5,
    )
    resp.raise_for_status()
    data = resp.json()
    body = data.get("showapi_res_body", {
   })
    if str(body.get("ret_code")) != "0":
        raise RuntimeError(f"查询失败: {body.get('remark')}")
    return body

if __name__ == "__main__":
    result = query_barcode("6938166920785")
    print("商品名称:", result.get("goodsName"))
    print("品牌:", result.get("trademark"))
    print("规格:", result.get("spec"))
    print("厂商:", result.get("manuName"))

5.4 Java 示例

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class BarcodeQuery {
   
    public static void main(String[] args) throws Exception {
   
        String endpoint = System.getenv("API_ENDPOINT");
        String appCode = System.getenv("APP_CODE");

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(endpoint + "?code=6938166920785"))
                .header("Authorization", "APPCODE " + appCode)
                .GET()
                .build();

        HttpResponse<String> response = client.send(request,
                HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

5.5 Node.js 示例

const APP_CODE = process.env.APP_CODE;
const API_ENDPOINT = process.env.API_ENDPOINT;

async function queryBarcode(code) {
   
  const url = new URL(API_ENDPOINT);
  url.searchParams.set("code", code);
  const resp = await fetch(url, {
   
    headers: {
    Authorization: `APPCODE ${
     APP_CODE}` },
  });
  if (!resp.ok) throw new Error(`HTTP ${
     resp.status}`);
  const data = await resp.json();
  const body = data.showapi_res_body || {
   };
  if (String(body.ret_code) !== "0") {
   
    throw new Error(`查询失败: ${
     body.remark}`);
  }
  return body;
}

queryBarcode("6938166920785").then((r) => {
   
  console.log("商品名称:", r.goodsName);
  console.log("品牌:", r.trademark);
  console.log("厂商:", r.manuName);
}).catch((e) => console.error(e.message));

5.6 常规商品返回结构

{
   
  "showapi_res_error": "",
  "showapi_fee_num": 1,
  "showapi_res_code": 0,
  "showapi_res_id": "67905216fb638c23e1849490",
  "showapi_res_body": {
   
    "flag": true,
    "ret_code": "0",
    "remark": "查询成功！",
    "code": "6938166920785",
    "goodsName": "强生婴儿牛奶沐浴露300毫升",
    "trademark": "强生婴儿",
    "spec": "300毫升",
    "manuName": "强生(中国)有限公司",
    "manuAddress": "",
    "goodsType": "服装、箱包、个人护理用品>>个人护理用品>>洗浴、身体护理品>>皮肤护理品",
    "gpc": "10000330",
    "gpcType": "身体清洁/洗涤/香皂用品",
    "ycg": "",
    "price": "",
    "keyword": "沐浴露",
    "img": "https://example.com/barcode/product.jpg",
    "imgList": [],
    "note": "checkResult：1；备注：宽：7.8；单位：CM；高：16.1；深：3.7；英文名称：Johnson's milk+rice bath 300ml；关键字：沐浴露；产地：上海；"
  }
}

返回字段说明：

5.7 药品条码返回结构

药品条码接入点返回的字段与常规商品接入点不同，核心是用药信息组：

{
   
  "showapi_res_code": 0,
  "showapi_res_body": {
   
    "ret_code": 0,
    "remark": "查询成功",
    "name": "皇后牌片仔癀珍珠膏",
    "spec": "20g",
    "basis": "片仔癀：3%；珍珠粉：5%；丙三醇：15%；高级白油：7%；高级脂肪醇：8%。",
    "dosage": "早晚两次，洁肤后适量使用并略加按摩至皮肤吸收。",
    "consideration": "1、请置於幼儿无法取得处。2、眼睛周围、黏膜等部位请勿使用。",
    "approval": "闽G妆网备字2020001817",
    "manuName": "福建片仔癀化妆品有限公司",
    "manuAddress": "福建漳州市草寮街132号",
    "img": "https://example.com/drug/barcode.jpg",
    "type": "非药品"
  }
}

药品接入点关键字段：

实测该接入点的「药品库」同时收录药妆健字类产品，返回 type 可能为「非药品」。仅服务药品业务时，建议用 approval 文号前缀（国药准字）做硬过滤，type 仅作辅助判断。

六、在线调试实录

以国内商品条码 6938166920785 为例，完整走一次调用流程。

第一步：在云市场调试工具中输入条码 6938166920785，发起 GET 请求，Header 携带 Authorization: APPCODE <您的AppCode>。

第二步：观察返回 JSON，重点确认 ret_code 为 "0"、flag 为 true。

第三步：提取业务字段：

• 商品名称：goodsName
• 品牌：trademark
• 规格：spec
• 厂商：manuName
• 分类路径：goodsType

第四步：如果业务需要商品图片，将返回的 img 字段 URL 下载到自有 OSS 或 CDN。该 URL 带有时效性（通常 24 小时内有效），不要直接作为前端永久链接使用。

第五步：构造业务展示数据。在收银、仓储或商品建档场景中，将上述字段映射到自己的数据模型即可。

药品条码调试时，先确认返回 ret_code 为 0，再按 type 与 approval 前缀分流展示：approval 以「国药准字」开头按药品页渲染，否则按普通商品/化妆品页渲染。dosage、taboo 等用药字段为空时展示「参见说明书」，不要自行补写内容。

七、调用限制与规范

7.1 条码编码规则

• 国内商品条码以 69 开头，长度 13 位（EAN-13）。
• 储运包装条码以 069 开头，长度 14 位（EAN-14）。
• 传入非数字字符、长度不对或校验位错误的条码，接口会返回对应错误码。
• 条码中不要包含空格、连字符或其他分隔符。

7.2 图片 URL 时效性

返回的商品图片 URL 是带有签名参数的临时地址，有效期通常为 24 小时。生产环境应在查询成功后立即将图片下载至自有对象存储，并替换为自己的永久 URL，避免后续图片 404。

7.3 数据更新频率

条码库收录了大量商品数据，新上市商品、临时活动包装、区域限定商品可能存在入库延迟。查询不到不代表条码无效，可能是该商品尚未被收录；药品长尾品种、新批文同样存在入库滞后，产品侧应有说明书拍照录入等兜底方案。

7.4 鉴权安全

• AppCode 仅放在服务端请求 Header 中，不要在前端 JS、小程序前端代码中明文携带。
• 若 AppCode 泄露，应立即在云市场控制台重置。
• 建议对失败的请求（4xx/5xx）记录 showapi_res_id 以便排查。

7.5 幂等与重试

接口为只读查询，天然幂等。网络超时或 5xx 错误时，可以使用相同参数重试 1–2 次。建议配合指数退避策略，避免对服务端造成突发压力。

7.6 批量查询与缓存

• 接口为单条查询。批量场景应在业务侧循环调用，建议控制并发（如每秒不超过 5–10 次）。
• 相同条码的查询结果做本地缓存（如 TTL 24 小时），减少重复调用。
• 对「未收录/未查到」的条码做 30 天左右的负缓存，过期后允许重查，不要永久放弃也不要每次重试。

八、能力边界与免责

• 接口返回的商品信息来源于公开条码数据库，不构成商品质量、真伪或售价的权威证明。price 字段为参考售价，可能与实际零售价存在差异。
• 商品图片版权归对应品牌方所有，业务使用前应确认自身有权使用。
• 药品类信息（用法用量、禁忌、注意事项）为说明书级文本，仅作辅助核对，不构成用药建议，不替代药品监管部门的官方数据库查询；面向消费者展示时应附加「请遵医嘱」提示。
• 药品条码接入点限定 69 开头的国内条码，进口药品无国内 69 码时无法查询。
• 接口不提供条码生成功能，仅做条码查询。如需生成条码图片，应使用专门的条码生成库（如 JBarcode、zxing）。
• 部分商品（尤其是新品、区域特供、工业零件）可能查不到完整信息，返回字段为空属于正常情况，业务层需做空值兼容。

九、错误码排查

网关层错误（showapi_res_code 非 0）通常与鉴权、配额、网络有关，可结合 showapi_res_error 字段和 showapi_res_id 在控制台排查。

十、技术 FAQ

Q1：为什么同一个条码有时返回有图片，有时返回空？
A：不同来源的数据完整度不同。快消品、日化品图片较全；部分工业用品、新品可能暂无图片。业务层应将 img 视为可空字段，空时使用占位图。

Q2：可以批量查询条码吗？
A：当前接口为单条查询。批量场景应在业务侧循环调用，建议控制并发数（如每秒不超过 5–10 次），并对结果做本地缓存，避免重复查询相同条码。

Q3：返回的 note 字段是什么格式？
A：note 是分号分隔的键值对字符串，例如 checkResult：1；备注：宽：7.8；单位：CM；高：16.1；产地：上海；。该字段非结构化，如需使用其中信息，建议在业务侧自行解析，且做容错处理。

Q4：条码库里的信息多久更新一次？
A：条码库持续扩充新商品数据，但具体更新周期不固定。新上市商品可能需要数周甚至更长时间才能被收录。

Q5：UPC 条码和 EAN 条码都能查吗？
A：支持 UPC-A（12 位）和 UPC-E（压缩位），但国内商品主要为 EAN-13/UPC-A。8 位短码 EAN-8 也在支持范围内。

Q6：需要在前端（浏览器/App）直接调用吗？
A：不建议。AppCode 会暴露在客户端代码中，存在被盗用风险。正确做法是由业务后端中转请求，前端只拿到业务需要的字段。

Q7：药品条码查询返回的是「非药品」怎么办？
A：正常。该接入点同时收录药妆健字类产品，type 可能为「非药品」，approval 也可能是「妆网备字」等化妆品备案文号。仅服务药品业务时按「国药准字」前缀硬过滤，type 作辅助判断。

Q8：taboo（禁忌）为空时可以填「无禁忌」吗？
A：不可以。为空只说明库里没有这条数据，填「无禁忌」等于替厂商做安全声明。正确做法是展示「参见说明书」。

十一、内容小结

本文介绍了商品条码查询接口的完整接入方式：从 APPCODE 鉴权、单参数 code 调用，到常规商品与药品条码两类返回结构解析、多语言代码示例、图片 URL 时效性处理、错误码排查和工程实践要点。在实际项目中，建议重点关注四点：

1. 空值兼容：不同商品返回字段完整度不同，数据模型应宽松；
2. 图片落库：临时图片 URL 需及时下载到自有存储；
3. 服务端中转：AppCode 仅在服务端使用，前端通过自己的后端获取数据；
4. 药品分流：药品接入点按 type 与文号前缀分流展示，用药字段为空展示「参见说明书」，不自行补写。

按照上述流程接入后，即可在零售、仓储、比价、药品核对等场景中快速实现「扫码即得商品信息」的能力。