# 京东店铺 API 连接与能力评估

## 2026-08-13 复测更新

- **AppKey 已恢复可用**：新版 SP-API 与旧版 JOS 均不再返回“AppKey 已禁用”。
- **本店授权 token 尚未接入测试**：商品、库存、店铺、评价、流量等只读接口均已进入 `access_token` 校验，旧版 JOS 统一返回错误码 `19`（accessToken 不正确/为空），新版商品和库存接口返回 `99904000016`（accessToken 为空）。
- **订单与售后仍有部署前置条件**：新版订单列表和售后服务单接口返回 `99904030005`，明确要求从云鼎平台发起调用。
- **已确认无权限的接口**：新版客服列表和承运商列表返回 `99904030008`，当前应用没有这两个接口的调用权限。
- **待单独复核**：新版报表定义探测返回 `99904000013`（签名校验失败）。该接口需要以官方 SDK 或确认路径参与规则后的服务端签名实现复测，不能据此判定报表权限。

## 结论摘要

- 初次测试时 AppKey 被禁用；2026-08-13 复测确认 AppKey 已恢复，不再是当前阻断项。
- 当前未形成可用的店铺数据访问能力，直接原因是本店 `access_token` 尚未接入测试；需要授权的 API 均在 token 校验阶段拦截。
- 当前无法确认商品、店铺、评价、流量等接口是否已真正返回店铺数据；解禁后仍须完成店铺授权并提供有效 `access_token`。
- 订单和售后在 token 之外还有云鼎调用前置条件；客服与承运商接口还需补充相应 API 权限包。
- 仓库当前仅把 `jd` 作为平台标识并读取本地快照，没有京东签名、OAuth token 交换或真实京东 API 连接实现。

## 官方文档依据

