# 接口文档

**Repository Path**: 12581/api-documentation

## Basic Information

- **Project Name**: 接口文档
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 内部系统数据交换接口文档

# 1. 文档概述

## 1.1 文档目的

本文档为【内部系统】接口规范说明书，用于明确系统对外提供的接口功能、请求参数、响应格式、调用方式及异常处理规则，为开发人员（前端、后端、第三方调用者）提供清晰的接口调用指引，确保接口调用的一致性和准确性，降低联调成本。

## 1.2 适用范围

适用对象：前端开发工程师、后端开发工程师、测试工程师、第三方系统集成工程师；

适用接口：【内部系统】所有对外暴露的HTTP接口，包括数据查询、数据接收等核心接口。

## 1.3 术语与定义

|术语|定义|
|---|---|
|接口|系统对外提供的服务入口，通过指定URL、请求方式和参数，实现数据交互或功能调用|
|请求参数|调用接口时，需要向接口传递的参数，分为路径参数、请求头参数、请求体参数|
|响应参数|接口处理请求后，返回给调用方的数据，包含状态码、提示信息和业务数据|
|AccessToken|系统交互需要的身份凭证，后续需要权限的接口需携带该凭证|
|JSON|接口请求和响应的默认数据格式，轻量、易解析|

## 1.4 接口通用规则

- 接口协议：HTTP/HTTPS（生产环境推荐HTTPS，保障数据传输安全）；

- 请求方式：支持POST（查询）、POST（新增/提交）

- 数据格式：请求体和响应体均采用JSON格式；

- 编码格式：UTF-8；

- 超时时间：默认3000ms，特殊接口可单独指定；

- 身份验证：需要权限的接口，需在请求头携带Token参数，格式为：AccessToken: {Token}；

- 响应统一格式：所有接口响应均包含code（状态码）、message（提示信息）、data（业务数据，可选）三个字段。

# 2. 通用响应格式

## 2.1 成功响应

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    // 业务数据，根据接口不同有所差异，可选
  }
}
```

## 2.2 失败响应

```json
{
  "code": 非200状态码,
  "message": "操作失败原因（明确提示用户/开发人员错误信息）",
  "data": null // 失败时，data字段可省略或为null
}
```

## 2.3 通用状态码说明

|状态码（code）|描述|说明|
|---|---|---|
|200|操作成功|接口正常处理请求，返回预期结果|
|400|参数错误|请求参数缺失、格式错误或不符合校验规则|
|401|未授权|未携带Token、Token过期或Token无效|
|403|权限不足|当前用户无权限操作该接口|
|404|接口不存在|请求的URL路径错误|
|405|请求方式错误|使用的请求方式（如GET/POST）与接口要求不符|
|500|服务器内部错误|服务器处理请求时发生异常，请联系开发人员排查|
|503|服务不可用|服务器暂时无法提供服务，建议稍后重试|

# 3. 具体接口详情

## 3.1 云仓数据拉取接口

### 3.1.1 接口基本信息

|项目|内容|
|---|---|
|接口名称|云仓数据拉取|
|接口URL|/api/data/yc|
|请求方式|POST|
|是否需要授权|否|
|接口描述|`退件系统`拉取`所属客户`的`云仓数据`，拉取成功后返回`所属客户`的`云仓数据`|
|超时时间|3000ms|

### 3.1.2 请求参数

#### 请求头参数

|参数名|类型|是否必填|示例值|描述|
|---|---|---|---|---|
|Content-Type|String|是|application/json|请求体数据格式|
|AccessToken|String|是|ac-xxxx|接口请求凭证|

#### 请求体参数（JSON）

|参数名|类型|是否必填|示例值|校验规则|描述|
|---|---|---|---|---|---|
|pageNo|Integer|是|1|从1开始|页码
|pageSize|Integer|是|1000|默认为1000|分页大小
|userId|string|是|xxx-xxx|客户所属|所属客户
|date|string|否|2026-03-23|日期|请求所属客户某一天的数据

### 3.1.3 响应参数

#### 响应体参数（JSON）

|参数名|类型|是否必返|示例值|描述|
|---|---|---|---|---|
|code|Integer|是|200|状态码，200表示成功|
|message|String|是|成功|操作提示信息|
|data|Object|是|-|成功后的数据|
|data.total|Integer|是|1000000|所属客户的云仓数据总数|
|data.records|List|是|-|所属客户的云仓数据列表|
|data.records.userId|String|是|-|客户所属|
|data.records.orderId|String|是|78xxxx|单号|
|data.records.wangwangName|String|是|-|店铺名称|

### 3.1.4 示例

#### 请求示例

```json
POST /api/data/yc HTTP/1.1
Host: localhost:8080
AccessToken: ac-sdsssdsd

