订单通知

本文档面向三方开发者，详细说明洗车服务订单状态变更时的回调通知机制。回调通知是洗车API系统与合作方系统之间实现订单状态实时同步的核心机制，确保双方数据的一致性和业务流程的顺畅执行。

业务流程关联

回调通知与洗车服务核心业务流程紧密关联，主要在以下场景触发：

下单发码流程

触发时机：发码成功（状态1）

业务价值：确保合作方及时获取核销码生成状态

关联接口：POST /api/order/create

到店核销流程

触发时机：核销成功（状态2）

业务价值：实时同步服务使用情况，便于合作方进行业务统计

关联接口：门店核销系统内部接口

订单完成流程

触发时机：订单完成（状态3）

业务价值：通知服务完成，便于合作方进行财务结算及后续营销

关联接口：无关联接口，门店核销6小时后自动完成

退单流程

触发时机：订单取消（状态6）

业务价值：同步退单状态，确保财务结算准确性

关联接口：POST /api/order/cancel

通知机制详解

通知触发条件

回调通知在以下订单状态变更时自动触发：

状态码	状态描述	业务场景	触发条件
1	发码成功	核销码生成	系统自动生成核销码后
2	核销成功	到店服务	门店验证核销码成功后
3	订单完成	服务结束	服务完成，订单生命周期结束
6	订单取消	用户主动取消	用户主动申请取消订单后

重试机制

为确保通知的可靠性，系统实现了智能重试策略：

重试间隔：10s, 10s, 10s, 30s, 60s, 120s, 360s, 600s

重试条件：

合作方系统返回非"success"响应

网络连接超时（超过5秒）

HTTP状态码非200

响应格式不符合规范

重试限制：

最大重试次数：8次

总重试时长：最长约20分钟

重试失败后：系统记录失败日志，不再重试

通知地址要求

合作方需在发现周边开放平台后台配置回调通知地址，技术要求如下：

网络要求：

必须支持公网访问

建议使用HTTPS协议确保数据传输安全

响应时间不超过5秒

技术要求：

支持HTTP POST方法

正确处理application/json格式数据

返回标准JSON格式响应

实现幂等性处理逻辑

接口技术规范

请求规范

属性	值
请求方法	POST
内容类型	application/json
字符编码	UTF-8
请求头	Content-Type: application/json

通知数据结构

字段名称	字段类型	必填	长度限制	描述
outOrderNo	String	是	1-64	发现周边系统生成的唯一订单号
channelOrderNo	String	是	1-64	合作方系统的订单号
orderTitle	String	是	1-100	订单标题，如"标准洗车服务"
orderSubTitle	String	否	0-100	订单副标题，如"轿车专用"
orderDesc	String	否	0-500	订单详细描述
originPrice	Double	是	-	门市价，保留2位小数
salePrice	Double	是	-	销售价，保留2位小数
settlePrice	Double	是	-	结算价，保留2位小数
quantity	Integer	是	1-999	购买数量默认1
totalSettleAmount	Double	是	-	总结算价（settlePrice × quantity）
status	Integer	是	-	订单状态，见状态说明

响应规范

成功响应：

   success


**响应要求**：
- HTTP状态码必须为200
- Content-Type必须为application/json
- message字段值为"success"才视为成功
- 其他任何响应都会触发重试机制

### 安全建议

- 监控异常通知请求
- 实现IP白名单机制（可选）

## 集成指南

### 开发流程

1. **环境准备**
   - 在发现周边开放平台测试环境后台配置回调通知地址
   - 准备测试环境进行联调测试

2. **接口开发**
   - 实现POST接口接收通知
   - 实现幂等性处理机制

3. **测试验证**
   - 使用测试数据进行功能测试
   - 验证各种异常场景处理

4. **上线部署**
   - 配置生产环境通知地址
   - 启动监控和日志记录

业务流程关联#

下单发码流程#

到店核销流程#

订单完成流程#

退单流程#

通知机制详解#

通知触发条件#

重试机制#

通知地址要求#

接口技术规范#

请求规范#

通知数据结构#

响应规范#