# 商城端接口对接



本模块共 4 个接口。源文件：`api.json`。



## 快速索引



| 接口名称 | 方法 | 路径 | 用途 |
| --- | --- | --- | --- |
| 扣减积分 | POST | `/gd_dataserver/gd_dataserver/mall/api/points/deduct` | 商城端在用户下单成功后调用此接口扣减积分，具有幂等性，同一orderNum多次调用只扣减一次 |
| 退还积分 | POST | `/gd_dataserver/gd_dataserver/mall/api/points/refund` | 商城端在用户退款时调用此接口退还积分，具有幂等性，同一orderNum多次调用只退还一次 |
| 根据Token获取用户信息 | POST | `/gd_dataserver/gd_dataserver/mall/api/user/info` | 商城端通过请求头中的Token获取用户基本信息，包括姓名、手机号、SAP编号等 |
| 根据Token获取用户积分信息 | POST | `/gd_dataserver/gd_dataserver/mall/api/user/points` | 商城端通过请求头中的Token及Body中的sap获取用户积分余额，包括可用积分、冻结积分等 |


## 接口详情



### 扣减积分

- **用途：** 商城端在用户下单成功后调用此接口扣减积分，具有幂等性，同一orderNum多次调用只扣减一次
- **请求：** `POST /gd_dataserver/gd_dataserver/mall/api/points/deduct`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `deductPointsUsingPOST`

参数：

| 字段 | 位置 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| token | header | 是 | - | 用户身份令牌 | - |

请求体：

- Content-Type：`application/json`
- 模型：`商城端-积分操作请求`
- 必填：文档未标记

| 字段 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| integralValue | 是 | number / bigdecimal | 积分数值（正整数） | 1000 |
| orderNum | 是 | string | 订单号（商城订单号，用于幂等校验） | ORDER202608210001 |
| sap | 是 | string | 用户SAP编号（从获取用户信息接口获得） | SAP001 |


响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: 商城端接口统一响应«Void» |
| 201 | Created | - |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 退还积分

- **用途：** 商城端在用户退款时调用此接口退还积分，具有幂等性，同一orderNum多次调用只退还一次
- **请求：** `POST /gd_dataserver/gd_dataserver/mall/api/points/refund`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `refundPointsUsingPOST`

参数：

| 字段 | 位置 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| token | header | 是 | - | 用户身份令牌 | - |

请求体：

- Content-Type：`application/json`
- 模型：`商城端-积分操作请求`
- 必填：文档未标记

| 字段 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| integralValue | 是 | number / bigdecimal | 积分数值（正整数） | 1000 |
| orderNum | 是 | string | 订单号（商城订单号，用于幂等校验） | ORDER202608210001 |
| sap | 是 | string | 用户SAP编号（从获取用户信息接口获得） | SAP001 |


响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: 商城端接口统一响应«Void» |
| 201 | Created | - |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 根据Token获取用户信息

- **用途：** 商城端通过请求头中的Token获取用户基本信息，包括姓名、手机号、SAP编号等
- **请求：** `POST /gd_dataserver/gd_dataserver/mall/api/user/info`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `getUserInfoUsingPOST`

参数：

| 字段 | 位置 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| token | header | 是 | - | 用户身份令牌 | - |

响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: 商城端接口统一响应«商城端-用户信息» |
| 201 | Created | - |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |


### 根据Token获取用户积分信息

- **用途：** 商城端通过请求头中的Token及Body中的sap获取用户积分余额，包括可用积分、冻结积分等
- **请求：** `POST /gd_dataserver/gd_dataserver/mall/api/user/points`
- **鉴权：** `X-Access-Token`（以接口定义为准）
- **operationId：** `getUserPointsUsingPOST`

参数：

| 字段 | 位置 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| token | header | 是 | - | 用户身份令牌 | - |

请求体：

- Content-Type：`application/json`
- 模型：`商城端-积分操作请求`
- 必填：文档未标记

| 字段 | 必填 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| integralValue | 是 | number / bigdecimal | 积分数值（正整数） | 1000 |
| orderNum | 是 | string | 订单号（商城订单号，用于幂等校验） | ORDER202608210001 |
| sap | 是 | string | 用户SAP编号（从获取用户信息接口获得） | SAP001 |


响应：

| 状态码 | 说明 | 响应模型 |
| --- | --- | --- |
| 200 | OK | */*: 商城端接口统一响应«商城端-用户积分信息» |
| 201 | Created | - |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Not Found | - |