服务商接单前先看：客户最常要的 8 个数据字段（附 python 源码）

接单最容易亏钱的地方不是报价报低了，是字段没问清。

我们踩过一次。客户说"我要商品的销量"，我们说"有"。交付那天他把数据接进选品系统，两周后打电话来：排序是乱的，销量高的排不上去。他要的是近 30 天销量，我们给的是累计销量——一个卖了三年但最近没人买的老品，累计销量五万，排在新品前面。

这个锅没法甩。合同里写的是"销量"，我们确实提供了"销量"。

后来我们把这件事做成了一张表：客户说的字段名，和数据库里的字段，是两个东西，中间必须翻译一次。这篇就把最常见的八个字段的翻译写出来，附一段可以跑的自检代码，接单前先跑一遍。

一、八个字段，三类落差

先说结论：这八个字段之所以容易出事，不是因为接口难，是因为它们在三个不同的地方让客户失望。

落差类型	客户什么时候失望	字段
口径落差	拿到数了，但和以为的不是一回事	价格、库存、销量
形态落差	拿到东西了，但塞不进他的系统	SKU 属性、图片、物流编码
合规落差	拿到东西了，但不能随便用	收件信息、商品标题

口径落差最危险，因为数据看起来是对的。五万销量确实是销量，不会报错，不会异常，只有业务逻辑错了才发现。
形态落差最费工，报价时按"给个字段"算的，实际要做一次转换层。
合规落差最容易变成法律问题，也是最容易被服务商忽略的一类。

下面逐个说，每个字段给三样：客户通常怎么说、你该追问什么、最贵的那个坑。

二、口径落差：数是对的，但意思不对

1. 价格

客户说"价格"的时候，脑子里可能是六种东西之一：

客户说的	实际对应的字段
页面价格	标价（`price`）
现在买多少钱	促销价 / 活动价（`promotion_price`）
我实际付多少	到手价 = 促销价 − 店铺券 − 平台券 + 运费
会员多少钱	会员价（部分平台单独返回，多数要自己算）
批发多少钱	1688 阶梯价，按起订量取档
含税多少钱	多数平台不含税，需要自己加

该追问的三句：

含不含券？含不含运费？
会员价要不要单独一列，还是并进到手价？
是给用户看，还是给财务算账？（前者要到手价，后者要标价+优惠明细，能对得上账）

最贵的坑：促销价没有时效字段。客户按促销价算了一个月的利润，活动结束了数据还在返回促销价，利润表对不上，回来找你查一周。第 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 只认两列。

该追问的两句：

要"颜色/尺码"这两列，还是要完整属性集（含材质、产地、执行标准）？
属性值要不要标准化？客户系统里是"黑色"，平台给的是"黑色/深黑/曜石黑"，不统一就合并不了。

最贵的坑：属性值不稳定。同一个商品，这次返回"黑色"，下次商家改了叫"经典黑"，你的 SKU 匹配逻辑就断了。做组合装、做对账的客户会遇到"同一个 SKU 变成两个"。

5. 图片

客户说"给我图片链接"，他以为拿到 URL 就能用。实际有三个坑：

防盗链：1688 的图片直接外链会 403，必须转存到自己的存储
尺寸：主图有 800×800、1200×1200 多个规格，详情图是长图（可能 750×8000）
有效期：部分 CDN 链接带签名参数，过期就失效

该追问的一句：你是要链接，还是要文件？

要链接，你得保证这个链接在他那边能打开、能长期打开；要文件，你得做转存，这是存储成本和带宽成本，报价时必须算进去。

最贵的坑：交付了链接，客户上线一个月后图片全挂。原因是 CDN 签名过期。这种事不报错，就是图片一个个变成灰块，客户发现的时候往往是客户投诉商品页打不开。

6. 物流编码

客户说"物流状态"，实际拿到的是 WAIT_SELLER_SEND_GOODS、STOP_ONE_STAGE、GOT 这一堆东西，三个平台三套编码，同一个"已揽收"在三家可能叫三个名字。

更要命的是节点的粒度不一样：有的平台给你 7 个状态，有的给你 20 个子状态（运输中、到达分拨中心、离开分拨中心……）。

