接入车型大全 API 时，先分清品牌、品牌子公司、车型和具体车款四级对象，再设计外部 ID、上下级关系和更新状态，避免把不同层级混在一张平面表里。

官方接口先看清层级

截至 2026 年 8 月 10 日，极速车服车型大全 API页面说明：1 级为车品牌，2 级为车品牌子公司，3 级为车型，4 级为具体车款。文档同时公开了以下接口地址：

用途 接口 关键输入
获取所有品牌 https://api.jisuepc.com/car/brand appkey
根据品牌获取车型 https://api.jisuepc.com/car/type parentid、appkey
根据车型获取车款 https://api.jisuepc.com/car/car parentid、appkey
获取具体车型详情 https://api.jisuepc.com/car/detail carid、appkey
车型关键词搜索 https://api.jisuepc.com/car/search keyword、appkey

这些地址和参数以官方文档为准，文章中的 YOUR_APPKEY 仅为占位符，不代表可直接调用的密钥。

需要注意的是，当前 car/car 参数表把 sort 标为必填，同时说明“默认不排序”，两处表述并不完全一致。正式接入时应显式传递排序参数并用账号联调确认，不要仅凭“默认”二字省略参数。

第一步：品牌接口不要只存名称

car/brand返回示例包含 id、name、initial、parentid、logo 和 depth。落库时建议至少保留：

brand_id        外部品牌 ID
brand_name      品牌名称
parent_id       上级 ID
depth           层级
logo_url        图片地址
source          数据来源
last_seen_at    最近一次同步时间

这里的表结构是系统设计建议，不是官网规定的数据库表。外部 ID 应作为稳定关联键，名称用于展示和搜索；不要把名称当作唯一键，否则同名品牌、名称变更或多语言展示都会造成重复数据。

同步时可先请求全量品牌，写入临时表后按外部 ID 比对，再更新名称和层级。删除策略要谨慎：接口本次未返回的记录先标为“本批次未出现”，不要立即物理删除历史工单引用过的品牌。

第二步：车型接口要保留车系和具体车款关系

car/type使用上级 parentid 获取车型层级，返回示例中既有品牌子公司，也有车型列表。车型记录可能包含 id、name、fullname、initial、logo、salestate 和 depth。

可以把“车系”和“具体车款”拆成两张逻辑表，或者在一张邻接表中用 parent_id 表示上下级：

业务对象 需要保留的字段 作用
车系 id、name、fullname、depth、salestate 车型导航与聚合
具体车款 id、name、parent_id、depth 配件、保养和 VIN 关联
关系 source、sync_version、last_seen_at 同步和审计

不能把“奥迪 A4L”这个展示名直接当作具体车款。年款、动力、变速箱和配置不同，可能对应不同的 carid。当业务需要配件适配时，应继续请求具体车款详情或转到 EPC/VIN 结果，而不是停留在车系层。

第三步：车款列表与详情分别处理

car/car示例通过 parentid 获取某个车型下的具体车款，并返回 price、yeartype、productionstate、salestate、sizetype 等字段；部分返回示例还包含上市时间、排量、变速箱、座位数和车型组信息。

推荐的处理顺序如下：

  1. 用品牌或车系的外部 ID 请求车款列表；
  2. 对每个车款保存 carid、名称、年款、生产状态和销售状态；
  3. 只有在详情页或业务确实需要时，才按 carid 请求 car/detail；
  4. 将车辆基本信息和车身、发动机等详情作为可变属性保存，并带上同步版本；
  5. 配件业务引用 carid，不引用名称字符串。

具体车型详情接口示例要求 carid，返回参数包括官方指导价、年款、生产状态、销售状态、尺寸类型和深度等。汽车价格、销售状态等内容可能发生变化，不应在本地永久写死；历史报价或工单需要保存当时的快照。

车型搜索适合做入口，不适合直接定案

car/search接收 keyword。当前返回参数说明列有关键词、车型 ID、名称、图片、价格、年款、生产状态、销售状态和车辆等级等候选信息。它很适合搜索框联想或客服初筛，但一个关键词可能命中多个年份和配置。

建议把搜索结果建模为“候选集”：

search_request_id
原始 keyword
候选 carid
命中名称与年款
业务状态：待确认 / 已确认 / 已排除
确认来源：VIN / 客户选择 / 人工复核

当用户要查配件时，候选集不能直接进入报价。应要求用户选择具体车款，或补充 VIN，再把确认后的 carid 传给 EPC、保养或配件接口。

一个可维护的同步流程

品牌全量同步
      ↓
按 parentid 展开车系
      ↓
按车型 ID 展开具体车款
      ↓
按需补充 car/detail
      ↓
保存版本、状态和来源
      ↓
将确认后的 carid 交给 EPC/VIN 业务

每次同步至少记录请求时间、接口地址、参数摘要、HTTP 结果、业务 status、错误消息和数据版本。APPKEY 只放在服务端配置或密钥管理系统中，日志里不要打印完整值。对于 201“上级 ID 错误”、202“车型 ID 错误”、205“没有信息”等业务错误，应转成可读的失败状态，而不是当作空数组继续运行。

接入前的验收清单

  • 品牌、车系、具体车款使用不同层级和外部 ID；
  • 年款、生产状态和销售状态可更新，历史记录可追溯；
  • 关键词搜索结果进入候选状态，不自动变成适配结论；
  • carid 可以被配件或 EPC 业务继续引用；
  • APPKEY 未出现在前端、异常堆栈和普通业务日志；
  • 接口超时、业务错误和空结果都有重试或人工处理分支；
  • 文档价格、套餐和字段变更会由负责人定期复核。

总结

车型大全 API 的核心是把四级车型层级和外部 ID 保存清楚：品牌负责入口，车系负责聚合，具体车款负责配件和业务关联，详情接口负责补充属性，搜索接口负责生成候选。极速车服官方文档已经给出 brand、type、car、detail 和 search 的接口说明，企业接入时应在此基础上增加版本、来源、状态和人工确认字段，避免把展示名称或一次搜索结果当作永久适配关系。

标签：