企业微信 API 实战：接口返回部分成功时，业务状态应该如何设计

在企业微信 API 开发中，一个业务请求可能涉及多条数据或多个接口调用，并不一定全部执行成功。

比如客户在外部群提交批量订单查询，系统需要处理100条订单，其中95条成功，5条失败。

如果直接将任务标记为成功，会遗漏失败数据；如果标记为失败，又无法准确反映已经完成的部分。

使用星云API对接企业微信消息时，可以通过细分业务状态和执行结果记录，处理这种部分成功的情况。

一、增加部分成功状态

传统任务通常只有成功和失败两种结果，但批量业务建议增加PARTIAL_SUCCESS状态。

状态	说明
PENDING	等待执行
RUNNING	正在处理
SUCCESS	全部执行成功
PARTIAL_SUCCESS	部分成功、部分失败
FAILED	全部执行失败
TIMEOUT	执行超时，结果待确认

这样可以更准确地反映任务的实际处理情况。

二、分别记录每条数据的执行结果

假设一个任务需要处理100条订单，可以保存以下信息：

{
  "taskId": "TASK1001",
  "total": 100,
  "success": 95,
  "failed": 5,
  "status": "PARTIAL_SUCCESS"
}

除了汇总数据，还应该保存每条订单的执行状态、错误原因和业务编号。

后续需要重新处理失败订单时，可以直接筛选失败记录，而不必重新执行全部任务。

三、设计任务状态判断流程

客户发送业务请求
        ↓
创建任务并记录任务ID
        ↓
调用后台业务接口
        ↓
收集每条数据执行结果
        ↓
统计成功与失败数量
        ↓
判断最终任务状态
        ↓
全部成功 → SUCCESS
部分成功 → PARTIAL_SUCCESS
全部失败 → FAILED
        ↓
保存执行记录
        ↓
向客户反馈处理结果

如果部分请求仍在执行或结果未知，应继续保留处理中状态，不能提前认定最终结果。

四、部分失败的数据怎么处理

1. 只重试失败数据

对于网络异常、临时超时等情况，可以筛选失败记录进行重试，避免重复调用已经成功的业务接口。

2. 做好幂等控制

每条业务数据都需要独立的幂等标识，防止重试过程中重复创建订单或重复执行其他操作。

3. 区分失败原因

参数错误、权限不足通常需要修正后重新提交；临时网络异常则可以考虑自动重试。

4. 保留完整执行记录

记录每条数据的状态、重试次数、错误信息和最终结果，方便后续排查。

五、如何向客户反馈部分成功结果

任务处理完成后，可以通过企业微信 API 向原始会话推送汇总结果。

例如：

任务编号：TASK1001
处理总数：100条
成功：95条
失败：5条
任务状态：部分完成

如果失败记录支持重新处理，还可以提供任务编号，方便客户查询或发起失败项重试。

需要注意，业务执行状态和消息发送状态应分开记录，避免出现业务已经完成，但消息推送失败却被误判为业务失败的情况。

六、总结

企业微信 API 处理批量业务时，不能简单地用成功或失败表示所有执行结果。

通过PARTIAL_SUCCESS状态、逐条执行记录、失败项重试和幂等控制，可以更加准确地管理业务结果，减少重复操作。

使用星云API对接企业微信消息收发能力，再结合后台任务管理，可以实现从客户提交请求、批量处理到最终结果反馈的完整流程。

相关接口参考顶部星云官网卡片里的接口文档。