该追问的一句：你要几个状态？

做客服系统的客户要细（"包裹现在在哪"），做订单看板的客户要粗（"发出/在途/签收"）。给粗了客服答不了，给细了客户系统没有对应字段，会全部落到"其他"。

最贵的坑：只给原始编码，不给映射后的标准状态。客户得自己写映射表，写完还得跟着平台改。这个工作量不小，而且一旦映射错了，"已签收"被当成"在途"，自动确认收货的逻辑就永远不触发。

四、合规落差：拿到了，但不能随便用

7. 收件信息

这个字段是八个里唯一会让你承担法律责任的。

客户说"我要订单的收件人姓名、电话、地址"，多数平台返回的是脱敏值：

收件人：张*
手机：138****1234
地址：浙江省杭州市西湖区****

要拿到明文，得走解密接口，而且要单独申请权限、有调用额度限制、有审计日志。这不是技术门槛，是平台在履行个人信息保护义务。

该追问的两句：

你要明文干什么？（发货打单可以，做用户画像不行）
你有没有做过去标识化处理？

最贵的坑：服务商把明文收件信息落库、落日志、甚至缓存到 Redis 里，客户的数据泄露了，追责链条上是你。第 18 篇讲数据服务的风险传导，这一条是最短的那根引线：你手里有十万条真实手机号，出事的时候没有"我只是个技术供应商"这种说法。

建议做法：明文只在内存里过一遍，直接推给客户的打单接口，不落库、不打日志。日志里要有 138****1234 这种打码，而不是全量。

8. 商品标题

客户说"标题照搬过来就行"，你照搬了，然后被平台驳回。

标题里的雷有四个：

极限词："最"、"第一"、"国家级"——违反广告法，平台会拦
平台痕迹："淘宝爆款"、"天猫同款"、"京东专供"——跨平台铺货必挂
促销词："【限时秒杀】"、"满 199 减 50"——价格变了标题没变，属于虚假宣传
他人商标：品牌词没授权就写上去

该追问的一句：这个标题你是要原样展示，还是要重新发布？

原样展示（做比价、做监控）没问题，但要注意展示合规；重新发布（铺货）必须清洗，第 5 篇那套正则就是干这个的。

最贵的坑：清洗时删词不删句。"【爆款】不锈钢保温杯 500ml 大容量"，删掉"【爆款】"就好，别把整句重写——重写会丢规格词，500ml 变成"大容量"，客户那边同款匹配全乱。

五、代码：字段契约 + 填充率探测

上面八个字段的问题是"说不清"，代码解决的是"说不清就没法验收"。

思路：把每个字段写成一份契约（客户可能怎么叫、对应哪几个实际字段、口径是什么、填充率下限多少），然后拿真实数据跑一遍，输出一份可以直接发给客户的报告。

5.1 字段契约

# 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 填充率探测

这段是整篇最实用的部分。多数人接单只验证"接口通不通、字段在不在"，但真正让客户失望的是字段在，值是空的。

# 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()


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)

# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
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 两百行出头，但它比任何一份字段文档都更能避免交付期的争执——因为它测的不是字段存不存在，是字段有没有值，值是什么口径。

如果你正在评估要不要自己接这三个平台，或者手上有一批客户需求要报，可以拿这套契约模板去套一遍。跑完你会知道哪些能承诺、哪些要提前说清——这个清单本身就是报价的依据。

有具体的字段拿不准口径，也可以直接问我们，我们把三平台的对照表摊开一起看。

服务商接单前先看：客户最常要的 8 个数据字段（附 python 源码）

服务商接单前先看：客户最常要的 8 个数据字段（附 python 源码）

一、八个字段，三类落差

二、口径落差：数是对的，但意思不对

1. 价格

2. 库存

3. 销量

三、形态落差：东西给了，但塞不进去

4. SKU 属性

5. 图片

6. 物流编码

四、合规落差：拿到了，但不能随便用

7. 收件信息

8. 商品标题

五、代码：字段契约 + 填充率探测

5.1 字段契约

5.2 填充率探测

六、接单前该给客户的三张纸

七、最后一句

数据库

热门文章

最新文章

相关电子书