商品药品条码查询接口接入指南｜输入条形码，获取商品名称、参考售价、生产厂家与商品图片

一、技术简介

商品药品条码查询接口用于根据商品条形码检索对应的商品基础信息。接口接收一段条形码作为输入，返回该条码对应的商品名称、参考售价、生产厂家、品牌、规格、商品图片等字段，并对药品类条码提供对应的药品信息查询能力。

当前接口覆盖国内商品条码体系，支持以 69 开头的 13 位标准商品条码，以及以 069 开头的 14 位扩展条码。药品专属条码同样在支持范围内。该能力适用于需要以条码为索引、反查商品主数据的业务系统，例如零售收银核验、仓储盘点、商品库建设、药监溯源等场景。

接口以 RESTful 风格提供，鉴权采用 Authorization: APPCODE <appcode> 请求头，调用地址以控制台显示为准。下文以中性技术视角说明接入流程、参数设计、返回结构、调试方式与常见排查方法，不涉及任何商业推广表述。

二、能力概览

下表列出接口提供的能力维度，便于在接入前确认是否满足业务需求。

三、适用场景

以下场景均以技术数据流角度描述，不讨论业务收益或投入产出。

• 零售收银核验：扫描商品条码后，调用接口补全商品名称与参考售价，用于在本地缓存缺失时回源查询。
• 仓储与盘点（WMS）：盘点设备扫描货架条码，将返回的商品名称、规格、生产厂家写入盘点单，减少录入错误。
• 商品主数据库建设：以条码为主键，批量拉取商品基础信息，构建企业自有商品库；药品类条码可同步补充药品字段。
• 药监溯源：在药品流转环节扫描药品条码，获取对应药品信息用于台账记录。
• 小程序 / APP 商品识别：移动端扫码后，将条码上送服务端，由服务端统一调用接口并返回结构化结果给前端。

四、接入流程

标准接入步骤如下，整体为「开通服务 → 获取凭证 → 组装请求 → 解析返回」四步。

1. 开通服务：在云市场完成该接口的开通，进入控制台获取调用凭证（appcode）。
2. 获取凭证：在已购服务详情页查看 AppCode，该值在后续每次请求中以请求头形式携带。
3. 组装请求：按接口要求拼接调用地址与参数，至少包含 barcode 字段；在请求头中加入 Authorization: APPCODE <appcode>。
4. 发送与解析：发起请求后，先判断 showapi_res_code 是否为 0 表示成功；成功时读取 showapi_res_body 中的商品字段，失败时按 showapi_res_error 与错误码排查。
5. 结果落库或展示：将需要持久化的字段写入业务表，或在页面渲染商品图片与名称。

五、调用示例与返回结构

5.1 请求参数

调用地址与具体参数传递方式（GET query 或 POST form）以控制台/商品页给出的接入方式为准；下例以 GET 形式示意。

5.2 完整返回结构

成功响应示例如下（其中图片字段为地址字符串，具体值以实际返回为准）：

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_body": {
   
    "ret_code": 0,
    "tiaoMa": "6901234567890",
    "goodsName": "纯牛奶",
    "price": "68.00",
    "manufacturer": "示例乳业股份有限公司",
    "brand": "示例品牌",
    "spec": "250ml*12盒",
    "unit": "箱",
    "category": "乳制品",
    "img": "（商品图片地址，以实际返回为准）"
  }
}

5.3 返回字段含义

药品类条码可能在 showapi_res_body 中返回批准文号、通用名称等扩展字段，结构以实际返回为准。

5.4 多语言调用示例

以下示例均使用占位调用地址，实际地址以控制台显示为准；<appcode> 替换为你自己的凭证。

Python

import urllib.request
import json

API_URL = "https://<调用地址>/barcode/query?barcode=6901234567890"
APPCODE = "<appcode>"

req = urllib.request.Request(API_URL)
req.add_header("Authorization", "APPCODE " + APPCODE)
req.add_header("Content-Type", "application/x-www-form-urlencoded")

with urllib.request.urlopen(req, timeout=10) as resp:
    data = json.loads(resp.read().decode("utf-8"))

if data.get("showapi_res_code") == 0:
    body = data["showapi_res_body"]
    print(body.get("goodsName"), body.get("price"), body.get("manufacturer"))
else:
    print("error:", data.get("showapi_res_error"))

Java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class BarcodeQuery {
   
    public static void main(String[] args) throws Exception {
   
        String apiUrl = "https://<调用地址>/barcode/query?barcode=6901234567890";
        String appcode = "<appcode>";
        URL url = new URL(apiUrl);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestProperty("Authorization", "APPCODE " + appcode);
        conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
        conn.setConnectTimeout(10000);
        try (BufferedReader br = new BufferedReader(
                new InputStreamReader(conn.getInputStream(), "utf-8"))) {
   
            StringBuilder sb = new StringBuilder();
            String line;
            while ((line = br.readLine()) != null) sb.append(line);
            System.out.println(sb.toString());
        }
    }
}

PHP

<?php
$apiUrl = "https://<调用地址>/barcode/query?barcode=6901234567890";
$appcode = "<appcode>";

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: APPCODE " . $appcode,
    "Content-Type: application/x-www-form-urlencoded"
]);
$resp = curl_exec($ch);
curl_close($ch);

