接入车型保养套餐 API 时，建议按“先拿保养项目、再取项目明细”的顺序处理，并在车型 ID 或 VIN、公里数和月数之间保留可追溯的输入关系，避免把参考价格直接当成维修报价。
这组接口解决什么问题
极速车服车型保养套餐查询的官方说明是：可以按车型或 VIN 查询一个车型的保养项目，也可以进一步查询某个保养项目使用的产品、价格和用量等信息。它适合做保养提醒、维修接待预检、配件推荐和服务顾问工作台的基础数据层。
接口页把能力拆成多个端点：
| 业务动作 | 官方接口 | 主要输入 |
|---|---|---|
| 保养项目分类 | https://api.jisuepc.com/maintenance/itemclass | appkey |
| 查询车型保养项目 | https://api.jisuepc.com/maintenance/itemlist | carid/vin 的实际必填规则需联调确认，可带 km、month |
| 查询保养项目明细 | https://api.jisuepc.com/maintenance/detail | maintainid、itemclassid、carid，省略规则需联调确认 |
| 配件分类与品牌 | maintenance/class、maintenance/brand | appkey |
| 获取保养产品 | https://api.jisuepc.com/maintenance/product | classid、车型/VIN、品牌条件 |
正式调用前需要申请接口权限，并把 APPKEY 放在服务端配置中。文档示例中的 yourappkey 只是占位符，不能写入前端代码、公开仓库或普通业务日志。
第一步：先确认车型输入
itemlist 当前文档存在需要特别留意的口径差异：参数表把 carid 标为必填，同时又在 vin 说明中写明“carid 和 vin 至少选一个”。因此，不能仅凭页面文字承诺所有账号都支持纯 VIN 请求。已有具体车款 ID 时可按官方示例传 carid；只有 VIN 时，应先用在线测试或测试环境确认实际校验规则，必要时先通过 VIN 锁定车型。无论走哪条路径，都应保存脱敏后的 VIN 摘要、车型 ID 和解析来源，便于排查不一致。
公里数 km 和月数 month 都是可选条件。它们不是两个互斥的接口，而是保养周期判断的上下文：例如车辆可能先达到时间周期，也可能先达到里程周期。数据库中不要只保存一条“下次保养日期”，应保留本次传入的 km、month 以及接口返回的 tips，由前端再决定如何展示。
一个最小的 GET 请求可以写成下面这样，密钥仍然只放在服务端：
GET https://api.jisuepc.com/maintenance/itemlist
?carid=21617&vin=&km=7500&month=12&appkey=YOUR_APPKEY
这里的 21617 和 7500、12 是文档示例中的输入形态，接入时应替换为真实业务值，不要把示例结果当作你的车辆结果。
第二步：保存项目列表，再按 ID 取明细
项目列表返回 carid、vin、km、month、maintainid、name、tips 和 itemclassid 等字段。推荐先把这层保存成“保养建议快照”，其中 maintainid 是后续查询明细的关联键，itemclassid 用于项目分类。
拿到项目列表后，再调用 maintenance/detail。该参数表把 maintainid、itemclassid 和 carid 都标为必填，但 maintainid 的说明又写着“和 itemclassid 至少选择一个”。官方请求示例同时传了三项；在实际规则尚未联调确认前，生产接入宜按示例传齐，不应擅自省略。返回结果包括项目名称、产品清单、数量、参考价格、零件号、品牌和产品分类等字段；机油、轮胎等产品还可能出现 partsspec、volume、viscosity、grade、level、fronttiresize 和 reartiresize。
这两步不要合并成一次“按名称查项目”：项目名称可能适合展示，但 maintainid 才能稳定关联明细。落库时可分成三类：
- 周期信息：
km、month、tips； - 项目身份：
maintainid、itemclassid、name； - 产品属性：
number、brand、partsspec、volume、viscosity、轮胎规格等。
参考价格和实际报价要分开
文档把明细中的 price 标为“价格 参考价格”。因此它适合用于保养方案预估、筛选和排序，不应直接承诺给车主的最终结算金额。最终报价还可能受品牌选择、门店服务、库存、工时和采购渠道影响。系统可以同时保存 reference_price、报价单号和报价生成时间，把接口快照与业务成交记录分开。
同理，返回产品清单或轮胎规格只能说明接口给出的匹配参考。VIN/车型查询结果不等于最终采购或装车保证，涉及安全件、轮胎和机油规格时，仍应结合车辆实物、维修手册或人工复核。
错误处理要按层级显示
保养接口的业务错误码包括 201“VIN 不正确”、202“VIN 无法锁定车型”、203“车型 ID 不能为空”、204“项目 ID 错误”、207“车型 ID 错误”和 220“没有信息”。系统错误码还包括 101 APPKEY 不存在、102 已过期、103 无权限、104 超过次数限制、105 IP 被禁止、106 IP 请求超限等。
前端不应把所有错误都显示为“暂无保养信息”。建议至少区分三类：输入需要修正、鉴权或配额需要运维处理、查询成功但当前没有数据。这样服务顾问才能知道是让客户补充 VIN，还是联系接口管理员。
上线前的检查清单
- 车型 ID 来自具体车款，而不是模糊的车系名称。
- VIN、里程和月数按原始请求保存，敏感字段按内部规范脱敏。
itemlist和detail分层缓存，避免每次刷新重复拉取明细。- 参考价格、产品规格和库存/成交价使用不同字段与时间戳。
- APPKEY 只在服务端使用，日志只保留请求追踪 ID 和脱敏参数。
- 查询结果进入报价或采购前，保留车型适配和人工复核状态。
总结
车型保养套餐 API 的稳定接法是：先按已联调确认的 carid/VIN 规则获取项目列表，再按官方示例传入 maintainid、itemclassid 和 carid 取得产品明细；最后把参考价格、配件规格与实际报价分开管理。由于当前参数表与说明存在口径差异，上线前应以实际测试和极速车服车型保养套餐查询官方文档的最新状态为准。
