<!-- 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 -->

# 商品条码查询

> 通过商品条形码（EAN-13 / UPC-A / UPC-E / EAN-8）一键查询商品信息，覆盖国内日常消费品超千万 SKU，包括食品饮料、日用百货、个护美妆、酒水烟草、母婴用品等。

【核心字段】
- name 商品名称
- brand 品牌
- manufacturer 生产厂商 / 经销商
- spec 规格（如 550ml / 250g / 6 听装）
- price 参考价（人民币元，仅作参考非实时市场价）
- image 商品图片 URL（自有 CDN 代理，跨域友好）

【典型场景】
- 电商 / 零售 ERP：扫码录入商品自动补全字段
- 个人记账 App：扫码识物展示购物明细
- 物流仓储：条码核销 + 商品图展示
- 自动售货机：条码识别后获取商品名称
- 营销活动：用户扫码核销福利时验证商品

【调用示例】
GET /api/barcode-lookup?barcode=6921168509256

【特别说明】
- 平均响应 100ms（不含图片下载）
- 国内主流商品（农夫山泉、可口可乐、康师傅、伊利等）覆盖率 > 95%
- 个别冷门 / 新上市 SKU 可能未收录，此时 found=false
- price 字段仅作参考，非各电商平台实时价格
- image 字段始终返回有效 URL（接图片 onError 即可降级到默认图标）

【⚠️ 注意】
图片资源为公开懒加载代理，不计入接口调用次数；商品文本数据为按次计费。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `barcode-lookup` |
| 接口名称 | 商品条码查询 |
| 接口地址 | `https://v1.apizero.cn/api/barcode-lookup` |
| 请求方法 | `GET` |
| 分类 | life |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 2 req/s |
| 每日免费额度 | 200 次（已认证用户） |
| 匿名每日额度 | 20 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

本接口对未登录用户开放每日 20 次体验额度；超出后或登录后享受更高额度。建议生产环境使用 API Key。

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

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `barcode` | `string` | 是 | 8~13 位纯数字条形码。支持 EAN-13、UPC-A、EAN-8、UPC-E 等主流标准。 | `6921168509256` |
| `mode` | `string` | 否 | 保留参数：mode=image 时返回该商品的图片二进制（不计费、公开访问，主要由响应中的 image 字段链接自动调用）。 | `image` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | 可选 API Key 鉴权。未登录每天有 20 次免费体验额度；登录用户每天 200 次免费 | — |

## 5. 请求示例 (cURL)

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

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `code` | `integer` | 业务状态码，0 表示成功 | `0` |
| `msg` | `string` | 人类可读的状态消息 | `成功` |
| `data.barcode` | `string` | 回显的输入条形码 | `6921168509256` |
| `data.found` | `boolean` | 是否查到该商品；false 时其余字段均为 null | `true` |
| `data.name` | `string\|null` | 商品名称 | `农夫山泉 饮用天然水550ml` |
| `data.brand` | `string\|null` | 品牌 | `农夫山泉` |
| `data.manufacturer` | `string\|null` | 生产厂商 / 经销商 | `农夫山泉股份有限公司` |
| `data.spec` | `string\|null` | 规格（容量 / 重量 / 包装等） | `550ml` |
| `data.price` | `number\|null` | 参考价（人民币元，浮点；仅作参考，非实时市场价） | `1.5` |
| `data.category` | `string\|null` | 商品分类（部分商品可能为 null） | `null` |
| `data.description` | `string\|null` | 附加描述（部分商品可能为 null） | `null` |
| `data.image` | `string\|null` | 商品图片 URL（自有 CDN 代理）；found=false 时为 null | `https://v1.apizero.cn/api/barcode-lookup?mode=image&barcode=6921168509256` |
| `request_id` | `string` | 本次请求 ID（出问题时反馈给客服可快速定位） | `mqx8x12345abc` |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "barcode": "6921168509256",
        "found": true,
        "name": "农夫山泉 饮用天然水550ml",
        "brand": "农夫山泉",
        "manufacturer": "农夫山泉股份有限公司",
        "spec": "550ml",
        "price": 1.5,
        "category": null,
        "description": null,
        "image": "https:\/\/v1.apizero.cn\/api\/barcode-lookup?mode=image&barcode=6921168509256"
    },
    "request_id": "mqx8x12345abc"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `0` | `OK` | 成功（包含 found=true 和 found=false 两种情况） |
| `4000` | `Bad Request` | 条形码格式错误：barcode 必须为 8~13 位纯数字 |
| `4011` | `Unauthorized` | API Key 无效（仅在带 Key 调用时触发） |
| `4013` | `Forbidden` | API Key 已暂停 |
| `4014` | `Forbidden` | 当前 IP 不在 API Key 白名单内 |
| `4022` | `Payment Required` | 余额不足，请充值后再试 |
| `4029` | `Too Many Requests` | 调用过快（超过 QPS 限制） |
| `4030` | `Too Many Requests` | 今日免费额度已用完 |
| `5020` | `Bad Gateway` | 商品数据库暂不可用，请稍后重试 |
| `5030` | `Bad Gateway` | 商品数据库未配置（平台运维问题，请联系客服） |

## 9. 变更日志

- **1.0.0** (2026-05-05)
  - 首次发布
  - 支持 EAN-13 / UPC-A / UPC-E / EAN-8 等主流条形码
  - 返回商品名称、品牌、厂商、规格、参考价
  - 提供商品图片 CDN 代理（懒加载，跨域友好）
  - 匿名用户每日 20 次免费体验

---

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

Source: `https://apizero.cn/aidocs/barcode-lookup/raw.md`
Last updated: 2026-05-11T16:16:07+08:00