文章目录[隐藏]
摘要： 京东联盟平台为了增强数据安全、管理能力和用户体验，计划对联盟侧的商品ID进行全面升级为“联盟商品ID”，其具有动态变化、区分于京东主站商品ID的特点。升级后，联盟商品ID将采用字符串形式，并分为A段和B段，其中A段每次请求会变，而B段在特定条件下保持不变。从2024年3月6日起，开放平台API接口将同时支持京东主站商品ID和联盟商品ID，并引入场景ID概念以适应不同业务场景。从2024年4月起，非企业认证及部分订单转化率低的媒体需仅使用联盟商品ID。此外，文档详细说明了涉及的API接口改造内容，包括新增接口、调整接口以及下线接口，明确指出各个接口在场景ID、入参和出参方面的具体变化。联盟还提供了详细的切换节奏计划和常见问题解答，协助各联盟媒体顺利过渡到新商品ID系统。
联盟商品ID切换白皮书（持续更新中）
亲爱的联盟媒体，您好！
为了提升京东联盟平台相关服务的数据安全、管理能力，优化体验，京东联盟平台近期将对平台商品ID进行升级（以下简称“联盟商品ID”）。本次商品ID升级仅为京东联盟侧升级，京东主站的商品ID暂不受本次升级影响（京东APP 12.3.2版本及以后，京东APP复制商品链接，均为“https://3.cn/XXXXX”形式）。
一、 商品ID核心变动
|
分类 |
升级前 京东主站商品ID |
升级后 联盟商品ID |
|
示例 |
123456789 |
VgDXlT9hVVVmDDiCbofTFhV7_VIfTFhV7VVyGGPNs |
|
类型 |
数字串 （API字段类型：number） |
字符串 （API字段类型：string） |
- 联盟商品ID将区别于京东主站商品ID，仅在京东联盟业务场景内流通：由静态数字变为动态变化的字符串，推客每次进行转链、获取物料等交互行为商品ID均会发生变化。
- 联盟商品ID长度变化：分为A段和B段，用 “_” 链接，不超过50个字符，示例：VgDXlT9hVVVmDDiCbofTFhV7_VIfTFhV7VVyGGPNs
- 联盟商品ID规则变化：A段为每次请求都会变更，B段为对同unionid（招商团长则为团长ID）和商品在特定范围内不变（范围可能有周期等因素）。（注：特定范围内不变目前不需要关注，正常情况不会变，但如果有数据泄露或安全风控事件，必须要遵循京东联盟相关安全策略）
- 商品链接变化：升级后商品链接：https://jingfen.jd.com/detail/{联盟商品ID}.html（该链接支持搜索商品信息、转链）
二、联盟商品ID升级说明
- 从2024年3月6日起，京东联盟开放平台API接口，均会支持京东主站商品ID（skuid）和联盟商品ID（itemId）的出入参，详细参见：五、本次升级所涉及的API及字段改造说明
- 联盟商品ID需结合不同业务场景使用，根据不同业务场景引入“场景ID”概念，涉及推广物料、转链、订单查询等核心接口的出入参变动，并且场景ID的使用需要符合对应的场景使用规范。详细参见：三、业务场景介绍与场景ID使用说明
- 联盟商品ID字段兼容（新字段，string类型）：为保障您调用开发平台API服务不受影响，您需要对您内部系统的字段类型进行调整，根据实际业务场景兼容京东主站商品ID和联盟商品ID。逾期未完成调整，调用开放平台API接口时将可能会出现异常；
- 业务系统需兼容联盟商品ID流通及数据分析：从2024年3月起，联盟商品ID升级陆续灰度，京东联盟陆续会有升级后的联盟商品ID开始流通进入生态；
- 从2024年4月起，非企业认证的媒体和部分接口调用量订单转化率低的媒体，京东联盟所有开放平台API接口都仅支持完整的全新的联盟商品ID出入参。未来京东联盟所有开放平台API接口都将仅支持完整的全新的联盟商品ID出入参。详细参见：六、首批联盟商品ID切换计划
- 京东联盟PC端、京粉APP不受本次升级影响
三、业务场景介绍与场景ID使用说明
|
场景类型 |
场景ID |
类型介绍 |
相关接口说明 |
|
常规场景 |
场景ID=1 |
常规联盟商品ID推广转链/查询信息，如导购转链、采集群商品获取后转链的场景 |
仅支持联盟商品ID出入参 |
|
商品库导购场景 |
针对部分媒体自己建立独立的小规模商品库，需要针对商品库进行管理，并针对商品库内的商品直接导购推广的场景 |
己建立独立的小规模商品库，建议保存联盟商品ID的A段+B段参数，通过B段去重管理（同一个unionid下同一个商品在特定范围内B段参数保持不变），接口入参必须入参联盟商品ID的A段+B段完整参数 |
|
|
消费者比价场景 |
场景ID=2 |
针对消费者返利，即需要支持消费者复制京东主站商品链接（如：https://3.cn/XXXXX）查询是否存在返利的场景 |
同时支持京东主站商品ID和联盟商品ID出入参 |
- 【常规场景】规范使用说明
场景说明：若无其他特殊业务场景，常规联盟商品ID推广转链/查询信息，如导购转链、采集群商品获取后转链的场景。该场景ID使用规则如下:
本场景ID的api入参参数，即sceneId=1（本场景无需单独申请权限）
- 使用API查询链接对应商品信息时：
keyword字段，仅支持入参完整的联盟商品ID、升级后的联盟商品链接：https://jingfen.jd.com/detail/{联盟商品ID}.html、通过联盟商品ID转链后的联盟链接：https://u.jd.com/XXXXXX 进行信息查询，此时需入参sceneId=1。
- 使用API批量查询商品信息时：
itemIds字段：仅支持入参完整的联盟商品ID进行信息查询，此时需入参sceneId=1。
- 使用API转链商品时：
materialId字段，仅支持入参完整的联盟商品ID、升级后的联盟商品链接：https://jingfen.jd.com/detail/{联盟商品ID}.html、转链后的联盟链接：https://u.jd.com/XXXXXX 进行转链，此时需入参sceneId=1。
（具体所涉及的API及字段使用说明，详细参见五、本次升级所涉及的API及字段改造说明）
- 【商品库导购场景】规范使用说明
场景说明：针对部分媒体自己建立独立的小规模商品库，需要针对商品库进行管理，并针对商品库内的商品直接导购推广的场景。该场景ID使用规则如下:
本场景ID的api入参参数，即sceneId=1（本场景无需单独申请权限）
- 已建立小规模商品库，需要将原京东主站商品ID，升级为联盟商品ID：
可申请联盟商品ID获取API（需联系对接商务申请，且仅限短期支持，具体所涉及的API及字段使用说明，详细参见五、本次升级所涉及的API及字段改造说明），可支持商品库内的京东主站商品ID，批量转换出联盟商品ID，将其中A段+B段参数均替换保存管理。
- 匹配商品库商品时：
通过联盟商品ID的B段匹配商品，同一个unionid下同一个商品在特定范围内B段参数保持不变
- 使用API查询链接对应商品信息时：
keyword字段，仅支持入参完整的联盟商品ID、升级后的联盟商品链接：https://jingfen.jd.com/detail/{联盟商品ID}.html、通过联盟商品ID转链后的联盟链接：https://u.jd.com/XXXXXX 进行信息查询，此时需入参sceneId=1。
- 使用API批量查询商品信息时：
itemIds字段：仅支持入参完整的联盟商品ID进行信息查询，此时需入参sceneId=1。
- 使用API转链商品时：
materialId字段，仅支持入参完整的联盟商品ID、升级后的联盟商品链接：https://jingfen.jd.com/detail/{联盟商品ID}.html、通过联盟商品ID转链后的联盟链接：https://u.jd.com/XXXXXX 进行转链，此时需入参sceneId=1。
（具体所涉及的API及字段使用说明，详细参见五、本次升级所涉及的API及字段改造说明）
- 【消费者比价场景】规范使用说明
场景说明：针对消费者返利，即需要支持消费者复制京东主站商品链接（如：https://3.cn/XXXXX）查询是否存在返利的场景。该场景ID使用规则如下:
本场景ID的api入参参数，即sceneId=2（本场景需单独申请权限）
- 使用API查询链接对应商品信息时：
keyword字段，支持入参京东主站商品ID 进行信息查询，此时需入参sceneId=2。
记录出参itemId字段的B段参数，以便与订单明细中的itemId字段的B段参数匹配商品信息
- 使用API批量查询商品信息时：
支持入参完整的京东主站商品ID（skuIds字段）进行信息查询，此时需入参sceneId=2。
- 使用API转链商品时：
materialId字段，支持京东主站商品ID、京东主站商品链接：https://3.cn/XXXXX 或者 https://item.jd.com/XXXXXXXX.html、通过京东主站商品ID转链后的联盟链接：https://u.jd.com/XXXXXX 进行转链，此时需入参sceneId=2
- 查询订单明细时：
出参支持入参完整的京东主站商品ID（skuIds字段）进行信息查询，此时需入参sceneId=2。
（具体所涉及的API及字段使用说明，详细参见五、本次升级所涉及的API及字段改造说明）
本场景id权限申请，点击：【消费者比价场景】
https://answer.jd.com/jump/?shortCode=AfSbFuAMEuG&surveyId=2062708
注：联盟系统会每天监控媒体“场景ID=2”推广数据健康度：场景ID=2的订单出现了浓度偏高或者偏低的疑似违规情况、使用场景ID=2服务于非消费者比价场景等。如监测到数据异常或调用不规范，会要求立即整改，严重者会关闭场景ID权限
四、订单明细说明
联盟商品ID（示例：VgDXlT9hVVVmDDiCbofTFhV7_VIfTFhV7VVyGGPNs），共分为A段与B段，中间用“_”连接，在推广链路中，A段为每次请求都会变更，B段为对同unionid（招商团长则为团长ID）和商品在特定范围内不变。
注意：在订单明细中，京东主站商品ID字段（skuId）不再返回数据，替换成新的联盟商品ID字段（itemId），且同时，同一个unionid下同一个商品，订单明细中的仅B段固定不变，即为一个固定的联盟商品ID；A段可能不同，且与推广链路中的A段并不相同，故若需与推广商品id查询匹配，建议用B段参数查询；
订单明细包括：订单行查询API、京东联盟PC端推客推广订单明细下载、京东联盟PC端招商团长推广订单明细下载
五、本次升级所涉及的API及字段改造说明
新增和调整的接口：2024年3月6日生效
推广物料接口数据因长期不再维护，无法升级联盟商品ID能力，故计划于2024年4月18日下线，请使用的媒体尽快切换接口
|
API类型 |
API名称 |
API中文名 |
链接 |
状态 |
入参调整 |
出参调整 |
|
快速刷库 |
jd.union.open.goods.itemid.get |
联盟商品ID获取 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.goods.itemid.get |
新增 |
skuIds字段：京东主站商品ID |
itemIds字段：联盟商品ID |
|
推广物料 |
jd.union.open.goods.jingfen.query |
京东联盟精选优质商品 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.goods.jingfen.query |
调整 |
无 |
1、新增字段：itemId 2、新增错误码：动态sku权限校验错误码 3、skuId字段：不返回 4、materialUrl字段：返回联盟商品链接 |
|
推广物料 |
jd.union.open.goods.query |
关键词查询接口 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.goods.query |
调整 |
1、新增sceneId字段（场景ID），支持入参1，2。注：整改期非必填，各个媒体需要尽快按照要求整改入参。调整为必填前会提前通知。 2、skuIds字段：仅支持sceneId=2时入参。 3、keyword字段：sceneId=2时支持入参京东主站商品ID、京东商品链接（包含3.cn单品链接）。其他场景仅支持入参关键词、联盟商品ID、联盟商品链接 |
1、新增字段：similaritemList，为联盟商品id 2、skuId字段：不返回 3、similarSkuList字段：不返回 4、materialUrl字段：当入参场景2且有对应场景权限时，返回京东商品链接，其他返回联盟商品链接 |
|
推广物料 |
jd.union.open.goods.material.query |
猜你喜欢 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.goods.material.query |
调整 |
无 |
1、新增字段：itemId，联盟商品ID 2、skuId字段：不返回 3、materialUrl字段：返回联盟商品链接 |
|
推广物料 |
jd.union.open.goods.bigfield.query |
商品详情查询接口 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.goods.bigfield.query |
调整 |
1、新增sceneId字段（场景ID），支持入参1，2。注：整改期非必填，各个媒体需要尽快按照要求整改入参。调整为必填前会提前通知 2、skuIds字段：仅sceneId=2时支持入参 |
skuId字段：不返回 |
|
推广物料 |
jd.union.open.goods.combination.query |
凑单商品物料查询接口 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.goods.combination.query |
调整 |
无 |
1、combinationGoodsResp下 新增字段：itemId，联盟商品ID skuId字段：不返回 url字段：返回联盟商品链接 2、combinationGoodsInfo下 新增字段：itemId，联盟商品ID skuId字段：不返回 url字段：返回联盟商品链接 |
|
推广物料 |
jd.union.open.goods.snapshop.query |
拍照购 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.goods.snapshop.query |
调整 |
无 |
1、新增字段：itemId，联盟商品ID 2、skuId字段：不返回 3、materialUrl字段：返回联盟商品链接 |
|
推广物料 |
jd.union.open.goods.combinationpage.get |
凑单页生成工具 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.goods.combinationpage.get |
调整 |
skuInfo字段：支持联盟商品ID入参 |
无 |
|
转链能力 |
jd.union.open.promotion.common.get |
网站/APP/流量媒体来获取的推广链接 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.promotion.common.get |
调整 |
1、新增sceneId字段（场景ID），支持入参1，2。注：整改期非必填，各个媒体需要尽快按照要求整改入参。调整为必填前会提前通知 2、materialId字段：单品转链时，sceneId=2时支持入参京东主站商品ID、京东商品链接（包含3.cn单品链接）；其他场景仅支持入参联盟商品ID、联盟商品链接。非单品转链不影响。
|
无 |
|
转链能力 |
jd.union.open.promotion.bysubunionid.get |
社群转链 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.promotion.bysubunionid.get |
调整 |
1、新增sceneId字段（场景ID），支持入参1，2。注：整改期非必填，各个媒体需要尽快按照要求整改入参。调整为必填前会提前通知 2、materialId字段：单品转链时，sceneId=2时支持入参京东主站商品ID、京东商品链接（包含3.cn单品链接）；其他场景仅支持入参联盟商品ID、联盟商品链接。非单品转链不影响。 |
无 |
|
转链能力 |
jd.union.open.promotion.byunionid.get |
工具商转链 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.promotion.byunionid.get |
调整 |
1、新增sceneId字段（场景ID），支持入参1，2。注：整改期非必填，各个媒体需要尽快按照要求整改入参。调整为必填前会提前通知 2、materialId字段：单品转链时，sceneId=2时支持入参京东主站商品ID、京东商品链接（包含3.cn单品链接）；其他场景仅支持入参联盟商品ID、联盟商品链接。非单品转链不影响。 |
无 |
|
推广效果 |
jd.union.open.order.row.query |
订单行查询 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.order.row.query |
调整 |
无 |
1、新增字段：itemId，联盟商品ID 2、skuId字段：不返回 |
|
推广效果 |
jd.union.open.order.bonus.query |
奖励订单查询接口 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.order.bonus.query |
调整 |
无 |
1、新增字段：itemId，联盟商品ID 2、skuId字段：不返回 |
|
推广效果 |
jd.union.open.order.agent.query |
工具商订单行查询 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.order.agent.query |
调整 |
无 |
1、新增字段：itemId，联盟商品ID 2、skuId字段：不返回 |
|
推广效果 |
jd.union.open.statistics.promotion.query |
支持传入skuId、活动链接来查询当日实时的推广效果数据。 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.statistics.promotion.query |
调整 |
1、新增字段：itemId，联盟商品ID 2、skuId字段：：不支持入参。 |
1、新增字段：itemId，联盟商品ID，与入参itemId一致 2、skuId字段：不返回
|
|
礼金 |
jd.union.open.coupon.gift.get |
创建礼金 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.coupon.gift.get |
调整 |
skuMaterialId字段：支持京东主站商品ID、联盟商品ID、联盟商品链接入参 |
无 |
|
礼金 |
jd.union.open.statistics.giftcoupon.query |
礼金效果数据 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.statistics.giftcoupon.query |
调整 |
1、新增字段：itemId，联盟商品ID 2、skuId字段：不支持入参。 |
1、新增字段：itemIdlist，联盟商品ID，与入参itemId一致 2、skuIdList：不返回 |
|
推广物料 |
jd.union.open.goods.promotiongoodsinfo.query |
推广商品查询 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.goods.promotiongoodsinfo.query |
计划下线 |
1、下线时间：2024-04-18 2、请切换到关键词商品查询接口：https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.goods.query |
|
|
推广物料 |
jd.union.open.goods.seckill.query |
秒杀商品查询接口 |
https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.goods.seckill.query |
计划下线 |
1.下线时间：2024-04-18 2.请切换到京粉精选商品查询接口https://union.jd.com/openplatform/api/v2?apiName=jd.union.open.goods.jingfen.query |
|
六、联盟商品ID切换节奏计划
时间节点一：2024年4月1日
- 2024年4月1日前，所有媒体、所有开发平台API均可正常使用，不受影响。
- 从2024年4月1日起，非企业认证的媒体，京东联盟所有开放平台API接口都仅支持完整的全新的联盟商品ID出入参
- 从2024年4月1日起，部分接口调用量订单转化率低的企业认证媒体，京东联盟所有开放平台API接口都仅支持完整的全新的联盟商品ID出入参。
调用量订单转化率低条件：2023年7月1日-2024年1月31日日，'jd.union.open.goods.query','jd.union.open.goods.jingfen.query','jd.union.open.goods.material.query'3个接口累计日均调用量＞10万，且媒体日均订单量＜100。
符合条件的媒体请注意查看联盟站内信，同时联盟商务会单独沟通。
时间节点二：2024年4月18日
推广商品查询接口下线，替换成新接口：关键词商品查询接口
秒杀商品查询接口下线，替换成新接口：京粉精选商品查询接口
时间节点三：预计2024年618前
全部媒体完成切换，具体时间节奏请随时关注本文档最新通知或者联盟公告
七、常见问题（持续更新中）
- 如果我有相关疑问，如何咨询？
如您有任何疑问，可以咨询对接商务、京东联盟在线客服、官方邮箱：cps@jd.com进行咨询解答。或者加入以下微信群咨询：
- 这次联盟商品ID升级有什么影响？
升级期间平台将同时支持联盟商品ID和京东主站商品ID的流通，请您注意识别商品ID格式的差异性，进行相关判断及处理
京东联盟PC端、京粉APP不受本次升级影响
- 什么时候会全量切换为联盟商品ID？
联盟商品ID的升级通知将会更新于此公告内：联盟商品ID切换白皮书（持续更新中），请您关注公告信息更新
- 如何判断两个商品ID是否指向同一个商品？如何判定两个商品ID是否指向同一个媒体（联盟ID）？
针对同一个媒体（联盟ID）+同一个商品，联盟商品ID的B段（后半段）保持不变；
如果两个联盟商品ID的B段（后半段）不一致，且链接至同一个商品，则其为不同媒体的联盟商品ID。
- 场景ID2如何申请？
与对接商务沟通，或者填写以下申请问卷：【消费者比价场景】
https://answer.jd.com/jump/?shortCode=AfSbFuAMEuG&surveyId=2062708
- 场景ID申请结果在哪能查到？
与对接商务确认，或者生效后在对应接口尝试调用即可
- 用户使用工具商的工具，应该如何处理？
工具商调用开发平台API，是否支持入参场景ID2和京东商品ID，取决于使用工具的用户对应联盟ID是否有场景2权限，而不是工具商本身是否有权限。
因2024年4月1日开始，非企业认证的媒体京东联盟所有开放平台API接口都仅支持完整的全新的联盟商品ID出入参，故工具商需要在2024年4月1日前完成联盟商品ID整改，以保证用户正常使用