<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 商品条码查询(GS1中国)

> 官方权威的商品条码查询接口，数据直通中国物品编码中心(GS1 China)官方注册数据库。

【数据源升级 · 2026-05】当前以中国编码官方 APP (ancc.org.cn) 为主源，多源兜底（chinatrace / gds-bff / cnaidc），三级缓存设计（Redis 24h → MySQL 永久库 → 上游 API），高频查询的条码自动周期性回源刷新，数据时效性进一步优化。

与 `barcode-lookup` 定位不同：
- 本接口**官方权威**：返回厂商注册名称、产品登记信息、上市日期、官方商品图等可追溯的官方数据
- 本接口**仅覆盖国内注册条码**(6/690 开头)，进口商品或非注册条码会返回 found=false
- 适合合规核验、溯源、上架审核等对数据权威性要求高的场景

支持输入格式：8 / 12 / 13 / 14 位纯数字，或 16 位 AI(01) 前缀 + GTIN-14。

返回数据包含：产品名称、品牌、通用名、分类（含分类编号）、规格、净含量、上市日期、厂商企业名、官方商品图、条码激活日期、产品创建日期、企业注册日期、已用天数等核心字段，部分情况下额外提供生产国、企业地址、参考售价、厂商识别代码等扩展字段。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `barcode-gs1` |
| 接口名称 | 商品条码查询(GS1中国) |
| 接口地址 | `https://v1.apizero.cn/api/barcode-gs1` |
| 请求方法 | `GET` |
| 分类 | life |
| 提供方 | 极数本源 |
| 计费模式 | 按次付费 · 月套餐 |
| 单次消耗 | 0 积分 |
| 起步价 | ¥0.00 / 1000 次 |
| QPS 限制 | 2 req/s |
| 每日免费额度 | 20 次（已认证用户） |
| 匿名每日额度 | 20 次（无 API Key） |
| VIP 免费 | 是 |
| 调用总次数 | undefined |

## 2. 认证

可匿名调用(每天 20 次)，传 API Key 后每天 20 次免费额度 + 付费套餐；响应缓存 24h

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `code` | `string` | 是 | 商品条形码(8/12/13/14 位纯数字，或 16 位 AI(01) 前缀 + GTIN-14) | `6921168509256` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | 登录用户传 API Key 享用更高额度；匿名调用每天 20 次免费 | — |

## 5. 请求示例 (cURL)

```bash
curl "https://v1.apizero.cn/api/barcode-gs1?code=6921168509256&key=YOUR_API_KEY"
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `barcode` | `string` | 13 位标准 EAN-13 条码 | — |
| `gtin14` | `string` | 14 位 GTIN（左侧补 0 标准化） | — |
| `found` | `boolean` | 是否在 GS1 中国数据库找到；false 时其余业务字段为 null | — |
| `registered` | `boolean` | 条码是否已在中国物品编码中心正式注册 | — |
| `registration_message` | `string` | 注册状态说明文本 | — |
| `name` | `string` | 完整产品名（含品牌+规格） | — |
| `brand` | `string` | 品牌名称 | — |
| `general_name` | `string` | 产品通用名（如"奶酪（易腐坏）"） | — |
| `feature` | `string` | 产品特征描述 | — |
| `category` | `string` | 产品分类（含 GPC 分类编号，如"奶酪（易腐坏）(10000028)"） | — |
| `specification` | `string` | 规格（如 90克 / 550ml） | — |
| `net_content` | `string` | 净含量 | — |
| `sale_date` | `string` | 上市日期（YYYY-MM-DD） | — |
| `manufacturer` | `string` | 发布企业名称（官方注册主体） | — |
| `images` | `string[]` | 官方商品图 URL 数组（gds.org.cn 域名） | — |
| `qr_active_date` | `string` | 二维码激活日期（YYYY年MM月DD日） | — |
| `product_create_date` | `string` | 产品信息创建日期（YYYY年MM月DD日） | — |
| `company_register_date` | `string` | 企业在编码中心的注册日期（YYYY年MM月DD日） | — |
| `use_days` | `integer` | 条码从登记到现在已用天数 | — |
| `country` | `string` | 生产国 / 产地（部分备源提供，主源可能为 null） | — |
| `address` | `string` | 企业地址（部分备源提供，主源可能为 null） | — |
| `price` | `string` | 参考售价（部分备源提供，主源可能为 null） | — |
| `category_code` | `string` | GPC 全球品类编码 / 厂商识别代码（部分源提供） | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "barcode": "6907992700199",
        "gtin14": "06907992700199",
        "found": true,
        "registered": true,
        "registration_message": "该商品条码已经在中国物品编码中心注册，编码信息已按规定通报。",
        "name": "伊利儿童奶酪棒香草冰淇淋味再制干酪",
        "brand": "伊利",
        "general_name": "奶酪（易腐坏）",
        "feature": "伊利儿童奶酪棒香草冰淇淋味再制干酪",
        "category": "奶酪（易腐坏）(10000028)",
        "specification": "90克",
        "net_content": "90克",
        "sale_date": null,
        "manufacturer": "内蒙古伊利实业集团股份有限公司",
        "images": [
            "https:\/\/www.gds.org.cn\/userfile\/uploada\/gra\/sj201210093039959369\/06907992700199\/06907992700199.1.jpg"
        ],
        "qr_active_date": null,
        "product_create_date": "2019年11月18日",
        "company_register_date": null,
        "use_days": 2366,
        "country": null,
        "address": null,
        "price": null,
        "category_code": null
    },
    "request_id": "mp0vcq0fab827132"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 缺少 code 参数，或条码格式非法(非 8/12/13/14 位数字) |
| `4029` | `—` | 调用过快，请降低 QPS |
| `4030` | `—` | 今日免费额度已用完(匿名每天 20 次 / 登录每天 20 次) |
| `5020` | `—` | 商品编码中心暂不可用或触发限流 |
| `5021` | `—` | 上游返回格式异常 |
| `5030` | `—` | 商品编码代理未配置(管理员侧问题) |

## 9. 变更日志

- **2.0.0** (2026-05-11)
  - 主源协议升级：从旧的 RSA+AES 加密协议切换为中国编码 APP 官方 searchGoods 接口
  - 多账号支持：支持 .env 配置 UPSTREAM_ANCC_ACCOUNTS 多账号轮转，突破单账号限流
  - 周期性后台刷新：本地命中第 10/20/30... 次时自动后台调上游拉最新数据，高频条码自动保鲜
  - 响应字段补全：补充 country / address / price / category_code 等扩展字段（部分源提供）
  - 免责声明完善：新增完整法律免责条款，明确数据归属、知识产权、责任豁免边界
- **1.0.0** (2026-05-08)
  - 首次上线，三级缓存（Redis 24h → MySQL 永久 → 上游 API）
  - 多源调度：chinatrace / gds-bff / cnaidc 自动熔断与降级
  - 未登记条码友好降级为 found=false，不抛错

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/barcode-gs1`

Source: `https://apizero.cn/aidocs/barcode-gs1/raw.md`
Last updated: 2026-05-12T11:30:07+08:00