21 KiB
订单管理系统标准 API 文档
- 项目名称：订单管理系统
- 文档版本：V1.0
- 文档类型：标准 API 文档
- 适用范围：WEB 业务员端、小程序管理层端、小程序司机端、WEB 管理后台
- 编写日期：2026-05-05
1. 文档说明
本文档用于描述订单管理系统的标准接口规范，包括接口分组、请求方法、路径、鉴权要求、请求参数、响应参数、错误码、状态码、字段说明和示例。
1.1 统一约定
- 接口采用
HTTP/HTTPS + JSON。 - 除登录接口外，所有接口均需携带身份凭证。
- 列表接口统一支持分页。
- 成功响应统一返回
code = 0。 - 失败响应统一返回非 0 状态码，并返回明确错误信息。
- 涉及敏感字段时，按角色做脱敏或隐藏。
1.2 通用响应体
{
"code": 0,
"message": "success",
"data": {}
}
1.3 分页响应体
{
"code": 0,
"message": "success",
"data": {
"total": 100,
"page_no": 1,
"page_size": 20,
"list": []
}
}
2. 鉴权与权限
2.1 鉴权方式
- 登录成功后返回
token。 - 后续请求通过请求头携带
Authorization: Bearer <token>。
2.2 权限范围
- 业务员：仅可访问本人订单、本人客户、本人相关提醒。
- 管理层：可访问全量订单、审批、利润、报表等。
- 司机：仅可访问自己的任务和任务相关信息。
- 管理员：可访问系统基础资料、配置、用户、角色、菜单等。
2.3 字段级权限
- 成本、利润、回扣、报价等财务数据仅管理层和管理员可见。
- 司机端不得查看客户敏感信息。
- 未授权字段应在接口层直接屏蔽，不应返回前端后再隐藏。
3. 统一错误码
| 错误码 | 说明 |
|---|---|
| 0 | 成功 |
| 40001 | 参数错误 |
| 40002 | 未登录或登录失效 |
| 40003 | 无权限 |
| 40004 | 资源不存在 |
| 40005 | 状态不允许当前操作 |
| 40006 | 数据重复 |
| 40007 | 业务规则校验失败 |
| 40008 | 文件上传失败 |
| 40009 | 第三方接口调用失败 |
| 50000 | 系统异常 |
4. 状态码规范
4.1 订单状态
| 状态值 | 状态名称 |
|---|---|
| draft | 草稿 |
| pending_approve | 待审核 |
| approved | 已通过 |
| rejected | 已退回 |
| pending_factory | 待下发工厂 |
| pending_driver | 待司机接单 |
| accepted | 已接单 |
| picked_up | 已揽货 |
| delivered | 已送达 |
| production | 生产中 |
| shipped | 已发货 |
| completed | 已完成 |
| settled | 已结算 |
| canceled | 已取消 |
4.2 任务状态
| 状态值 | 状态名称 |
|---|---|
| pending | 待接单 |
| accepted | 已接单 |
| picked_up | 已揽货 |
| delivered | 已送达 |
| canceled | 已取消 |
4.3 提醒状态
| 状态值 | 状态名称 |
|---|---|
| pending | 待发送 |
| sent | 已发送 |
| read | 已读 |
| canceled | 已取消 |
4.4 审批结果
| 状态值 | 状态名称 |
|---|---|
| pass | 通过 |
| reject | 退回 |
| refuse | 拒绝 |
5. 接口分组
- 认证接口
- 订单接口
- 审批接口
- 客户接口
- 产品接口
- 工厂/供应商接口
- 司机任务接口
- 物流与 AI 接口
- 提醒接口
- 报表接口
- 配置接口
- 审计日志接口
6. 认证接口
6.1 用户登录
接口名称： 用户登录
请求方式： POST
路径： /api/auth/login
是否鉴权： 否
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| username | string | 是 | 登录账号 |
| password | string | 是 | 登录密码 |
| role_type | string | 是 | 角色类型 |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| user_id | number | 用户ID |
| real_name | string | 姓名 |
| role_id | number | 角色ID |
| role_name | string | 角色名称 |
| token | string | 登录凭证 |
| menus | array | 菜单列表 |
| permissions | array | 权限列表 |
示例响应
{
"code": 0,
"message": "success",
"data": {
"user_id": 1,
"real_name": "张三",
"role_id": 2,
"role_name": "业务员",
"token": "xxxxx",
"menus": [],
"permissions": []
}
}
6.2 当前用户信息
接口名称： 当前用户信息
请求方式： GET
路径： /api/auth/me
是否鉴权： 是
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| user_id | number | 用户ID |
| username | string | 账号 |
| real_name | string | 姓名 |
| mobile | string | 手机号 |
| role_id | number | 角色ID |
| role_name | string | 角色名称 |
| menus | array | 菜单列表 |
| permissions | array | 权限列表 |
6.3 退出登录
接口名称： 退出登录
请求方式： POST
路径： /api/auth/logout
是否鉴权： 是
7. 订单接口
7.1 创建订单
接口名称： 销售单录入
请求方式： POST
路径： /api/orders
是否鉴权： 是
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| customer_name | string | 是 | 客户姓名 |
| customer_mobile | string | 是 | 客户手机号 |
| customer_address | string | 否 | 客户地址 |
| order_source | string | 否 | 订单来源标签 |
| delivery_type | string | 否 | 发货类型 |
| factory_id | number | 否 | 工厂ID |
| remark | string | 否 | 备注 |
| rebate_total | number | 否 | 回扣总额 |
| freight_total | number | 否 | 运费总额 |
| tax_total | number | 否 | 税费总额 |
| other_fee_total | number | 否 | 其他费用总额 |
| items | array | 是 | 订单明细 |
items 明细字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| product_id | number | 否 | 产品ID |
| product_name | string | 是 | 产品名称 |
| specification | string | 是 | 规格 |
| unit | string | 是 | 单位 |
| quantity | number | 是 | 数量 |
| sale_price | number | 是 | 销售单价 |
| cost_price | number | 是 | 成本单价 |
| rebate_amount | number | 否 | 回扣金额 |
| freight_amount | number | 否 | 运费分摊 |
| tax_amount | number | 否 | 税费分摊 |
| other_fee_amount | number | 否 | 其他费用分摊 |
| remark | string | 否 | 备注 |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| order_id | number | 订单ID |
| order_no | string | 订单编号 |
| order_status | string | 订单状态 |
| profit_total | number | 利润 |
| profit_rate | number | 利润率 |
业务规则
- 新客户按姓名 + 手机号自动写入客户库。
- 新订单默认进入草稿状态。
- 订单保存后需记录创建人和时间。
7.2 提交订单审核
接口名称： 订单提交审核
请求方式： POST
路径： /api/orders/{order_id}/submit
是否鉴权： 是
路径参数
| 字段 | 类型 | 说明 |
|---|---|---|
| order_id | number | 订单ID |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| order_id | number | 订单ID |
| order_status | string | 状态 |
| submitted_at | string | 提交时间 |
7.3 订单详情
接口名称： 订单详情
请求方式： GET
路径： /api/orders/{order_id}
是否鉴权： 是
路径参数
| 字段 | 类型 | 说明 |
|---|---|---|
| order_id | number | 订单ID |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| order_id | number | 订单ID |
| order_no | string | 订单编号 |
| customer_id | number | 客户ID |
| customer_name | string | 客户姓名 |
| customer_mobile | string | 客户手机号 |
| salesman_id | number | 业务员ID |
| order_source | string | 来源标签 |
| order_status | string | 订单状态 |
| delivery_type | string | 发货类型 |
| factory_id | number | 工厂ID |
| sale_price_total | number | 销售价总额 |
| cost_price_total | number | 成本价总额 |
| rebate_total | number | 回扣总额 |
| freight_total | number | 运费总额 |
| tax_total | number | 税费总额 |
| other_fee_total | number | 其他费用总额 |
| profit_total | number | 利润 |
| profit_rate | number | 利润率 |
| items | array | 明细 |
| approve_logs | array | 审批记录 |
| logistics_info | object | 物流信息 |
| remark | string | 备注 |
7.4 订单列表
接口名称： 订单列表
请求方式： GET
路径： /api/orders
是否鉴权： 是
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
| order_status | string | 订单状态 |
| customer_name | string | 客户姓名 |
| customer_mobile | string | 客户手机号 |
| salesman_id | number | 业务员ID |
| factory_id | number | 工厂ID |
| order_source | string | 订单来源 |
| start_time | string | 开始时间 |
| end_time | string | 结束时间 |
| page_no | number | 页码 |
| page_size | number | 每页条数 |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| total | number | 总数 |
| page_no | number | 页码 |
| page_size | number | 每页条数 |
| list | array | 数据列表 |
7.5 订单取消
接口名称： 订单取消
请求方式： POST
路径： /api/orders/{order_id}/cancel
是否鉴权： 是
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_id | number | 是 | 订单ID |
| cancel_reason | string | 是 | 取消原因 |
| cancel_opinion | string | 否 | 取消意见 |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| order_id | number | 订单ID |
| order_status | string | 取消后状态 |
| canceled_at | string | 取消时间 |
业务规则
- 草稿、待审核订单可直接取消。
- 已通过订单需何总确认。
- 已进入履约阶段的订单需特殊审批。
7.6 订单状态变更
接口名称： 订单状态变更
请求方式： POST
路径： /api/orders/{order_id}/status
是否鉴权： 是
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_id | number | 是 | 订单ID |
| target_status | string | 是 | 目标状态 |
| remark | string | 否 | 备注 |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| order_id | number | 订单ID |
| order_status | string | 变更后状态 |
8. 审批接口
8.1 销售单最终审批
接口名称： 销售单最终审批
请求方式： POST
路径： /api/orders/{order_id}/approve
是否鉴权： 是
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_id | number | 是 | 订单ID |
| approve_result | string | 是 | 审批结果 |
| approve_opinion | string | 否 | 审批意见 |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| order_id | number | 订单ID |
| order_status | string | 审批后状态 |
| profit_total | number | 利润 |
| profit_rate | number | 利润率 |
| approve_time | string | 审批时间 |
业务规则
- 审核时需展示利润计算过程。
- 审批结果为通过或退回。
8.2 取消审批
接口名称： 取消审批
请求方式： POST
路径： /api/orders/{order_id}/cancel-approve
是否鉴权： 是
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_id | number | 是 | 订单ID |
| approve_result | string | 是 | 审批结果 |
| approve_opinion | string | 否 | 审批意见 |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| order_id | number | 订单ID |
| order_status | string | 变更后状态 |
9. 客户接口
9.1 新增客户
接口名称： 客户新增
请求方式： POST
路径： /api/customers
是否鉴权： 是
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| customer_name | string | 是 | 客户姓名 |
| mobile | string | 是 | 手机号 |
| address | string | 否 | 地址 |
| settlement_type | string | 否 | 结算方式 |
| settlement_days | number | 否 | 月结天数 |
| settlement_start_type | string | 否 | 账期起算口径 |
| customer_type | string | 否 | 客户类型 |
| salesman_id | number | 否 | 归属业务员ID |
| credit_limit | number | 否 | 信用额度 |
| remark | string | 否 | 备注 |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| customer_id | number | 客户ID |
| customer_name | string | 客户姓名 |
| mobile | string | 手机号 |
9.2 客户列表
接口名称： 客户列表
请求方式： GET
路径： /api/customers
是否鉴权： 是
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
| customer_name | string | 客户姓名 |
| mobile | string | 手机号 |
| customer_type | string | 客户类型 |
| settlement_type | string | 结算方式 |
| salesman_id | number | 业务员ID |
| page_no | number | 页码 |
| page_size | number | 每页条数 |
9.3 客户详情
接口名称： 客户详情
请求方式： GET
路径： /api/customers/{customer_id}
是否鉴权： 是
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| customer_id | number | 客户ID |
| customer_name | string | 客户姓名 |
| mobile | string | 手机号 |
| address | string | 地址 |
| settlement_type | string | 结算方式 |
| settlement_days | number | 月结天数 |
| settlement_start_type | string | 账期起算口径 |
| customer_type | string | 客户类型 |
| salesman_id | number | 归属业务员ID |
| credit_limit | number | 信用额度 |
| arrears_amount | number | 欠款金额 |
| status | string | 状态 |
| remark | string | 备注 |
9.4 客户导入
接口名称： 客户批量导入
请求方式： POST
路径： /api/customers/import
是否鉴权： 是
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file_url | string | 是 | 导入文件地址 |
| import_mode | string | 否 | 导入模式 |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| total_count | number | 总条数 |
| success_count | number | 成功条数 |
| duplicate_count | number | 重复条数 |
| fail_count | number | 失败条数 |
| fail_list | array | 失败明细 |
10. 产品接口
10.1 新增产品
接口名称： 产品新增
请求方式： POST
路径： /api/products
是否鉴权： 是
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| product_name | string | 是 | 产品名称 |
| specification | string | 是 | 规格 |
| unit | string | 是 | 单位 |
| category | string | 是 | 分类 |
| cost_price | number | 是 | 成本价 |
| sale_price | number | 是 | 售价 |
| status | string | 是 | 状态 |
| remark | string | 否 | 备注 |
10.2 产品列表
接口名称： 产品列表
请求方式： GET
路径： /api/products
是否鉴权： 是
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
| product_name | string | 产品名称 |
| specification | string | 规格 |
| category | string | 分类 |
| status | string | 状态 |
| page_no | number | 页码 |
| page_size | number | 每页条数 |
10.3 产品详情
接口名称： 产品详情
请求方式： GET
路径： /api/products/{product_id}
是否鉴权： 是
11. 工厂/供应商接口
11.1 新增工厂/供应商
接口名称： 工厂新增
请求方式： POST
路径： /api/suppliers
是否鉴权： 是
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| supplier_name | string | 是 | 名称 |
| supplier_type | string | 是 | 类型 |
| contact_name | string | 否 | 联系人 |
| contact_mobile | string | 否 | 联系电话 |
| address | string | 否 | 地址 |
| template_type | string | 否 | 模板类型 |
| status | string | 是 | 状态 |
| remark | string | 否 | 备注 |
11.2 工厂列表
接口名称： 工厂列表
请求方式： GET
路径： /api/suppliers
是否鉴权： 是
11.3 下发文本生成
接口名称： 工厂下发文本生成
请求方式： POST
路径： /api/orders/{order_id}/supplier-text
是否鉴权： 是
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_id | number | 是 | 订单ID |
| supplier_id | number | 是 | 工厂/供应商ID |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| text_content | string | 可复制文本 |
| template_type | string | 模板类型 |
12. 司机任务接口
12.1 任务列表
接口名称： 司机任务列表
请求方式： GET
路径： /api/driver/tasks
是否鉴权： 是
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
| status | string | 任务状态 |
| page_no | number | 页码 |
| page_size | number | 每页条数 |
12.2 任务详情
接口名称： 司机任务详情
请求方式： GET
路径： /api/driver/tasks/{task_id}
是否鉴权： 是
12.3 接单
接口名称： 司机接单
请求方式： POST
路径： /api/driver/tasks/{task_id}/accept
是否鉴权： 是
12.4 确认揽货
接口名称： 司机确认揽货
请求方式： POST
路径： /api/driver/tasks/{task_id}/pickup
是否鉴权： 是
12.5 确认送达
接口名称： 司机确认送达
请求方式： POST
路径： /api/driver/tasks/{task_id}/deliver
是否鉴权： 是
13. 物流与 AI 接口
13.1 物流查询
接口名称： 物流查询
请求方式： GET
路径： /api/logistics/{order_id}/trace
是否鉴权： 是
13.2 AI 图片识别
接口名称： AI 图片识别
请求方式： POST
路径： /api/ai/recognize
是否鉴权： 是
13.3 AI 识别结果修正
接口名称： AI 识别结果修正
请求方式： POST
路径： /api/ai/recognize/{log_id}/correct
是否鉴权： 是
14. 提醒接口
14.1 欠款提醒检查
接口名称： 欠款提醒检查
请求方式： POST
路径： /api/reminders/arrears/check
是否鉴权： 是
14.2 长时间未下单提醒检查
接口名称： 长时间未下单提醒检查
请求方式： POST
路径： /api/reminders/inactive-customers/check
是否鉴权： 是
15. 报表接口
15.1 业绩统计
接口名称： 业绩统计
请求方式： GET
路径： /api/reports/performance
是否鉴权： 是
15.2 报表导出
接口名称： 业绩报表导出
请求方式： GET
路径： /api/reports/performance/export
是否鉴权： 是
16. 配置接口
16.1 配置查询
接口名称： 配置查询
请求方式： GET
路径： /api/configs/{config_key}
是否鉴权： 是
16.2 配置更新
接口名称： 配置更新
请求方式： PUT
路径： /api/configs/{config_key}
是否鉴权： 是
17. 审计日志接口
17.1 日志列表
接口名称： 审计日志列表
请求方式： GET
路径： /api/audit-logs
是否鉴权： 是
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
| biz_type | string | 业务类型 |
| biz_id | number | 业务ID |
| operator_name | string | 操作人 |
| start_time | string | 开始时间 |
| end_time | string | 结束时间 |
| page_no | number | 页码 |
| page_size | number | 每页条数 |
18. 接口补充说明
18.1 错误处理
- 所有接口错误都必须返回统一结构。
- 不能仅返回文本消息。
- 第三方失败需记录原始异常并转换为
40009。
18.2 状态流转限制
- 若目标状态不允许，返回
40005。 - 若资源不存在，返回
40004。 - 若重复提交，返回
40006。
18.3 字段保留策略
- 订单、审批、物流、识别、附件等均保留历史快照。
- 不建议直接修改历史快照字段，除非业务上确有修正记录。
19. 字段映射检查表
为了统一《确定版需求说明书》《数据库.sql》《系统标准API文档》的字段口径，新增《字段映射检查表.md》作为三份文档之间的字段对照依据。
字段映射检查表定义了：
- 核心业务对象的统一字段名
- 数据库字段命名
- API 字段命名
- 状态字段统一口径
- 三份文档的对齐说明
后续接口联调、前后端协作、数据库建模均以三份文档及《字段映射检查表.md》为准。