一、爱回收 API 接口整体概述
爱回收 API 接口是爱回收开放平台提供的标准化数据交互通道，旨在赋能第三方平台（电商、手机品牌商、企业服务平台等）快速集成二手电子产品回收、估价、订单管理等核心能力，实现 “估价 - 下单 - 回收 - 结算” 全流程数字化联动。其核心优势在于：数据实时同步（如报价、库存、物流状态）、功能模块化拆分（适配不同业务场景）、安全机制完善（签名验证、权限分级），目前已广泛应用于 “以旧换新”“企业资产回收”“个人闲置回收” 等场景。
二、核心功能模块分类及接口详解
爱回收 API 接口按业务流程分为五大核心模块，每个模块包含特定功能接口，以下为关键接口的用途、请求方式及核心参数说明：
1. 设备估价模块（核心基础模块）
用于获取二手电子设备（手机、电脑、平板等）的实时回收报价，是所有回收业务的起点。
接口名称 | 请求方式 | 核心用途 | 必传参数 | 返回结果 |
设备型号列表查询 | GET | 获取支持回收的设备品牌、型号、配置清单（如手机内存、颜色） | brand_id（品牌 ID）、category_id（设备品类 ID） | 型号 ID、型号名称、支持配置项 |
设备估价接口 | POST | 传入设备配置及成色信息，获取实时回收价 | model_id（型号 ID）、storage（存储容量）、color（颜色）、condition（成色等级：1 - 全新未拆封 / 2-99 新 / 3-95 新等）、fault（故障情况：0 - 无故障 / 1 - 屏幕损坏等） | 回收基准价、加价券金额、最终回收价、回收条件说明 |
估价规则查询接口 | GET | 获取当前设备的估价逻辑（如折旧系数、故障扣减规则） | model_id（型号 ID） | 折旧规则、故障扣减标准、保价期限 |
2. 订单管理模块（交易核心模块）
负责回收订单的创建、状态查询、取消等全生命周期管理，对接回收业务的核心流程。
接口名称 | 请求方式 | 核心用途 | 必传参数 | 返回结果 |
回收订单创建 | POST | 基于估价结果创建回收订单 | estimate_id（估价 ID）、user_name（用户姓名）、phone（手机号）、address_id（收货地址 ID）、payment_type（收款方式） | 订单号、预约回收时间、物流单号、订单状态（待上门 / 待邮寄） |
订单状态查询 | GET | 实时查询订单进度（如已接单、已质检、已付款） | order_no（订单号）、app_key（应用密钥） | 订单状态、操作时间、质检结果（如是否符合预估成色）、结算金额 |
订单取消接口 | POST | 支持用户或商户取消未发货 / 未质检订单 | order_no（订单号）、cancel_reason（取消原因） | 取消结果、退款状态（若已支付） |
3. 物流对接模块（履约支撑模块）
实现回收物流的轨迹追踪、上门回收预约等功能，衔接订单与物流履约环节。
接口名称 | 请求方式 | 核心用途 | 必传参数 | 返回结果 |
物流轨迹查询 | GET | 查询回收包裹的实时物流状态（如已揽收、在途、已签收） | logistics_no（物流单号）、logistics_company（物流公司编码） | 物流节点、操作时间、所在地点 |
上门回收预约 | POST | 预约上门回收时间（仅支持开通上门服务的城市） | order_no（订单号）、reserve_date（预约日期）、reserve_time（预约时段） | 预约结果、上门回收员信息、联系电话 |
收货地址管理 | POST | 新增 / 查询用户收货地址（用于邮寄回收） | user_id（用户 ID）、address_info（地址详情）、is_default（是否默认地址） | 地址 ID、地址校验结果（如是否支持物流配送） |
4. 结算与支付模块（资金流转模块）
处理回收订单的结算、退款、发票申请等资金相关操作，确保资金流转透明可追溯。
接口名称 | 请求方式 | 核心用途 | 必传参数 | 返回结果 |
订单结算查询 | GET | 查询订单最终结算金额（含质检调整后的价格） | order_no（订单号） | 结算金额、调整原因（如成色不符扣减）、付款状态 |
退款申请接口 | POST | 因质检不符等原因申请退款（仅支持符合退款规则的订单） | order_no（订单号）、refund_reason（退款原因）、proof（凭证图片 URL） | 退款申请状态、审核结果、退款到账时间 |
发票申请接口 | POST | 申请回收订单的电子发票（个人 / 企业） | order_no（订单号）、invoice_type（发票类型）、invoice_info（发票抬头 / 税号） | 发票申请状态、电子发票 URL、开票时间 |
5. 公共基础模块（通用支撑模块）
提供基础配置查询、数据字典同步等通用功能，保障接口调用的稳定性与适配性。
接口名称 | 请求方式 | 核心用途 | 必传参数 | 返回结果 |
支持回收品类查询 | GET | 获取爱回收当前支持回收的所有设备品类（手机、电脑、平板等） | -（无需必传参数） | 品类 ID、品类名称、支持品牌列表 |
城市服务查询 | GET | 查询支持回收服务的城市及服务类型（上门 / 邮寄） | province_id（省份 ID） | 城市 ID、城市名称、支持的服务类型、物流时效 |
接口状态监控 | GET | 检查爱回收 API 开放平台的服务可用性 | app_key（应用密钥） | 服务状态（正常 / 维护中）、响应延迟、最近维护时间 |
三、API 接口调用规范（实操核心）
1. 接口调用基础格式
- 请求地址：所有接口统一前缀为 https://openapi.aihuishou.com/v1/，后续拼接具体接口路径（如估价接口路径为 device/estimate）。
- 数据格式：请求与返回数据均为 JSON 格式，编码统一为 UTF-8。
- 请求头必填字段：
- App-Key：应用密钥（申请后由爱回收开放平台提供）；
- Timestamp：请求时间戳（毫秒级，与爱回收服务器时间差不超过 5 分钟）；
- Sign：签名（按 App-Key + Timestamp + 密钥 的顺序拼接后，通过 MD5 加密生成，确保请求合法性）；
- Content-Type：固定为 application/json。
2. 签名生成示例（Java 代码片段）
md5 = MessageDigest.getInstance("MD5");
byte[] bytes = md5.digest(rawStr.getBytes(StandardCharsets.UTF_8));
StringBuilder sb = new StringBuilder();
for (byte b : bytes) {
String hex = Integer.toHexString(b & 0xFF);
if (hex.length() == 1) {
sb.append("0");
}
sb.append(hex);
}
return sb.toString().toUpperCase();
} catch (NoSuchAlgorithmException e) {
throw new RuntimeException("MD5加密失败", e);
}
}
3. 调用限制与节流规则
- QPS 限制：普通商户账号单接口 QPS 限制为 10（每秒最多 10 次请求），企业级账号可申请提升至 50；
- 请求频率控制：同一 IP 地址单日调用总量不超过 10000 次，超出后将临时封禁 24 小时；
- 重试机制：接口调用失败（如超时、5xx 错误）时，建议间隔 3-5 秒重试，重试次数不超过 3 次，避免频繁重试导致封禁。
4. 错误码说明（高频错误排查）
错误码 | 错误描述 | 排查方向 |
400 | 参数错误 | 检查必传参数是否缺失、参数格式是否符合要求（如手机号、日期格式） |
401 | 未授权 / 签名错误 | 验证 App-Key 是否有效、签名生成逻辑是否正确、Timestamp 是否超时 |
403 | 权限不足 | 当前账号未开通该接口的调用权限，需申请权限升级 |
404 | 接口路径错误 | 检查接口路径是否拼写正确（如是否多写 / 少写斜杠） |
500 | 服务器内部错误 | 爱回收平台服务异常，建议稍后重试并联系技术支持 |
503 | 服务繁忙 | 临时超出 QPS 限制，需降低调用频率或申请提升 QPS |
四、权限申请流程（从注册到调用全步骤）
1. 前置准备条件
- 主体资质：个人开发者需提供身份证正反面照片；企业商户需提供营业执照、法人身份证、对公账户信息；
- 业务场景说明：需明确 API 接口的使用场景（如电商平台以旧换新、企业资产回收）、预估调用量、合作周期；
- 技术对接文档：需提供技术联系人信息、系统架构说明（确保对接合规性）。
2. 具体申请步骤
- 注册开放平台账号：访问爱回收开放平台官网（https://open.aihuishou.com/），点击 “注册”，选择 “个人开发者” 或 “企业商户” 类型，完成账号注册与实名认证；
- 创建应用：登录后进入 “控制台 - 应用管理”，点击 “创建应用”，填写应用名称、应用描述、使用场景，提交审核（审核时长 1-3 个工作日）；
- 申请接口权限：应用审核通过后，进入 “权限管理”，选择需要调用的接口模块（如估价模块、订单模块），提交权限申请，企业商户需额外上传业务合作协议；
- 获取密钥与测试：权限申请通过后，在 “应用管理” 中获取 App-Key 与 Secret（密钥需妥善保管，避免泄露），下载官方 SDK（支持 Java、Python、PHP 等语言），进行测试环境调用；
- 正式上线：测试环境调用无问题后，联系爱回收开放平台技术支持，申请切换至生产环境，完成正式上线前的联调，即可开展业务。
3. 权限升级说明
- 初始账号默认仅开通 “设备估价模块”“公共基础模块” 的基础接口，如需调用 “订单管理”“结算支付” 等核心接口，需提交业务场景说明与资质材料，申请权限升级；
- 企业级账号可申请定制化接口（如批量估价接口、企业专属结算接口），需与爱回收签订专项合作协议，周期约 7-15 个工作日。
五、对接注意事项与最佳实践
- 数据安全保障：传输过程中需采用 HTTPS 加密，避免明文传输敏感信息（如用户手机号、银行卡号）；Secret 需存储在服务器端，禁止前端明文存储，防止泄露；
- 数据同步机制：订单状态、物流信息等关键数据建议定时同步（如每 5 分钟查询一次订单状态），确保数据一致性，避免因异步更新导致业务异常；
- 用户体验优化：调用估价接口时，需提前告知用户设备成色、故障情况的判断标准，避免因质检结果与预估不符导致用户投诉；
- 异常处理预案：针对接口调用失败、订单状态异常（如质检不符）等场景，需设计兜底方案（如提供人工客服介入通道、退款快速处理流程）；
- 合规性要求：使用 API 接口时需遵守《爱回收开放平台服务协议》，不得将接口用于非法用途（如批量爬取设备价格、虚假订单创建），否则将终止合作并追究法律责任。