{
    "pageNo":1,
    "pageSize":1000,
    "userId": "客户所属"
}
```

#### 成功响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "total": 237,
    "records":[
        "userId":"客户所属",
        "orderId":"单号",
        "wangwangName":"店铺名称"
    ]
  }
}
```

#### 失败响应示例（参数错误）

```json
{
  "code": 400,
  "message": "参数错误",
  "data": null
}
```

#### 失败响应示例（权限不足）

```json
{
  "code": 400,
  "message": "权限不足",
  "data": null
}
```

### 3.1.5 异常说明

|状态码|异常描述|解决方案|
|---|---|---|
|400|参数缺失、格式错误或校验失败|检查请求参数，确保所有必填参数齐全，格式符合校验规则|
|400|权限不足|AccessToken凭证信息过期，或者未授权|
|500|服务器内部错误（如数据库异常）|联系后端开发人员排查，稍后重试|

## 3.2 退件数据推送接口

### 3.2.1 接口基本信息

|项目|内容|
|---|---|
|接口名称|退件数据推送|
|接口URL|/api/data/order|
|请求方式|POST|
|是否需要授权|是|
|接口描述|`退件系统`推送`所属客户`的`退件数据`|
|超时时间|3000ms|

### 3.2.2 请求参数

#### 请求头参数

|参数名|类型|是否必填|示例值|描述|
|---|---|---|---|---|
|Content-Type|String|是|application/json|请求体数据格式|
|AccessToken|String|是|ac-xxxx|接口请求凭证|
#### 请求体参数（JSON）

|参数名|类型|是否必填|示例值|校验规则|描述|
|---|---|---|---|---|---|
|userId|String|是|-|-|客户所属|
|total|Integer|是|-|-|数据总数|
|records|List|是|-|-|数据列表|
|records.userId|String|是|-|-|所属客户|
|records.orderId|String|是|-|-|单号|
|records.wangwangName|String|否|-|-|店铺名称|
|records.customerName|String|否|-|-|客户名称|
|records.remark|String|是|-|-|备注|
|records.createTime|时间戳|是|1773467714270|-|录单时间|
|records.updateTime|时间戳|否|1773467714270|-|数据更新时间|
|records.clientIp|String|是|-|-|客户端ip|

### 3.2.3 响应参数

#### 响应体参数（JSON）

|参数名|类型|是否必返|示例值|描述|
|---|---|---|---|---|
|code|Integer|是|200|状态码，200表示成功|
|message|String|是|登录成功|操作提示信息|
|data|Integer|是|-||
### 3.2.4 示例

#### 请求示例

```json
POST /api/data/order HTTP/1.1
Host: localhost:8080
Content-Type: application/json
AccessToken: ac-sdsssdsd

{
  "userId": "客户所属",
  "total": 1000,
  "records":[
    {
       "userId":"客户所属",
       "orderId":"单号",
       "wangwangName":"店铺名称",
       "customerName":"客户名称",
       "remark":"备注",
       "createTime":"创建时间",
       "updateTime":"更新时间",
       "clientIp":"客户端ip"
   }
  ]
}
```

#### 成功响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": 1000
}
```

#### 失败响应示例（参数缺失）

```json
{
  "code": 400,
  "message": "账号或密码错误，请重新输入",
  "data": null
}
```

### 3.2.5 异常说明

|状态码|异常描述|解决方案|
|---|---|---|
|400|参数缺失或格式错误|补充必填参数，确保参数格式符合要求|
|500|服务器内部错误|联系后端开发人员排查，稍后重试|

# 4. 接口调试说明

## 4.1 调试环境

调试地址：http://localhost:8080（本地调试）、http://test.xxx.com（测试环境）；

调试工具：Postman、Apifox、浏览器开发者工具等；

测试账号：AccessToken：ac-xxxx

## 4.2 调试注意事项

- 调试时需确保请求方式、URL路径、参数格式与文档一致；

- 需授权的接口，必须携带有效Token，否则会返回401未授权；

- 请求参数需严格遵循校验规则，否则会返回400参数错误；

- 测试环境数据为模拟数据，请勿使用真实敏感信息；

- 若调试过程中出现500错误，或接口返回异常，及时联系后端开发人员排查。

# 5. 版本更新记录

|版本号|更新时间|更新内容|更新人|
|---|---|---|---|
|V1.0|2026-03-23|初始版本，新增云仓数据拉取，退件数据推送接口|程序|
# 6. 联系方式

若接口调用过程中遇到问题，或有需求变更，请联系相关负责人：

后端开发负责人：程序，联系电话：xxx，邮箱：2864667376@qq.com；

文档维护负责人：程序，联系电话：xxx，邮箱：2864667376@qq.com；