一、两层严谨区分：接口文档两部分撰写人

第一层：业务需求、功能说明（产品经理负责）

核心产出：接口是做什么的、给谁用、业务规则、用户场景、限制逻辑。产品不懂网络请求、加密、报文格式、错误码，只梳理业务逻辑。

第二层：技术调用规范（后端开发负责）

核心产出：请求地址、请求方式、请求头、入参 / 出参字段、数据类型、加密规则、报错码、调用限制、报文示例。开发基于代码实现，填充所有可落地的技术细节。

完整对外接口文档 = 产品写业务框架 + 后端填充全套技术细则。

案例 1：智能 AI 蓝牙耳机「设备解绑接口」

1、产品经理写的内容（业务层）

接口名称：耳机设备解绑接口业务说明：用户在配套 APP 内操作解绑蓝牙耳机；解绑后该耳机可被其他账号重新绑定；设备处于售后维修状态时不允许解绑；账号删除前必须解绑全部耳机设备，否则无法注销账号；解绑记录永久留存，用于设备售后溯源。

2、后端开发写的内容（技术层）

请求地址：https://api.headset.com/device/unbind请求方式：POST请求头部：Authorization 用户登录 token（必填）请求入参 JSON：

返回码定义：0000 解绑成功5001 token 失效，请重新登录5002 设备不存在5003 设备维修锁定，禁止解绑。

案例 2：蓝牙智能音箱「语音收藏歌曲接口」

1、产品经理写的内容（业务层）

接口名称：语音音频收藏接口业务说明：用户语音下达 “收藏这首歌” 指令，音箱上传音频标识完成收藏；普通用户最多收藏 200 首，会员无上限；已收藏歌曲重复收藏不会重复新增；用户可在 APP 收藏列表查看所有收藏音频。

2、后端开发写的内容（技术层）

请求地址：https://api.speaker.com/audio/collect请求方式：POST入参：userId、audioId、deviceMac字段约束：audioId 长度 16 位纯数字；限流规则：单设备 1 分钟最多调用 10 次，超限返回报错码 6008；返回参数：collectId、collectTime、currentCollectCount。

案例 3：智能两轮电动车「车辆设防上锁接口」

1、产品经理写的内容（业务层）

接口名称：电动车远程设防上锁接口业务说明：车主通过小程序远程给电动车上锁设防；设防后车辆发生震动、挪动会推送报警消息；车辆正在行驶中无法执行上锁操作；上锁成功后切断车辆电机供电。

2、后端开发写的内容（技术层）

请求地址：https://api.ebike.com/car/lock请求方式：POST敏感字段加密：车辆车架号采用 AES 对称加密传输入参：bikeSn（加密）、ownerUserId、operateType错误码：9001 车辆当前行驶中，禁止上锁9002 车辆离线，指令下发失败9003 用户无该车辆操作权限。

总结：

1. 描述用户场景、功能作用、业务限制、产品规则 → 产品经理。
2. 描述调用地址、传参格式、加密、限流、报错码、JSON 报文 → 后端开发。