- [SP-API 调用方法](https://open.jd.com/v2/#/doc/dev-guide?listId=1100587)：新版入口为 `https://api-cn.jd.com/rest`；GET 请求需要 AppKey、时间戳、签名，标记为需要授权的接口还需要 `X-JOS-Access-Token`。
- [自研与 ISV 授权](https://open.jd.com/v2/#/doc/dev-guide?listId=1100981)：`appKey/appSecret` 用于创建应用；商家授权后通过 `code` 换取 `access_token`，并用 `refresh_token` 续期。
- [订单详情 getOrder](https://open.jd.com/v2/#/doc/api?apiCateId=100066&apiId=100251&apiName=getOrder&gwType=1)：订单详情接口 `sp-order/v0/orders/{orderId}` 标明需要授权，且订单数据属于敏感数据范围。
- [旧版 JOS 调用说明](https://open.jd.com/v2/#/doc/guide?listId=533)：旧版接口使用 `api.jd.com/routerjson`、`app_key`、`access_token`、GMT+8 格式的 `yyyy-MM-dd HH:mm:ss` 时间戳和签名参数。
- [开发工具授权管理](https://open.jd.com/v2/#/devtools?listId=authorization)：用于确认服务对象、授权状态和 token 获取状态。

## 测试计划与执行

### 测试原则

1. 先验证入口、签名和凭证状态，再验证接口权限。
2. 只调用 GET 或等价只读接口；不调用库存写入、发货、订单备注、售后操作、营销人群创建/删除、报表生成等有副作用接口。
3. 每个结果按四层解释：传输层、签名层、AppKey 状态、API 权限/授权层。
4. 原始凭证仅通过进程环境变量传入，未写入仓库、浏览器存储或本报告。

### 已执行探测

| 入口 | 探测范围 | 结果 |
|---|---|---|
| `https://api-cn.jd.com/rest` | 商品列表、商品详情、订单列表、订单详情、售后列表、客服列表、报表定义、承运商、物流轨迹、库存查询，共 10 个 GET | 10/10 HTTP 403，`99904030002`，AppKey 已禁用 |
| `https://api-cn-pre.jd.com/rest` | 商品列表 GET | HTTP 403，`99904030002`，AppKey 已禁用 |
| `https://api.jd.com/routerjson` | 店铺基本信息、店铺信息、商品搜索/详情/库存、售后、评价、销售排行、店铺流量、客服评价等 V1 只读方法 | 普通方法返回错误码 `21`，AppKey 已禁用 |
| `https://api.jd.com/routerjson` | `jingdong.pop.order.search`、`jingdong.pop.order.get` | 错误码 `73`，敏感 API 需要云鼎入驻；未进入业务数据返回 |

### 2026-08-13 复测

| 入口 | 探测范围 | 结果 |
|---|---|---|
| `https://api-cn.jd.com/rest` | 商品列表、SKU 库存 | HTTP 400，`99904000016`，请求已通过 AppKey 校验但缺少 `access_token` |
| `https://api-cn.jd.com/rest` | 订单列表、售后服务单列表 | HTTP 403，`99904030005`，请求必须从云鼎平台发起 |
| `https://api-cn.jd.com/rest` | 客服列表、承运商列表 | HTTP 403，`99904030008`，应用没有该 API 调用权限 |
| `https://api-cn.jd.com/rest` | 报表定义 | HTTP 400，`99904000013`，待按该接口的官方签名规则/SDK复测 |
| `https://api.jd.com/routerjson` | 店铺、商品、库存、评价、流量、客服评价只读接口 | HTTP 200 的业务错误响应，错误码 `19`，`access_token` 为空或不正确 |

代表性请求追踪号已在终端结果中保留，建议提交工单时附上对应时间段的 requestId，而不要附带 AppSecret。

## 当前能力判断

### 已确认可用

没有确认到任何店铺数据 API 可用。公开文档可证明接口存在，不能证明当前应用拥有该接口权限。

### 解禁并授权后，理论上可覆盖

| 数据域 | 官方接口能力 | 对系统的可用场景 | 关键限制 |
|---|---|---|---|
| 店铺与经营范围 | 商家基本信息、店铺信息、店内分类、经营分类 | 店铺档案、类目树、商品归属校验 | 需对应店铺身份和权限包 |
| 商品与 SKU | 商品列表、商品详情、SKU 列表、图片、标题/卖点、状态、库存、价格相关接口 | 自有商品主数据、SKU 维度经营分析、商品详情页 | 商品查询与库存/价格字段可能分权限；写接口必须单独申请，不纳入本次测试 |
| 订单 | 订单列表、订单详情、订单商品、支付、订单状态、发货和物流轨迹 | GMV、销量、订单数、客单价、履约状态、订单级退款关联 | `getOrder` 明确需要授权；旧版订单接口命中敏感 API/云鼎要求；收货人等字段需遵守脱敏和敏感数据规则 |
| 售后与退款 | 售后服务单列表/详情、日志、价保、小额打款等 | 退款金额、退款订单数、售后原因、商品/订单售后归因 | 不同售后类型对应不同接口和权限包，仍需按真实店铺数据回归 |
| 商品评价 | 旧版评价 API 包含 `jingdong.pop.PopCommentJsfService.getVenderCommentsForJos` | 评价正文、星级、评价时间、商品 VOC 分析 | 当前 AppKey 已禁用；评价接口的字段、分页和权限未取得成功响应验证 |
| 客服与服务质量 | 客服列表、客服评价、会话、聊天记录、客服绩效等 | 客服 VOC、服务质量、咨询问题归因 | 聊天记录和用户信息属于敏感数据，需额外授权、脱敏和合规控制 |
| 经营指标与报表 | 新版 `sp-data` 报表定义/报表查询；旧版数据 API | 流量、销量、经营日报、趋势指标 | 旧版数据 API 目录已提示下线并指向云海数据开放平台；新版报表接口需要 schema 和数据权限，当前未执行 POST 报表查询 |
| 会员与营销 | 会员列表/详情/积分、策略、人群包、营销活动 | 会员运营、营销活动效果 | 与 VOC 首期无关，涉及用户数据或写操作，需单独权限与审计 |

### 当前无法覆盖或不应假设可覆盖

- 竞品价格、竞品销量、竞品评价和全网市场快照：店铺商家 API 主要面向本店数据，不能把本店授权推导为竞品数据权限。
- 稳定的日粒度流量/转化/GMV趋势：需要实际可用的 `sp-data` 报表 schema 和店铺授权验证；旧版数据 API 已有下线提示。
- 未经授权的评价正文、订单收货人明文、用户 PIN、手机号和聊天记录：这些属于敏感数据场景，需单独授权、脱敏和数据留存策略。
- 自动修改商品、库存、价格、订单发货、订单备注、售后处理：即使接口存在，也必须按写权限单独验收，本次没有调用。

## 对现有仓库的影响

- `src/app/core/config/runtime-config.ts` 固定 `domesticPlatform: 'jd'`，但这只是数据模型平台标识。
- `src/app/core/services/domestic-ecommerce-gateway.service.ts` 只提供 `/api/voc-e-commerce/{platform}/{path}` 的通用 GET 代理，不实现京东签名或 OAuth。
- `proxy.conf.json` 的京东相关代理指向本地后端；当前前端默认国内数据仍可使用本地快照模式。
- 因此，当前不能把本次 API 探测结果直接接入前端页面，也不应把 AppKey/AppSecret 放入 Angular 环境变量或浏览器代码。

## 恢复后的复测顺序

1. 在京东开放平台确认应用状态，提交错误码 `21`/`99904030002` 对应的解禁工单。
2. 在授权管理中确认服务对象为目标 POP 店铺，并完成商家授权。
3. 获取并安全保存 `access_token`、`refresh_token`、过期时间和店铺标识；AppSecret 只放服务端密钥管理，不放前端。
4. 先复测一个免授权 GET 和一个需要授权 GET，确认签名、店铺身份和 token 关系。
5. 再按商品、订单、售后、评价、客服、报表顺序扩大探测；每一域至少验证分页、增量字段、时间范围、空数据和错误码。
6. 以真实店铺数据做字段映射和数据质量验收，再接入本地快照/增量同步任务。

## 复测通过标准

- AppKey 状态不再返回 `99904030002` 或 V1 错误码 `21`。
- 需要授权的接口返回业务层响应，而不是 token 缺失、过期或店铺身份不匹配。
- 商品、订单、售后、评价、报表至少各有一个真实店铺数据样本，分页和增量游标可重复运行。
- 失败请求不记录 AppSecret、完整 token、用户 PIN、手机号、地址或聊天正文。
- 同步任务具备限流、重试、断点、幂等、审计和撤销授权后的降级行为。