京东 VOP 供应链对接与使用指南

1. 功能概述

本系统深度集成了京东 VOP 开放平台接口，实现了从商品搜索、同步、下单到物流跟踪的全自动化闭环。通过此功能，您可以：

• 海量选品：直接搜索京东千万级 SKU，一键导入平台销售。
• 自动同步：定时同步商品价格、库存、上下架状态，确保售卖信息准确。
• 自动下单：用户在本平台下单支付后，系统自动向京东提交订单，使用预存款余额支付。
• 物流同步：自动获取京东物流轨迹，同步至本平台订单详情。
• 售后支持：支持订单取消、余额查询及明细核对。

核心优势：无需囤货，京东物流极速配送，正品保障，适合积分商城、企业福利采购、带货直播等场景。

---

2. 前置准备

在启用本功能前，请确保您已完成以下步骤：

1. 注册京东 VOP 账号：
   • 访问 京东 VOP 官网 注册并申请入驻。
   • 完成实名认证及协议签署。
2. 创建应用并获取密钥：
   • 在京东 VOP 控制台创建应用，获取 App Key 和 App Secret。
   • 获取 Username 和 Password（用于获取 Access Token）。
   • 重要：生成 RSA 私钥 (PrivKey)，并在京东后台配置对应的公钥。
3. 配置白名单：
   • 在京东 VOP 控制台 -> 流量权限 中，设置 IP 白名单（如需）和回调地址。
   • 回调地址示例：https://您的域名/addons/smplive/jdvop_callback/query_token (用于获取 Token)。
4. 充值预存款：
   • 京东 VOP 采用预存款模式下单，请确保账户内有足够余额。

---

3. 系统配置

请在后台 系统配置 -> 商城(京东) 中填写以下参数：

配置项键名 (Key)	说明	备注
jdvop_url	API 接口地址	通常为 https://api.vop.jd.com/routerjson
jdvop_app_key	App Key	京东应用管理中获得
jdvop_app_secret	App Secret	京东应用管理中获得
jdvop_username	用户名	京东提供的账号名称
jdvop_password	密码	京东提供的密码（系统会自动加密处理）
jdvop_privKey	RSA 私钥	注意：只需填入私钥内容，不含头尾标识，系统会自动格式化
jdvop_freight_id	默认运费模板 ID	建议设置为“免运费”或固定运费模板
jdvop_category_id	默认商品分类 ID	同步的京东商品将归入此本地分类
jdvop_category_new_add	是否允许新增分类	allow: 根据京东一级分类自动创建本地分类; deny: 全部归入默认分类

---

4. 核心功能操作

4.1 获取 Access Token (授权)

京东 API 调用需要有效的 Access Token。

• 初始化授权：
  • 调用 \addons\smplive\library\jdVopService::initAccessToken()。
  • 系统会拼接授权 URL，引导用户跳转至京东 OAuth 页面进行授权。
  • 授权成功后，京东会回调至 queryAccessToken 方法，系统自动保存 access_token 和过期时间。
• 自动刷新：
  • getAccessToken() 方法会自动检查缓存中的 Token 是否过期。
  • 若过期，需重新执行授权流程（通常 Token 有效期较长，建议设置定时任务监控）。

4.2 商品搜索与导入

管理员可在后台“京东商品库”中搜索并添加商品。

• 搜索商品：
  • 调用 goodsSearch($pageNo, $pageSize, $search_arr)。
  • 支持关键字 (keyword) 和京东分类 ID (categoryId1) 筛选。
  • 返回数据包含：SKU ID、名称、图片、京东售价、成本价、库存状态、是否已添加标记。
• 添加商品：
  • 选中商品后，调用 addGoods($skuIds)。
  • 处理逻辑：
    1. 批量获取商品详情、图片、价格、库存。
    2. 解析商品介绍中的图片，转换为 HTML 格式存入详情表。
    3. 自动匹配或创建本地商品分类。
    4. 若商品已存在，则更新标题、价格、库存等信息；若不存在，则新建商品。
    5. 默认状态为 normal（上架），若京东下架则设为 hidden。

4.3 定时同步任务 (重要)

为了保证价格和库存的准确性，必须配置定时任务（Cron）。

• 同步内容：价格、库存、上下架状态。
• 推荐频率：每 4 小时执行一次全量轮询，或每分钟执行一次增量更新。
• 执行方法：

  \addons\smplive\library\jdVopService::updateGoodsPriceStock();
  

• 逻辑说明：
  • 系统记录上次更新的最后商品 ID (jdvop_update_last_id)。
  • 每次执行读取接下来的 1000 个商品，调用京东接口获取最新数据。
  • 智能更新：仅当价格、库存或状态发生变化时才更新数据库，减少 IO 压力。
  • 库存策略：京东不返回具体库存数，只返回“有货/无货”。代码中将“有货”映射为库存 50，“无货”映射为 0。

