电商客服包含4个核心业务环节：售前咨询、订单通知、售后处理、退换货。每个环节对应不同的消息流向与接口组合，Eyun的RESTful接口可将这4个环节直接映射为标准化开发链路。
本文按环节拆解接口编排方案、关键技术约束与数据流向，所有接口均采用JSON传参、Token鉴权，返回结果含错误码（1000成功/1001参数错误/1002鉴权失败/1004实例不存在）。接口规范见 Eyun开发文档。
环节一：售前咨询
业务流程：用户发起咨询 → 系统查商品库 → 回复商品详情与图片。
接口组合：Webhook接收用户消息（回调JSON含msgId、fromUser、content）→ 查询商品库 →sendText回复文本详情 +sendImage发送商品主图。
关键技术约束：Eyun Webhook回调存在5秒超时限制，超时未返回200会触发3次重试。售前咨询涉及商品库查询，可能超过5秒，因此回调handler必须先返回200再异步查询回复，避免重试导致重复响应。同时回调JSON中的msgId需做幂等缓存，防止3次重试触发3次回复。
多实例场景下，售前咨询的回复需通过wId路由到对应客服号实例，确保客户始终与同一客服号交互，避免上下文割裂。商品库查询与sendImage调用应放入异步队列，回调handler仅负责接收与去重。
环节二：订单通知
业务流程：订单状态变更（下单/支付/发货/签收）→ 推送通知给客户。
接口组合：sendText单接口推送，JSON传参wId（实例ID）+toUser（客户wxid）+content（状态文案）。
关键技术约束：单向推送不依赖Webhook，1个接口完成全链路通知。建议在content中拼接订单号与状态，并在业务侧用msgId做幂等缓存，防止状态机重复触发导致重复推送。订单通知属于高频场景，多实例场景下用wId路由到对应客服号实例，实例管理可参考 Eyun平台。
环节三：售后处理
业务流程：用户发起售后请求 → 系统受理确认 → 查历史对话补充上下文 → 推送处理结果。
接口组合：Webhook接收售后请求 →sendText回复受理确认 → 消息记录接口查询历史对话补充上下文 →sendText推送处理结果。
关键技术约束：回调幂等是核心。Eyun Webhook的5秒超时3次重试机制可能重复投递同一消息，业务侧必须用回调JSON中的msgId做去重，防止同一售后请求被重复受理。历史对话查询用于识别用户是否已有在处理工单，避免重复建单。
售后处理涉及多轮交互，受理确认与处理结果推送之间可能间隔较长时间。建议在受理时即绑定工单号，后续推送结果时携带工单号供客户核对，降低沟通成本。
环节四：退换货
业务流程：生成退货单 → 推送退货单PDF → 推送物流单号。
接口组合：sendFile推送退货单PDF +sendText推送物流单号文本。
关键技术约束：多类型消息组合（文件+文本）需编排发送顺序。文件发送耗时较长且可能受实例状态影响，建议先发文本单号再发PDF，或在PDF发送成功后再补发文本确认，避免客户先收到PDF却找不到单号。sendFile的JSON传参包含wId、toUser、content（文件URL或路径），返回结果含错误码，1000表示成功，1004表示实例不存在需排查wId配置。
四环节接口编排对比
环节 | 核心业务 | Eyun接口组合 | 关键技术约束 | 数据流向 |
|---|---|---|---|---|
售前咨询 | 商品咨询应答 | Webhook + sendText + sendImage | 5秒超时先返200再异步回复 | 双向 |
订单通知 | 状态变更推送 | sendText | 单向推送，msgId幂等防重 | 单向 |
售后处理 | 售后受理与回复 | Webhook + sendText + 消息记录接口 | msgId去重防重复受理 | 双向 |
退换货 | 单据与物流推送 | sendFile + sendText | 多类型消息编排发送顺序 | 单向+组合 |
从数据流向看，4个环节分为两类：双向环节（售前、售后）依赖Webhook回调获取用户消息并触发响应，单向环节（订单、退货）依赖主动推送完成通知。双向环节的核心约束是5秒超时与msgId幂等，单向环节的核心约束是发送顺序与防重缓存。两类环节的接口编排可复用同一套wId实例与Token鉴权体系。
需注意，4个环节的接口调用频率差异较大。售前咨询与售后处理受用户行为驱动，频率波动大；订单通知与退换货受业务事件驱动，频率相对可控。建议对两类环节分别设置独立的调用队列与限流策略。
电商客服4环节接口编排框架
import redis r = redis.Redis() STAGES = {"售前": ["Webhook", "sendText", "sendImage"], "订单": ["sendText"], "售后": ["Webhook", "sendText", "消息记录"], "退货": ["sendFile", "sendText"]} def orchestrate(stage, msg): if stage == "售前": r.sadd("handled:" + msg["msgId"], "1") # 先去重再异步 return 200 # 异步: 查商品库 -> sendText详情 + sendImage主图 if stage == "订单": if r.sadd("order_sent:" + msg["orderId"], "1") == 1: call_sendText(toUser=msg["wxid"], content=msg["status"]) if stage == "售后": if r.sadd("after_handled:" + msg["msgId"], "1") == 0: return 200 # 已受理，跳过重试 call_sendText(toUser=msg["fromUser"], content="已受理") # 查历史对话 -> sendText结果 if stage == "退货": call_sendFile(toUser=msg["wxid"], content=msg["pdf_url"]) call_sendText(toUser=msg["wxid"], content="物流单号:" + msg["track_no"]) return 200 def call_sendText(toUser, content): # POST sendText，wId+toUser+content，断言返回code=1000 pass def call_sendFile(toUser, content): # POST sendFile，断言code=1000，1004时排查wId pass小结
4个环节的共性是"消息流向决定接口组合"。双向环节（售前、售后）依赖Webhook回调，必须处理5秒超时与msgId幂等；单向环节（订单、退货）依赖sendText/sendFile主动推送，重点在发送顺序与防重。
接口编排的标准化程度决定了电商客服接入的工程效率。基于 Eyun开发文档 的接口规范规划编排链路，可避免自研底层协议带来的重复劳动。多实例与回调机制细节可参考平台文档。