$data = json_decode($resp, true);
if ($data["showapi_res_code"] == 0) {
   
    $body = $data["showapi_res_body"];
    echo $body["goodsName"] . " " . $body["price"] . " " . $body["manufacturer"];
} else {
   
    echo "error: " . $data["showapi_res_error"];
}
?>

Node.js

const https = require("https");

const apiUrl = "https://<调用地址>/barcode/query?barcode=6901234567890";
const appcode = "<appcode>";

const req = https.get(apiUrl, {
   
  headers: {
   
    "Authorization": "APPCODE " + appcode,
    "Content-Type": "application/x-www-form-urlencoded"
  }
}, (res) => {
   
  let raw = "";
  res.on("data", (c) => raw += c);
  res.on("end", () => {
   
    const data = JSON.parse(raw);
    if (data.showapi_res_code === 0) {
   
      const b = data.showapi_res_body;
      console.log(b.goodsName, b.price, b.manufacturer);
    } else {
   
      console.log("error:", data.showapi_res_error);
    }
  });
});
req.on("error", (e) => console.error(e));

六、在线调试实录

在控制台「API 调试」区域可按以下步骤完成一次最小验证：

1. 在条码输入框填入一个真实存在的国内商品条码，例如 6901234567890（示例值，请使用你手边的实际条码）。
2. 确认请求头已自动携带 Authorization: APPCODE <appcode>（控制台通常会预填凭证）。
3. 点击发送，观察返回 JSON。
4. 成功判定：showapi_res_code == 0 且 showapi_res_body.ret_code == 0，此时 goodsName、price、manufacturer 等字段有值。
5. 失败判定：showapi_res_code 非 0 或 ret_code 非 0，按 showapi_res_error 与错误码表排查；若返回「未查询到该条码对应商品」，多为条码不在收录范围内或格式不符。

调试时的常见坑：条码含空格或前后导零错误会导致格式校验失败；药品条码需确认属于国内药品条码体系；返回中图片地址可能为空，前端需做空值兜底。

七、接口调用限制与规范

以下为接入时应遵守的约束，具体数值以控制台实时配置为准。

• 参数必填：barcode 为必填项，缺失或为空将返回参数错误。
• 条码格式：仅接受 69 开头 13 位或 069 开头 14 位的国内商品条码；其他格式不在支持范围。
• 频控：单账户存在并发与每秒请求数上限，超出会触发限流；建议在客户端做请求合并与退避重试。
• 配额：每日调用量存在配额上限，用量达到上限后，接口返回限流错误，需在控制台关注用量。
• 超时：建议客户端设置合理超时（如 10 秒），并对网络异常做重试。
• 合规：查询所得商品信息仅可用于自身业务系统内部的数据补全与展示，不得用于非法爬取、批量转售或侵犯第三方权益的用途。

八、能力边界与免责声明

为明确接口适用范围，列出以下边界与免责说明：

支持范围

• 国内 69 开头 13 位标准商品条码。
• 国内 069 开头 14 位扩展商品条码。
• 药品类条码对应的药品信息查询。

不支持范围

• 非国内商品条码（如境外 UPC/EAN 体系）不在覆盖范围内。
• 接口不保证覆盖全部在售商品，未收录条码将返回「未查询到」类结果。
• 不提供商品实时成交金额、库存、销售渠道等动态数据。

免责声明

• 返回的商品名称、参考售价、生产厂家等信息来源于第三方商品数据库，可能存在延迟或不完整，仅供参考，不应作为交易、理赔、监管认定的唯一依据。
• 接口提供方不对因数据偏差导致的业务损失承担责任。
• 调用方须自行对返回数据做校验与兜底，并对数据使用承担合规责任。
• 建议对关键业务字段做二次核验，而非直接采信单次返回结果。

九、错误码与排查指南

下表为常见错误现象、可能原因与处理建议（具体错误码以控制台返回为准）。

十、常见问题 FAQ

Q：条码格式有什么要求？
A：当前仅支持国内商品条码，即 69 开头 13 位标准条码，或 069 开头 14 位扩展条码；其他格式不在支持范围。

Q：返回的数据多久更新一次？
A：商品主数据的更新频率以数据源为准，接口不承诺实时性；对时效性敏感的业务建议做本地缓存并定期回源刷新。

Q：药品条码能查到哪些信息？
A：药品类条码可返回对应的药品信息，具体字段以实际返回结构为准，可能包含通用名称、批准文号等扩展字段。

Q：批量查询怎么实现？
A：接口本身为单次条码查询，批量场景通过循环提交多个条码实现；注意控制并发与频率，避免触发限流。

Q：高并发下如何保证稳定？
A：在客户端实现请求合并、退避重试与本地缓存，对空结果与异常做兜底，并监控每日配额用量。

Q：返回的图片地址为空怎么办？
A：部分商品可能无图片数据，前端需对空值做兜底展示，不可假设 img 字段必有值。

十一、内容小结

本文以中性技术视角说明了商品药品条码查询接口的接入方式：通过 barcode 参数传入国内商品条码，配合 Authorization: APPCODE <appcode> 请求头调用，接口以统一的 showapi_res_code / showapi_res_body 结构返回商品名称、参考售价、生产厂家、品牌、规格与图片等字段。

工程实践中建议注意三点：一是严格校验条码格式，仅提交支持的国内条码；二是做好频控、重试与缓存，规避限流与超时；三是对返回数据做校验与兜底，尤其图片字段可能为空。接入前请再次以控制台/商品页显示的接入地址、参数传递方式与配额约束为准进行核对。