# 物流与质量追溯：一物一码条码生成与扫码核验方案
> 接口/接入点：条码生成与识别（apiCode 1129）· 1129-1 生成、1129-2/3/4 识别 ｜ 是否免费：免费 ｜ 请求方式：POST/GET ｜ 返回格式：JSON ｜ 适用人群：物流/质量/供应链工程师 ｜ 阅读时间：约 7 分钟
## TL;DR
- "一物一码"：为每个实物生成唯一条码（用 `content` 承载流水号/批次号），CODE_128(5) 或 EAN_13(2) 常用。
- 出入库/质检时扫码识别成文字，与追溯系统比对，形成闭环。
- 生成图片 12h 过期，追溯档案须把图落盘归档，不可依赖 `imgUrl`。
## Why：追溯为什么靠条码
质量追溯要求"哪批料、哪件成品、经谁手"可追。把唯一编码印/贴到实物上，每个环节扫码识别，系统就能拼出完整链路。1129 接口让你无需本地条码库即可出码、扫码。
## What：闭环构成
| 环节 | 动作 | 接入点 |
|----|----|----|
| 赋码 | 流水号/批次号 → 条码图 → 落盘归档 | 1129-1 |
| 采集 | 环节扫码图 → 文字 | 1129-2/3/4 |
| 比对 | 识别文字与追溯库比对、写节点 | 你的系统 |
## How：赋码 + 出入库核验（Python）
```python
import requests, os
APPKEY = "YOUR_APPKEY"
os.makedirs("trace", exist_ok=True)
def issue_code(serial: str, fmt: str = "5"):
r = requests.post(
f"https://route.showapi.com/1129-1?appKey={APPKEY}",
data={"content": serial, "formatType": fmt, "width": "150", "height": "40"},
timeout=10,
).json().get("showapi_res_body", {})
if r.get("ret_code") != "0" or not r.get("imgUrl"):
return None
img = requests.get(r["imgUrl"], timeout=10).content
p = f"trace/{serial}.jpg"
with open(p, "wb") as f: f.write(img) # 归档，供追溯系统引用
return p
def scan(serial_img_url: str) -> str | None:
r = requests.post(
f"https://route.showapi.com/1129-3?appKey={APPKEY}",
data={"imgUrl": serial_img_url}, timeout=10,
).json().get("showapi_res_body", {})
return r.get("retText") if r.get("ret_code") == "0" else None
# 出厂赋码
archived = issue_code("LOT2026-0001-A1")
# 入库核验
scanned = scan("https://your-cdn.com/inbound/LOT2026-0001-A1.png")
print("核验:", "通过" if scanned == "LOT2026-0001-A1" else "不符")
```
cURL（核验）：
```bash
curl -X POST "https://route.showapi.com/1129-3?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "imgUrl=https%3A%2F%2Fyour-cdn.com%2Finbound%2FLOT2026-0001-A1.png"
```
Node.js（核验）：
```javascript
const APPKEY = "YOUR_APPKEY";
const body = new URLSearchParams({ imgUrl: "https://your-cdn.com/inbound/LOT2026-0001-A1.png" });
const res = await fetch(`https://route.showapi.com/1129-3?appKey=${APPKEY}`, {
method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body
});
console.log((await res.json()).showapi_res_body.retText);
```
## 返回示例与解析
```json
{ "showapi_res_body": { "retText": "LOT2026-0001-A1", "ret_code": "0" } }
```
## 进阶 / 边界
- **编码承载**：`content` 建议用你系统内的唯一码（流水/批次），长度与字符集需匹配所选格式（如 CODE_128 兼容广）。
- **归档而非直连**：追溯系统存"落盘后的条码图地址"与对应编码映射，原 `imgUrl` 12h 失效不能做长期字段。
- **高并发采集**：无批量/订阅端点，大流量用消息队列削峰 + 有限重试，思路见 [错误排查指南](https://www.showapi.com/guides/barcode-error-handling-1129)。
## FAQ
**Q：一物一码用哪种格式好？**
内部追溯常用 CODE_128(formatType=5)，字符集兼容性强；若需对外零售兼容可用 EAN_13(2)。具体以你的扫码设备为准。
**Q：追溯链要存哪些数据？**
至少存"编码 ↔ 落盘图地址 ↔ 各环节扫描记录（时间/工位/操作人）"；图片用落盘地址，不用 `imgUrl`。
**Q：识别不一致怎么处理？**
先确认图片质量，重试一次仍不符则标记为异常件转人工复核，不要自动放行。
**Q：能生成二维码存更多追溯信息吗？**
本文接口 13 种格式不含 QR Code（含 PDF_417 堆叠式二维）；需要 QR 请另寻对应接口或扩展方案。
## 相关能力 / 下一步阅读
- [条码生成图片 12 小时过期：缓存与本地落盘保存策略](https://www.showapi.com/guides/barcode-image-expiry-1129)
- [仓储入库如何用条码识别接口做扫码核验（含三种传图方案）](https://www.showapi.com/guides/barcode-recognize-wms-1129)
- [条码生成与识别：13 种条码格式（formatType）对照与选型指南](https://www.showapi.com/guides/barcode-format-types-1129)
- **本系列共 12 篇**：查看[条码生成与识别指南总目录](https://www.showapi.com/guides/barcode-guides-1129)
