品

品源 · 开发者接入

产品数据基础设施 / Product Data Infrastructure for Agentic Commerce

品源把商家的产品与服务资料，整理成机器能直接读的一份事实。你要做的是接一次协议，而不是挨家适配 —— 这份协议是公开的、自描述的、可自证的。

为什么接品源省事

自描述/api/v1/schema 免鉴权返回全部字段、类型、级别、单位、以及逐版本变更段 —— 不用等人发文档，读到什么就是什么。

可自证一致性套件 32 条（A–G 七组，含 ACT CID-MER-CAT 目录口与能力发现口），你自己跑它来证明你的实现兼容（不是我们说了算）。

一份事实源字段口径、完整度、门槛各有唯一实现；出库面与文档同源，不会"文档写 38、接口出 39"。

兼容承诺什么算破坏性变更、弃用多久，写在 COMPATIBILITY.md 里。整数仍出整数这类承诺有字节级测试。

三步跑通

# 1) 读规范（不需要任何凭据）
curl -s https://pinyuan.sxai77.cn/api/v1/schema | head -40

# 2) 自证兼容（第三方拿这份套件跑自己的实现）
#    对参考实现的本机实测（2026-10-15 · 带钥 · 只读）：32 条 → 通过 28 / 失败 1 / 跳过 3
#    那 1 条是本机 DEBUG=True 下 Django 绕过自定义 handler404 的已知假红（判据会自己打印病因）
python3 conformance.py --base https://pinyuan.sxai77.cn --i-know-its-remote

# 3) 带渠道钥取数据（钥由平台签发，每家店/每个渠道一把，库内只存哈希）
curl -s -H "X-Channel-Key: $PY_CHANNEL_KEY" \
  "https://pinyuan.sxai77.cn/api/v1/channel/products?store=st0001" | head -60

出库面（渠道口，需 `X-Channel-Key`）

GET /api/v1/channel/products —— 商品与服务（关键词/类目/标签/价格上限/类型/完整度档；游标翻页）
GET /api/v1/channel/stores —— 本钥可见的店目录
GET /api/v1/channel/products-batch —— 跨店批量取数（单批 ≤ 20 家）
POST /api/v1/channel/stock_report —— 报销量扣库存（幂等：带 request_id 重复上报只生效一次；批次按过期日先出）
GET /api/v1/channel/moves —— 库存流水对账（日对账用）
GET /api/v1/channel/categories · field-rules · events（商品级事件上报）
GET /api/v1/channel/aggregate —— 跨商家聚合：已实现并对外可用（200）；独立店数低于门槛 k_min=10 时一个数都不出（sample_ok:false），只出统计不出个体，且只纳入显式 opt-in 的商家

兼容性承诺（摘要）

兼容：新增键 / 新增字段 / 新增端点 / 精度提高。
破坏性：删键、改类型、收紧校验、把可选变必填 —— 必须走 vN 段 + 弃用周期。
数字类型：数量支持小数，但整数值一律出 JSON int（148 不会变成 148.0）。
聚合：只出统计不出个体；样本不足（独立店数 < 10）一个数值都不给。

许可

协议文档与工具（docs/ + tools/）按 LICENSE 宽松授权，允许你自由实现兼容客户端；品源自身的服务端实现不在该许可范围内。

下载 / 在线阅读

PROTOCOL.md（规范正文） COMPATIBILITY.md（兼容与弃用） DATA-USE.md（数据使用条款要点）用户协议（服务条款）隐私政策（数据处理说明） conformance.py（一致性套件） pyclient.py（参考客户端） tools/README.md LICENSE

拿渠道密钥

渠道密钥由平台签发（明文只在签发时显示一次，库内只存哈希；可限流、可限定可见店铺、可停用）。接入或联调请联系品源，或从官网了解产品： sxai77.cn。