接入易错点

 新投诉提醒须接入投诉通知回调

 说明：商家助手消费者投诉提醒为每日推送（9:00-22:00），且只发送给超管，不会每产生一条投诉就即时通知；需要实时提醒应接入投诉通知回调。
正确应该怎么做：① 调用创建投诉通知回调地址接口配置 HTTPS、无参数的回调地址；② 收到回调后验签，并在 5 秒内返回 200 或 204，业务异步处理；③ 按通知 ID 和投诉单号做幂等；④ 超管在商家助手员工管理中为员工开通查询消费者投诉权限，员工自行登录商家助手小程序查看；⑤ 未收到回调时主动查询投诉单详情。
典型反例：只依赖超管的商家助手提醒，不接入投诉通知回调，客服团队无法实时获知新投诉。
见 4012289719-投诉通知回调、4012068499-开发指引、4012458679-创建投诉通知回调地址、4012587539-交易投诉运营规范、kf.qq.com/faq/2403276ZVJVj240327IBYNFN.html、kf.qq.com/faq/250414a2MFrm250414aEzMbU.html。 

 新投诉可能到次日推送时段才被看到，容易超过1日首次回复、3日处理完成的时限，影响投诉处理时效考核。

 需邮件提醒时须基于投诉回调自行实现

 说明：消费者投诉2.0提供投诉通知回调，未提供独立的邮件通知功能；需要邮件提醒的商户应在收到投诉回调后自行发送邮件。
正确应该怎么做：① 调用创建投诉通知回调地址接口配置HTTPS回调地址；② 收到POST回调后先验签，验证通过及时返回200或204，业务处理异步执行；③ 使用通知ID和投诉单号做幂等，解密资源后获取complaint_id和事件类型；④ 按通知类型查询投诉单详情或协商历史，再触发自有邮件系统发送提醒并记录发送结果。
典型反例：直接把每一次回调都当成新事件发送邮件，没有按通知ID去重。
见 4012289719-投诉通知回调、4012076174-投诉通知回调、4012458679-创建投诉通知回调地址、4012458106-创建投诉通知回调地址、4012068499-开发指引、4012072858-开发指引。 

 未接入回调时无法获得实时投诉数据，也就无法自动发送邮件；重复回调未去重时可能产生重复邮件。

 投诉通知须按 action_type 分流处理

 说明：投诉通知回调的 action_type 用于标识用户提交投诉、继续投诉、留言、商户回复、退款审批及退款到账等具体动作，商户应按动作类型进入相应处理流程。
正确应该怎么做：① 验签并解密投诉通知，取得 complaint_id 与 action_type；② 对 CREATE_COMPLAINT、CONTINUE_COMPLAINT、用户留言、平台协助及退款状态变化等关注事件，按文档设置的统一分流逻辑调用查询投诉单详情或协商历史接口；③ 对非关注事件走默认处理，并保留异常监控；④ 如未收到通知，主动调用查询投诉单详情接口确认状态。
典型反例：只处理 CONTINUE_COMPLAINT，将其他投诉通知统一忽略，导致新投诉、用户留言或退款状态变化没有进入处理流程。
见 4012289719-投诉通知回调、4012076174-投诉通知回调、4012533436-查询投诉单详情、4012691648-查询投诉单详情 

 新投诉、续投、用户留言或退款状态变化可能未进入对应流程，投诉单无法及时响应和结单。

 投诉列表须按不超过30天分段查询

 说明：查询投诉单列表时，begin_date 与 end_date 必填，且查询日期跨度不得超过 30 天；接口使用 limit 与 offset 分页。
正确应该怎么做：① 按业务需要将查询区间拆成不超过 30 天的连续日期段；② 每段设置在 1 到 50 范围内的 limit，通过 offset 翻页直至取全 total_count；③ 对历史续投投诉按首次投诉时间所在日期段补查，不将“本次升级日期”作为唯一查询条件；④ 已知 complaint_id 时直接查询投诉单详情。
典型反例：一次传入跨越两个月的日期区间，或为覆盖首次投诉日期而把查询区间无限放大。
见 4012533431-查询投诉单列表、4012691285-查询投诉单列表、4012533436-查询投诉单详情、4012691648-查询投诉单详情、4012068499-开发指引、4012072858-开发指引 

 查询请求会被参数校验拦截，返回 PARAM_ERROR 或 INVALID_REQUEST，无法按预期拉取历史投诉数据。 

 投诉详情查询须按商户维度限流

 说明：查询投诉单详情接口限流为 6000 次/1800 秒，即30分钟6000次，按商户维度限制；开发指引另明确查询投诉单列表每分钟200次、商户反馈接口每分钟60次。
正确应该怎么做：① 以商户号为单位设计集中限流，多实例部署共享配额；② 使用队列削峰，按 1 秒、3 秒、10 秒指数退避；③ 批量处理优先使用查询投诉单列表分页，limit 不超过 50、日期跨度不超过 30 天；④ 需要调整额度时向对接运营申请，并以运营确认结果为准。
典型反例：多个服务实例各自按本地计数器限流，叠加后仍超过商户维度总限额。
见 4012533436-查询投诉单详情、4012533431-查询投诉单列表、4012068499-开发指引、4020801845-错误码。 

 超过限流返回“频率过快”，批量查询被拒绝，投诉处理延迟。