4.4 自动下单流程

当用户在本平台支付京东商品订单后：

1. 触发条件：订单支付成功，且 shops_id 为京东商户 ID (默认 31)。
2. 提交订单：
   • 调用 submitOrder($order)。
   • 组装收货人信息、SKU 列表、发票信息（默认开具增值税普通发票）。
   • 使用预存款支付方式 (paymentType=4)。
3. 结果处理：
   • 成功：记录京东订单号 (jdOrderId) 到本地订单表，状态更为“已发货/处理中”。
   • 失败：记录错误日志，抛出异常，需人工介入或自动退款。
4. 确认订单：
   • 部分场景下需调用 confirmOrder() 进行二次确认（视京东具体业务规则而定）。

4.5 物流与售后

• 物流同步：
  • 定时任务调用 queryJdessage() 监听京东消息队列（如发货、妥投消息）。
  • 或主动调用 queryDeliveryInfo($jdOrderId) 获取物流轨迹。
  • 系统自动解析物流公司编码和运单号，更新本地订单物流状态。
• 取消订单：
  • 调用 cancelOrder($orderId, $jdOrderId, $cancelReason)。
  • 需在京东规定时间内（通常是未出库前）申请取消。
• 余额查询：
  • 调用 getAccountBalance() 获取当前预存款余额，建议在后台仪表盘展示，提醒充值。

---

5. 常见问题排查 (FAQ)

Q1: 提示 "Access Token 无效" 或 "No Token"?

• 原因：Token 过期或未正确授权。
• 解决：检查 jdvop_access_token 配置是否为空。重新执行 initAccessToken() 流程，确保回调地址在白名单内，且能正常接收 code 参数。

Q2: 商品同步后库存显示为 0 或 50？

• 原因：京东 VOP 接口出于商业保密，不返回精确库存数值，仅返回库存状态类型。
• 说明：代码中约定 stockStateType==33 (有货) 时设置为 50，否则为 0。这是正常现象。若实际购买时京东有货但显示无货，可手动在后台修改库存。

Q3: 下单失败，提示 "余额不足"？

• 原因：京东账户预存款余额低于订单总金额。
• 解决：登录京东 VOP 后台充值，或调用 getAccountBalance() 检查余额。

Q4: 物流信息长时间不更新？

• 原因：未配置消息监听或定时任务未执行。
• 解决：
  1. 确保定时任务正在运行 queryJdessage()。
  2. 检查服务器是否能访问京东 API。
  3. 对于已发货但未同步的订单，可手动在后台点击“查询物流”触发 queryDeliveryInfo()。

Q5: 商品图片无法显示？

• 原因：京东图片链接可能需要 HTTPS，或防盗链限制。
• 解决：代码中已处理图片链接拼接 (https://img13.360buyimg.com/n12/...)。若仍无法显示，请检查服务器是否允许外链图片，或考虑将图片下载到本地 OSS。

---

6. 开发参考 (For Developers)

如果您需要二次开发，可以参考以下核心方法：

use addons\smplive\library\jdVopService;

// 1. 搜索商品
$list = jdVopService::goodsSearch(1, 10, ['keyword' => '手机', 'categoryId1' => '9987']);

// 2. 添加商品到本地库
$skuIds = ['1000123456', '1000654321'];
$msg = jdVopService::addGoods($skuIds);

// 3. 手动同步某几个商品的价格库存
jdVopService::updateGoodsPriceStock('1000123456,1000654321');

// 4. 查询余额
$balance = jdVopService::getAccountBalance();

// 5. 获取客户端实例（用于自定义请求）
$client = jdVopService::getJdClient();

注意事项：

• RSA 签名：accessTokenPwdMi 方法使用了 RSA 私钥对密码进行加密，请确保配置的 jdvop_privKey 格式正确（代码会自动添加 BEGIN/END 头尾）。
• 并发控制：京东 API 有调用频率限制，建议在定时任务中加入 sleep 或使用队列处理大量商品同步。
• 日志记录：所有关键操作均通过 smplive_log 记录，排查问题时请查看 runtime/log/ 下的 jdVopService 相关日志。

---

温馨提示：京东 VOP 接口规则可能会随政策调整，请以 京东 VOP 官方文档 为准。本系统代码已针对常见场景做了封装和容错处理。

更多技术介绍在smplive.wpygo.com/

DCloud 插件市场** 便于直接在 HBuilderX 中导入使用： 点击查看插件详情ext.dcloud.net.cn/plugin?id=2…

Gitee 代码仓库** 获取完整源代码及提交历史： 访问仓库地址 gitee.com/mldxmy/simp…