# 服务商接单前先看：客户最常要的 8 个数据字段（附 python 源码）
接单最容易亏钱的地方不是报价报低了，是**字段没问清**。
我们踩过一次。客户说"我要商品的销量"，我们说"有"。交付那天他把数据接进选品系统，两周后打电话来：排序是乱的，销量高的排不上去。他要的是**近 30 天销量**，我们给的是**累计销量**——一个卖了三年但最近没人买的老品，累计销量五万，排在新品前面。
这个锅没法甩。合同里写的是"销量"，我们确实提供了"销量"。
后来我们把这件事做成了一张表：**客户说的字段名，和数据库里的字段，是两个东西，中间必须翻译一次**。这篇就把最常见的八个字段的翻译写出来，附一段可以跑的自检代码，接单前先跑一遍。
## 一、八个字段，三类落差
先说结论：这八个字段之所以容易出事，不是因为接口难，是因为它们在三个不同的地方让客户失望。
| 落差类型 | 客户什么时候失望 | 字段 |
| -------- | --------------- | -------------- |
| **口径落差** | 拿到数了，但和以为的不是一回事 | 价格、库存、销量 |
| **形态落差** | 拿到东西了，但塞不进他的系统 | SKU 属性、图片、物流编码 |
| **合规落差** | 拿到东西了，但不能随便用 | 收件信息、商品标题 |
口径落差最危险，因为**数据看起来是对的**。五万销量确实是销量，不会报错，不会异常，只有业务逻辑错了才发现。
形态落差最费工，报价时按"给个字段"算的，实际要做一次转换层。
合规落差最容易变成法律问题，也是最容易被服务商忽略的一类。
下面逐个说，每个字段给三样：客户通常怎么说、你该追问什么、最贵的那个坑。
## 二、口径落差：数是对的，但意思不对
### 1. 价格
客户说"价格"的时候，脑子里可能是六种东西之一：
| 客户说的 | 实际对应的字段 |
| ------ | ---------------------------- |
| 页面价格 | 标价（`price`） |
| 现在买多少钱 | 促销价 / 活动价（`promotion_price`） |
| 我实际付多少 | 到手价 = 促销价 − 店铺券 − 平台券 + 运费 |
| 会员多少钱 | 会员价（部分平台单独返回，多数要自己算） |
| 批发多少钱 | 1688 阶梯价，按起订量取档 |
| 含税多少钱 | 多数平台不含税，需要自己加 |
**该追问的三句**：
1. 含不含券？含不含运费？
2. 会员价要不要单独一列，还是并进到手价？
3. 是给用户看，还是给财务算账？（前者要到手价，后者要标价+优惠明细，能对得上账）
**最贵的坑**：促销价没有时效字段。客户按促销价算了一个月的利润，活动结束了数据还在返回促销价，利润表对不上，回来找你查一周。第 13 篇讲过价格要建模成带 `promo_end` 的对象，这是同一个问题的另一面——**服务商交付时如果只给一个数字，就必须同时给这个数字的有效期**。
### 2. 库存
客户说"库存"，实际可能是：
- **总库存**：仓库里有多少件
- **可售库存**：总库存 − 已占用 − 安全库存，这才是"还能卖几件"
- **锁定库存**：下单未付款占用的
- **在途库存**：采购中，还没入库
这四个数能差出好几倍。做活动备货的客户要总库存，做防超卖的客户要可售库存，两个数给错了都是事故。
**该追问的一句**：你要的是"还剩几件"，还是"还能卖几件"？
**最贵的坑**：1688 没有 SKU 库存这个概念。它的业务模型是按起订量阶梯卖，返回的是商品的**可售状态**，不是一个数字。你用淘宝的思维去接，适配器里会写一句"忽略 sku_id，返回总量"——**调用方以为拿到了 SKU 库存，实际上是错的，而且不报错**。第 8 篇把这叫"假装都支持"，在我看来这是服务商最容易犯的错：不是不会做，是不好意思说不支持。
### 3. 销量
这个字段水最深，因为三个平台给的东西根本不是一回事：
| 平台 | 通常返回 | 说明 |
| ---- | --------------------- | ----------------- |
| 淘宝 | 累计销量（`sold_quantity`） | 商品生命周期累计，老品数字很大 |
| 京东 | 评价数为主，销量部分类目不返回 | 很多接口根本不给你销量 |
| 1688 | 成交件数 / 成交笔数 | 批发的"笔"和零售的"件"完全不同 |
**该追问的一句**：这个销量你拿去干什么？
答案决定你该给什么：
- **排序/选品** → 用**评价增速**或**近 N 天增量**，比累计销量准得多。累计销量对老品有严重偏袒。
- **备货预测** → 必须近 30 天，而且要和退货率一起给，不然备多了。
- **给客户看**（比如"本店已售 10 万件"）→ 累计销量就够，甚至平台前台展示的那个数就行。
**最贵的坑**：**答应了给"月销"，实际平台只给累计**。这种承诺在售前最容易出口，因为客户问的时候你觉得"销量不就是销量"。交付时你只能自己算：`累计(t) − 累计(t−30d)`。这需要你从接单第一天就开始存历史快照——**如果你第三个月才想起来算，前三个月的数据永远补不回来**。
## 三、形态落差：东西给了，但塞不进去
### 4. SKU 属性
客户说"我要颜色和尺码两列"，听起来像是在表格上加两列。实际拿到的是这个：
```
1627207:28320:颜色分类:黑色;1627208:34117:尺码:M
```
这是淘宝的属性串格式：`属性ID:值ID:属性名:值`，多组用分号隔开。京东是另一套结构（对象数组），1688 又是另一套（带 `skuId` 和自定义属性）。
三个平台三种给法，这就是"必须做归一化"的全部理由——不是洁癖，是客户的 ERP 只认两列。
**该追问的两句**：
1. 要"颜色/尺码"这两列，还是要完整属性集（含材质、产地、执行标准）？
2. 属性值要不要标准化？客户系统里是"黑色"，平台给的是"黑色/深黑/曜石黑"，不统一就合并不了。
**最贵的坑**：**属性值不稳定**。同一个商品，这次返回"黑色"，下次商家改了叫"经典黑"，你的 SKU 匹配逻辑就断了。做组合装、做对账的客户会遇到"同一个 SKU 变成两个"。
### 5. 图片
客户说"给我图片链接"，他以为拿到 URL 就能用。实际有三个坑：
1. **防盗链**：1688 的图片直接外链会 403，必须转存到自己的存储
2. **尺寸**：主图有 800×800、1200×1200 多个规格，详情图是长图（可能 750×8000）
3. **有效期**：部分 CDN 链接带签名参数，过期就失效
**该追问的一句**：你是要**链接**，还是要**文件**？
要链接，你得保证这个链接在他那边能打开、能长期打开；要文件，你得做转存，这是存储成本和带宽成本，报价时必须算进去。
**最贵的坑**：交付了链接，客户上线一个月后图片全挂。原因是 CDN 签名过期。这种事不报错，就是图片一个个变成灰块，客户发现的时候往往是客户投诉商品页打不开。
### 6. 物流编码
客户说"物流状态"，实际拿到的是 `WAIT_SELLER_SEND_GOODS`、`STOP_ONE_STAGE`、`GOT` 这一堆东西，三个平台三套编码，同一个"已揽收"在三家可能叫三个名字。
更要命的是**节点的粒度不一样**：有的平台给你 7 个状态，有的给你 20 个子状态（运输中、到达分拨中心、离开分拨中心……）。
**该追问的一句**：你要几个状态？
做客服系统的客户要细（"包裹现在在哪"），做订单看板的客户要粗（"发出/在途/签收"）。给粗了客服答不了，给细了客户系统没有对应字段，会全部落到"其他"。
**最贵的坑**：**只给原始编码，不给映射后的标准状态**。客户得自己写映射表，写完还得跟着平台改。这个工作量不小，而且一旦映射错了，"已签收"被当成"在途"，自动确认收货的逻辑就永远不触发。
## 四、合规落差：拿到了，但不能随便用
### 7. 收件信息
这个字段是八个里唯一会让你承担法律责任的。
客户说"我要订单的收件人姓名、电话、地址"，多数平台返回的是**脱敏值**：
```
收件人：张*
手机：138****1234
地址：浙江省杭州市西湖区****
```
要拿到明文，得走**解密接口**，而且要单独申请权限、有调用额度限制、有审计日志。这不是技术门槛，是平台在履行个人信息保护义务。
**该追问的两句**：
1. 你要明文干什么？（发货打单可以，做用户画像不行）
2. 你有没有做过去标识化处理？
**最贵的坑**：服务商把明文收件信息落库、落日志、甚至缓存到 Redis 里，客户的数据泄露了，追责链条上是**你**。第 18 篇讲数据服务的风险传导，这一条是最短的那根引线：你手里有十万条真实手机号，出事的时候没有"我只是个技术供应商"这种说法。
建议做法：明文只在内存里过一遍，直接推给客户的打单接口，**不落库、不打日志**。日志里要有 `138****1234` 这种打码，而不是全量。
### 8. 商品标题
客户说"标题照搬过来就行"，你照搬了，然后被平台驳回。
标题里的雷有四个：
1. **极限词**："最"、"第一"、"国家级"——违反广告法，平台会拦
2. **平台痕迹**："淘宝爆款"、"天猫同款"、"京东专供"——跨平台铺货必挂
3. **促销词**："【限时秒杀】"、"满 199 减 50"——价格变了标题没变，属于虚假宣传
4. **他人商标**：品牌词没授权就写上去
**该追问的一句**：这个标题你是要**原样展示**，还是要**重新发布**？
原样展示（做比价、做监控）没问题，但要注意展示合规；重新发布（铺货）必须清洗，第 5 篇那套正则就是干这个的。
**最贵的坑**：清洗时**删词不删句**。"【爆款】不锈钢保温杯 500ml 大容量"，删掉"【爆款】"就好，别把整句重写——重写会丢规格词，500ml 变成"大容量"，客户那边同款匹配全乱。
## 五、代码：字段契约 + 填充率探测
上面八个字段的问题是"说不清"，代码解决的是"说不清就没法验收"。
思路：把每个字段写成一份**契约**（客户可能怎么叫、对应哪几个实际字段、口径是什么、填充率下限多少），然后拿真实数据跑一遍，输出一份可以直接发给客户的报告。
### 5.1 字段契约
```python
# contract.py
"""字段契约：接单前和客户确认的内容，落成代码。
每条契约四件事：
aliases 客户可能怎么叫（用于把需求清单映射到契约）
candidates 我方数据里可能对应的字段路径（按优先级）
semantic 口径说明——这句要写进合同附件
min_fill 填充率下限，低于此值必须在报价前告知客户
"""
FIELDS = {
"price": {
"label": "价格",
"aliases": ["价格", "售价", "单价", "页面价", "标价"],
"candidates": ["price", "sku.price", "sku_list[0].price"],
"semantic": "商品标价，不含优惠券、不含运费；活动价见 promotion_price",
"must_ask": ["含不含券", "含不含运费", "会员价是否单列"],
"min_fill": 0.99,
},
"promo_price": {
"label": "促销价",
"aliases": ["活动价", "到手价", "现价", "最低价"],
"candidates": ["promotion_price", "sku.promotion_price"],
"semantic": "活动期内的成交价，必须与 promo_end 一起交付",
"must_ask": ["活动结束时间要不要一起给"],
"min_fill": 0.60, # 没活动的商品本来就没有，60% 是正常的
},
"stock": {
"label": "库存",
"aliases": ["库存", "剩余", "可售", "数量"],
"candidates": ["stock", "quantity", "sku.quantity"],
"semantic": "可售库存（已扣占用与安全库存），非仓库总库存",
"must_ask": ["要总库存还是可售", "1688 无 SKU 库存，是否接受商品级"],
"min_fill": 0.95,
},
"sales": {
"label": "销量",
"aliases": ["销量", "月销", "已售", "成交"],
"candidates": ["sold_quantity", "sales", "volume"],
"semantic": "累计销量，非近 30 天；近 30 天需历史快照计算",
"must_ask": ["用来排序还是备货", "能否接受累计口径"],
"min_fill": 0.80,
},
"sku_props": {
"label": "SKU 属性",
"aliases": ["规格", "颜色尺码", "SKU", "属性"],
"candidates": ["skus", "sku_list", "props"],
"semantic": "已归一为 {spec_name: spec_value} 结构；原始属性串另存 raw_props",
"must_ask": ["要两列还是要完整属性集", "属性值是否需标准化"],
"min_fill": 0.90,
},
"images": {
"label": "图片",
"aliases": ["主图", "详情图", "图片", "素材"],
"candidates": ["images", "pic_url", "item_imgs"],
"semantic": "已转存至自有存储的直链，非平台原始 CDN 地址",
"must_ask": ["要链接还是要文件", "主图还是详情长图"],
"min_fill": 0.98,
},
"logistics_status": {
"label": "物流状态",
"aliases": ["物流", "轨迹", "快递状态"],
"candidates": ["status", "trace_list[-1].status"],
"semantic": "已映射为 5 个标准状态；原始编码见 raw_status",
"must_ask": ["要几个状态粒度", "要不要节点时间"],
"min_fill": 0.85,
},
"receiver": {
"label": "收件信息",
"aliases": ["地址", "收件人", "电话", "收货信息"],
"candidates": ["receiver_name", "receiver_mobile", "receiver_address"],
"semantic": "默认脱敏值；明文需单独授权，仅透传不落库",
"must_ask": ["要明文做什么", "是否接受脱敏"],
"min_fill": 1.00,
},
"title": {
"label": "商品标题",
"aliases": ["标题", "名称", "商品名"],
"candidates": ["title", "name"],
"semantic": "原始标题，含营销词与平台痕迹；用于重新发布需清洗",
"must_ask": ["原样展示还是重新发布"],
"min_fill": 0.99,
},
}
```
（八个字段，契约里为什么有九条：`price` 和 `promo_price` 是同一个字段的两种口径，拆开写是因为**客户说"价格"的时候，你必须先问清是哪一个**。）
### 5.2 填充率探测
这段是整篇最实用的部分。多数人接单只验证"接口通不通、字段在不在"，但真正让客户失望的是**字段在，值是空的**。
```python
# probe.py
"""拿真实样本跑一遍，输出填充率、口径分布、字段可用性。
用法：
python probe.py --file sample.json # 本地样本回放
python probe.py --file sample.json --md # 输出 markdown 报告
样本格式：一个 JSON 数组，每个元素是一个商品/订单的原始返回。
"""
import argparse
import json
from collections import Counter
from decimal import Decimal, InvalidOperation
from pathlib import Path
from contract import FIELDS
MISSING = object()
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
def pick(obj, path):
"""按 "sku_list[0].price" 取值，取不到返回 MISSING（区别于 None）
为什么区分 MISSING 和 None：
key 不存在 = 我方没给这个字段（或没权限）
key 存在但值是 null = 平台没给（该商品不适用）
这两种在验收时是两回事，混在一起客服会答错。
"""
cur = obj
for seg in path.split("."):
if "[" in seg:
name, idx = seg.rstrip("]").split("[")
cur = cur.get(name, MISSING) if isinstance(cur, dict) else MISSING
if cur is MISSING:
return MISSING
try:
cur = cur[int(idx)]
except (IndexError, TypeError):
return MISSING
else:
if not isinstance(cur, dict) or seg not in cur:
return MISSING
cur = cur[seg]
return cur
def filled(v):
"""空值的判定比想象中麻烦：0 是有效值，空串不是"""
if v is MISSING or v is None:
return False
if isinstance(v, str):
return v.strip() != ""
if isinstance(v, (list, dict)):
return len(v) > 0
return True
def normalize_price(v):
"""价格比较必须用 Decimal，float 会把 19.9 和 19.90 判成不同"""
try:
return Decimal(str(v)).quantize(Decimal("0.01"))
except (InvalidOperation, TypeError, ValueError):
return None
def probe(samples, field_key):
spec = FIELDS[field_key]
stats = {p: 0 for p in spec["candidates"]}
samples_with_any = 0
values = Counter()
for row in samples:
hit = False
for path in spec["candidates"]:
v = pick(row, path)
if filled(v):
stats[path] += 1
hit = True
if field_key in ("price", "promo_price"):
d = normalize_price(v)
values[str(d) if d else str(v)] += 1
elif field_key == "sku_props" and isinstance(v, list):
values[f"{len(v)}个SKU"] += 1
if hit:
samples_with_any += 1
total = len(samples) or 1
fill = samples_with_any / total
# 只有命中率接近才叫"多口径并存"，否则就是主备关系
live = {p: c for p, c in stats.items() if c > 0}
return {
"label": spec["label"],
"fill": fill,
"ok": fill >= spec["min_fill"],
"min_fill": spec["min_fill"],
"hit": live,
"distinct": len(values),
"top_values": values.most_common(3),
"semantic": spec["semantic"],
"must_ask": spec["must_ask"],
}
def stability(a, b, field_key):
"""同一批样本拉两次，看字段值变了多少。
变了不一定是坏事（价格本来就该变），但要知道是哪个字段在变：
title / sku_props 频繁变 = 商家在改，你的匹配逻辑会断
price 变 = 正常，但交付时必须带更新时间
"""
spec = FIELDS[field_key]
path = spec["candidates"][0]
changed = 0
compared = 0
for x, y in zip(a, b):
vx, vy = pick(x, path), pick(y, path)
if not filled(vx) or not filled(vy):
continue
compared += 1
if vx != vy:
changed += 1
return changed / compared if compared else 0.0
def render(results, total_samples, n_days=None):
lines = [
f"# 字段可用性报告（样本 {total_samples} 条）",
"",
"| 字段 | 填充率 | 门槛 | 判定 | 备注 |",
"|---|---|---|---|---|",
]
for r in results:
mark = "通过" if r["ok"] else "**不足**"
if not r["ok"]:
note = "需在报价前告知客户"
elif r["distinct"] > 1:
note = f"{r['distinct']} 种取值" # 口径可能不唯一，值得问一句
else:
note = ""
if r.get("drift", 0) > 0.3:
note += f"；两次抽样差异 {r['drift']:.0%}"
lines.append(
f"| {r['label']} | {r['fill']:.1%} | {r['min_fill']:.0%} | {mark} | {note} |"
)
bad = [r for r in results if not r["ok"]]
if bad:
lines += ["", "## 需要提前说明的字段", ""]
for r in bad:
lines.append(f"**{r['label']}** 填充率 {r['fill']:.1%}，低于 {r['min_fill']:.0%}。")
lines.append(f"- 口径：{r['semantic']}")
lines.append(f"- 必须确认：{'；'.join(r['must_ask'])}")
lines.append("")
lines += ["", "## 各字段口径", ""]
for r in results:
lines.append(f"- **{r['label']}**：{r['semantic']}")
return "\n".join(lines)
def _pad(text, width):
"""中文占两格。str.ljust 按字符数补空格，表格会歪，必须按显示宽度算"""
w = sum(2 if ord(c) > 127 else 1 for c in text)
return text + " " * max(0, width - w)
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--file", required=True, help="样本 JSON 文件")
ap.add_argument("--compare", help="第二次抽样，用于比对字段漂移")
ap.add_argument("--md", action="store_true", help="输出 markdown 报告")
ap.add_argument("--out", default="field_report.md")
args = ap.parse_args()
samples = json.loads(Path(args.file).read_text(encoding="utf-8"))
if not isinstance(samples, list) or not samples:
raise SystemExit("样本必须是 JSON 数组，且不能为空")
results = [probe(samples, k) for k in FIELDS]
if args.compare:
later = json.loads(Path(args.compare).read_text(encoding="utf-8"))
for r, k in zip(results, FIELDS):
r["drift"] = stability(samples, later, k)
if args.md:
Path(args.out).write_text(render(results, len(samples)), encoding="utf-8")
print(f"已写出 {args.out}（{len(samples)} 条样本）")
return
print(_pad("字段", 14) + _pad("填充率", 10) + _pad("门槛", 8) + "判定")
print("-" * 46)
for r in results:
flag = "OK" if r["ok"] else "LOW"
line = (_pad(r["label"], 14) + _pad(f"{r['fill']:.1%}", 10)
+ _pad(f"{r['min_fill']:.0%}", 8) + flag)
if "drift" in r:
line += f" 漂移 {r['drift']:.0%}"
print(line)
if not r["ok"]:
print(f" └ {r['semantic']}")
if __name__ == "__main__":
main()
```
```
### 5.3 怎么用
三步，接单前跑完，只要半天：
```bash
# 1. 从客户的目标商品里抽 200 条，存成 sample.json
python dump_samples.py --shop shop_123 --limit 200 > sample.json
# 2. 跑一遍，先看哪些字段填不满
python probe.py --file sample.json
# 3. 隔一天再抽一次，看哪些字段在漂（可选，但强烈建议）
python probe.py --file sample.json --compare sample_day2.json
# 4. 生成报告，直接发给客户确认
python probe.py --file sample.json --md --out 字段确认单.md
```
输出大概是这样：
```
字段 填充率 门槛 判定
----------------------------------------
价格 100.0% 99% OK
促销价 62.5% 60% OK
库存 98.5% 95% OK
销量 41.0% 80% LOW
└ 累计销量，非近 30 天；近 30 天需历史快照计算
SKU 属性 93.0% 90% OK
图片 99.5% 98% OK
物流状态 86.0% 85% OK
收件信息 100.0% 100% OK
商品标题 100.0% 99% OK
```
那个 41% 就是这篇的价值。**如果你在报价前跑出这个数，就可以跟客户说"销量这个字段有一半商品拿不到，我们建议用评价增速替代，或者加价做历史快照"**。如果等交付了才发现，客户只会记住"你说有销量的"。
顺带一个观察：跑完这份报告，你会发现自己对数据的了解比读三天文档还多。文档告诉你字段存在，报告告诉你字段**有值**。
## 六、接单前该给客户的三张纸
代码解决的是"我知道"，三张纸解决的是"客户知道"。少一张，后面就会有一次扯皮。
**第一张：字段确认单**
就是上面代码生成的那份报告，每个字段要写清四件事：口径（一句话）、示例值（真的从数据里取的）、填充率、更新频率。**示例值必须是真的**，从样本里截一段；自己编的示例，客户拿去验证会发现对不上。
**第二张：不保证清单**
这张最容易被跳过，也最保命。写清楚哪些事不承诺：
- 平台字段变更不另行通知，但我们会在 24 小时内适配
- 部分类目的可选属性，不保证有值
- 历史数据只能从接入日开始（除非另行采购）
- 平台侧的限流、审核、政策变化导致的延迟，不算 SLA 违约
**第三张：验收标准**
不要写"以客户满意为准"，要写成可测的：
- 字段准确率 ≥ 99.5%（抽 50 条人工比对）
- 主键准确率 100%（`item_id` / `order_id` 不能错，错了就是数据串店）
- 填充率达到确认单标注的门槛
- 数据延迟 ≤ N 分钟（P95）
这三张纸加起来不到两页，但它们把"你当时说的是这个意思"这类争执，提前到签约之前解决。
## 七、最后一句
这八个字段里，没有一个技术上难。它们难在**客户用的词和系统里的字段之间，隔着一层业务理解**。
服务商真正卖的不是接口访问权，是这层翻译。翻译得好，客户觉得你懂他的业务；翻译得不好，你会一直在解释"我给你的确实是销量"。
而翻译这件事，是可以提前做、并且用代码验证的。上面那段 `probe.py` 两百行出头，但它比任何一份字段文档都更能避免交付期的争执——**因为它测的不是字段存不存在，是字段有没有值，值是什么口径**。
如果你正在评估要不要自己接这三个平台，或者手上有一批客户需求要报，可以拿这套契约模板去套一遍。跑完你会知道哪些能承诺、哪些要提前说清——这个清单本身就是报价的依据。
有具体的字段拿不准口径，也可以直接问我们，我们把三平台的对照表摊开一起看。
