# 京东管家 GA SOP — 京东运营能力接入指南

> 适用：GA 作为电商管家，需对京东商家/消费者场景提供运营、查询、自动化支持。
> 本 SOP 覆盖京东开放平台 API 的核心能力，用于商品、订单、物流、客服四大场景。

---

## 一、平台概览

| 维度 | 京东开放平台 |
|------|-------------|
| 官网 | https://open.jd.com |
| API 门户 | https://open.jd.com/home#/home |
| 认证方式 | Access Token（OAuth2.0） |
| 沙箱 | https://open.jd.com/home#/home |
| 限流 | 按 API 不同，部分需申请白名单 |
| 主要语言 | JD SDK（Python/Java/PHP/.NET/Node.js） |

---

## 二、核心 API 能力（按场景）

### 场景 1：商品查询

**适用**：用户问"某商品在京东的价格/评价/店铺"
```
GET /api/jos/CustomersServiceService.getJdosGoodsInfoByWareId
参数：wareId (商品ID)
返回：商品名称、价格、店铺、库存、评价数
```

**热搜商品榜单**：
```
GET /api/jos/HotWordsService.getSearchRecommendHotWordList
返回：热搜词排行（供选品参考）
```

**商品搜索**：
```
GET /api/jos/newWareSearchService.search
参数：keyword, catId, pageSize, pageIndex, sortType
返回：商品列表（标题/价格/销量/店铺）
```

---

### 场景 2：订单管理

**适用**：管家帮用户查询/管理京东订单

**订单列表**：
```
GET /api/jos/orderOnlineService.queryOpenOrderList
参数：startDate, endDate, orderState, page, pageSize
返回：订单号、商品、金额、状态、物流
```

**订单详情**：
```
GET /api/jos/orderOnlineService.getOpenOrderDetailInfo
参数：orderId
返回：完整订单信息（含配送地址、商品明细）
```

**订单取消**（消费者视角）：
```
POST /api/jos/orderService.cancelOrder
参数：orderId, cancelReasonType
```

---

### 场景 3：物流跟踪

**适用**：用户问"我的京东快递到哪了"

**物流轨迹**：
```
GET /api/jos/logisticsService.getLogisticsTrackInfo
参数：deliveryId（运单号）, logisticsId（物流公司编码）
返回：物流节点列表（时间、地点、状态）
```

**京东物流编码**：
| 编码 | 名称 |
|------|------|
| JD | 京东物流 |
| SF | 顺丰速运 |
| YTO | 圆通速递 |
| ZTO | 中通快递 |
| STO | 申通快递 |

---

### 场景 4：客服/售后

**适用**：处理售后问题、退换货查询

**退换货进度**：
```
GET /api/jos/afsService.getAfsApplyDetailById
参数：afsApplyId
返回：售后单状态、处理进度
```

**商品评价查询**：
```
GET /api/jos/goodcommentService.getGoodCommentList
参数：wareId, sortType, page
返回：商品好评列表（用于竞品分析）
```

---

## 三、OAuth2.0 授权流程

### 步骤 1：申请应用
1. 登录京东开放平台 → 创建应用 → 获取 `client_id` + `client_secret`

### 步骤 2：获取 Authorization Code
```
https://oauth.jd.com/oauth/authorize?
  response_type=code&
  client_id=<YOUR_CLIENT_ID>&
  redirect_uri=<YOUR_REDIRECT_URI>&
  scope=read
```

### 步骤 3：交换 Access Token
```
POST https://oauth.jd.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=<AUTH_CODE>&
client_id=<CLIENT_ID>&
client_secret=<CLIENT_SECRET>&
redirect_uri=<REDIRECT_URI>
```

### 步骤 4：调用 API
```
GET /api/jos/xxx
Authorization: Bearer <ACCESS_TOKEN>
```

---

## 四、常见错误码

| 错误码 | 含义 | 处理方式 |
|--------|------|---------|
| 102 | 无权限 | 需在控制台申请对应权限 |
| 104 | 接口停用 | 检查是否已上线/是否沙箱 |
| 1202 | 订单不存在 | 确认订单号是否正确 |
| 3001 | token 过期 | 刷新 token 或重新授权 |
| 3003 | 请求限流 | 降低频率，加入重试 |

---

## 五、Python 示例

```python
import requests

def get_jd_hot_words():
    url = "https://router.jd.com/api"
    params = {
        "method": "jingdong.newWareSearchService.search",
        "app_key": "YOUR_APP_KEY",
        "access_token": "YOUR_ACCESS_TOKEN",
        "timestamp": "2026-01-01 12:00:00",
        "v": "1.0",
        "sign_method": "md5",
        "param_json": "{\"keyword\":\"手机\",\"pageSize\":10}"
    }
    resp = requests.get(url, params=params)
    return resp.json()
```

---

## 六、GA 管家集成检查清单

- [ ] 已配置京东 `client_id` / `client_secret` / `access_token`
- [ ] 已测试订单查询（用真实订单号）
- [ ] 已测试物流轨迹（用真实运单号）
- [ ] 限流处理：有 429 时退避重试逻辑
- [ ] token 过期处理：自动刷新或重新授权流程

---

## 七、参考资源

- 京东开放平台文档：https://open.jd.com/home#/home
- 错误码参考：京东开放平台 → 开发文档 → 错误码表