接入指南

快速开始

搜配云 API 是一组 HTTPS POST 接口。先拿 Key,再按车型或配件场景选接口。

  1. 商户开通「API 开放接口」应用。
  2. 在商户端「应用中心 - API 开放接口」生成 API Key。
  3. 请求头携带 Authorization: YOUR_API_KEY。JSON 接口同时设置 Content-Type: application/json。
Base URL:https://api.sopei.cn/api/sopei/openservice/v1.0

调用顺序

查产品前,先用「查询品牌品类」拿到 category_code 和 ten_brand_code。VIN 场景走 VIN 识别 / VIN 查车型 / VIN 查产品。

计费

每个接口有明确扣点。VIN 查产品按品类数分档:1-10 个品类 5 点,11-20 个品类 10 点;精准接口返回候选车型时免费。

统一响应

字段类型说明
code number 业务状态码。0 表示成功,非 0 表示失败。
msg string 状态文案。成功固定为 OK;失败为对应错误码的标准文案,参数错误时为 ParametersError。
status string ok 或 fail。可忽略,以 code 为准。
data object | array 成功时的业务数据。失败时通常不返回。
error string 失败时的补充说明。参数校验失败时,具体原因在此字段,而不是 msg。
参数错误的 msg 是 ParametersError,中文原因在 error。不要只判断 msg 中文。

接入指南

错误码

所有接口共用同一套响应信封。失败时看 code;4003 的具体原因在 error。

统一响应

字段类型说明
code number 业务状态码。0 表示成功,非 0 表示失败。
msg string 状态文案。成功固定为 OK;失败为对应错误码的标准文案,参数错误时为 ParametersError。
status string ok 或 fail。可忽略,以 code 为准。
data object | array 成功时的业务数据。失败时通常不返回。
error string 失败时的补充说明。参数校验失败时,具体原因在此字段,而不是 msg。

业务错误码

codemsg说明
0 OK 调用成功
10023 非法请求,授权无效 API Key 无效、缺失,或网关未能解析授权信息
4003 ParametersError 请求参数不合法。具体原因见 error,例如「无效的车架号(vin)」
4004 CallServiceError 下游服务调用失败
4005 PayloadTooLargeError 上传文件超过 20MB
4006 ConcurrentLimitError 触发并发限流
20001 暂无可查询品类数据 品类/品牌未开通、已关闭,或当前应用无权查询
20002 VIN码校验规则不通过 VIN 不是 17 位,或包含 I/O/Q,或为纯数字
20004 品类数量超过上限 VIN 查产品接口最多 20 个品类;其他相关接口最多 10 个品类
20005 品牌数量超过上限 VIN 查产品接口每个品类最多 5 个品牌;其他相关接口每个品类最多 10 个品牌
20006 VIN识别失败. VIN 图片未能识别出有效车架号
20007 此VIN码不符合校验规则或为非国标码,未能解析到车型。 仅 VIN 查车型接口在解析失败时返回。VIN 查产品失败时返回空数组
30001 商户的调用点数不足,请及时充值! 当前应用的剩余调用点数不足

车牌识别

上传车牌图片,识别车牌号。

POST https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/number/ocr
10 点 / 次 multipart/form-data
  • 表单字段名必须是 image,不是 file。
  • 文件必须是图片格式,大小不超过 20MB。
  • 车牌识别与 VIN 图片识别共用同一套文件校验文案,失败时 error 可能为「无效的VIN图片」。

请求参数

参数类型说明
image必填 file 车牌图片文件,multipart/form-data 上传

返回参数 data

参数类型说明
car_number string 识别出的车牌号

错误码

codemsg说明
10023 非法请求,授权无效 API Key 无效、缺失,或网关未能解析授权信息
4003 ParametersError 请求参数不合法。具体原因见 error,例如「无效的车架号(vin)」
4004 CallServiceError 下游服务调用失败
4005 PayloadTooLargeError 上传文件超过 20MB

调用示例

curl

curl -X POST 'https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/number/ocr' \
  -H 'Authorization: YOUR_API_KEY' \
  -F 'image=@/path/to/image.jpg'

Python

import requests

url = "https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/number/ocr"
headers = {"Authorization": "YOUR_API_KEY"}
files = {"image": open("/path/to/image.jpg", "rb")}
print(requests.post(url, headers=headers, files=files).json())

JavaScript

const fs = require("fs");
const https = require("https");
const FormData = require("form-data");

const form = new FormData();
form.append("image", fs.createReadStream("/path/to/image.jpg"));

const req = https.request({
  hostname: "api.sopei.cn",
  path: "/api/sopei/openservice/v1.0/carmodel/number/ocr",
  method: "POST",
  headers: { Authorization: "YOUR_API_KEY", ...form.getHeaders() },
}, (res) => {
  let body = "";
  res.on("data", (chunk) => { body += chunk; });
  res.on("end", () => console.log(JSON.parse(body)));
});
form.pipe(req);

Java

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/number/ocr"))
    .header("Authorization", "YOUR_API_KEY")
    .header("Content-Type", "multipart/form-data; boundary=----SopeiBoundary")
    .POST(HttpRequest.BodyPublishers.ofByteArray(multipartBody))
    .build();

PHP

<?php
$ch = curl_init("https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/number/ocr");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Authorization: YOUR_API_KEY"],
  CURLOPT_POSTFIELDS => ["image" => new CURLFile("/path/to/image.jpg")],
]);
echo curl_exec($ch);

成功响应

{
  "code": 0,
  "msg": "OK",
  "status": "ok",
  "data": {
    "car_number": "辽A34Qf1"
  }
}

失败响应

{
  "code": 4003,
  "msg": "ParametersError",
  "status": "fail",
  "error": "无效的VIN图片"
}

VIN 图片识别

上传车架号图片,识别 VIN。

POST https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/vin/ocr
5 点 / 次 multipart/form-data
  • 表单字段名必须是 image。
  • 识别失败返回 20006,不会返回空 vin。

请求参数

参数类型说明
image必填 file VIN 图片文件,multipart/form-data 上传

返回参数 data

参数类型说明
vin string 识别出的 VIN,未识别到时可能为空字符串

错误码

codemsg说明
10023 非法请求,授权无效 API Key 无效、缺失,或网关未能解析授权信息
4003 ParametersError 请求参数不合法。具体原因见 error,例如「无效的车架号(vin)」
4004 CallServiceError 下游服务调用失败
4005 PayloadTooLargeError 上传文件超过 20MB
20006 VIN识别失败. VIN 图片未能识别出有效车架号

调用示例

curl

curl -X POST 'https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/vin/ocr' \
  -H 'Authorization: YOUR_API_KEY' \
  -F 'image=@/path/to/image.jpg'

Python

import requests

url = "https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/vin/ocr"
headers = {"Authorization": "YOUR_API_KEY"}
files = {"image": open("/path/to/image.jpg", "rb")}
print(requests.post(url, headers=headers, files=files).json())

JavaScript

const fs = require("fs");
const https = require("https");
const FormData = require("form-data");

const form = new FormData();
form.append("image", fs.createReadStream("/path/to/image.jpg"));

const req = https.request({
  hostname: "api.sopei.cn",
  path: "/api/sopei/openservice/v1.0/carmodel/vin/ocr",
  method: "POST",
  headers: { Authorization: "YOUR_API_KEY", ...form.getHeaders() },
}, (res) => {
  let body = "";
  res.on("data", (chunk) => { body += chunk; });
  res.on("end", () => console.log(JSON.parse(body)));
});
form.pipe(req);

Java

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/vin/ocr"))
    .header("Authorization", "YOUR_API_KEY")
    .header("Content-Type", "multipart/form-data; boundary=----SopeiBoundary")
    .POST(HttpRequest.BodyPublishers.ofByteArray(multipartBody))
    .build();

PHP

<?php
$ch = curl_init("https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/vin/ocr");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Authorization: YOUR_API_KEY"],
  CURLOPT_POSTFIELDS => ["image" => new CURLFile("/path/to/image.jpg")],
]);
echo curl_exec($ch);

成功响应

{
  "code": 0,
  "msg": "OK",
  "status": "ok",
  "data": {
    "vin": "LSVAT4BR4GU818457"
  }
}

失败响应

{
  "code": 20006,
  "msg": "VIN识别失败.",
  "status": "fail",
  "error": ""
}

VIN 查车型

用 17 位车架号解析车型。多车型时返回多条。

POST https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/vin
2 点 / 次 application/json
  • 服务端会去掉 VIN 中的非字母数字字符后再校验。
  • 解析失败返回 20007,响应根级会额外带上 vin 字段。
  • 未解析到车型时可能返回空数组,根级同样可能带 vin。
  • cm_conf_level 由配置等级和驱动方式拼接而成。
  • 指导价为数字时会追加「万」,例如 52.99万。

请求参数

参数类型说明
vin必填 string 车架号,17 位,不能包含 I/O/Q,不能为纯数字

返回参数 data

参数类型说明
cm_brand string 汽车品牌
cm_factory string 主机厂
cm_model string 车型
cm_model_year string 年款
cm_displacement string 排量
cm_fuel_type string 燃料类型
cm_engine_model string 发动机型号
cm_chassis_model string 底盘号
cm_engine_start_stop string 发动机启停,有/无/选配;空值按“无”返回
cm_gearbox string 变速箱类型
cm_conf_level string 配置等级 + 驱动方式
cm_model_price string 指导价,有值时带「万」;无值时为空字符串

错误码

codemsg说明
10023 非法请求,授权无效 API Key 无效、缺失,或网关未能解析授权信息
4003 ParametersError 请求参数不合法。具体原因见 error,例如「无效的车架号(vin)」
4004 CallServiceError 下游服务调用失败
20002 VIN码校验规则不通过 VIN 不是 17 位,或包含 I/O/Q,或为纯数字
20007 此VIN码不符合校验规则或为非国标码,未能解析到车型。 仅 VIN 查车型接口在解析失败时返回。VIN 查产品失败时返回空数组

调用示例

curl

curl -X POST 'https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/vin' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "vin": "LSGUL8AL0LA144652"
  }'

Python

import requests

url = "https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/vin"
headers = {
  "Authorization": "YOUR_API_KEY",
  "Content-Type": "application/json",
}
payload = {
  "vin": "LSGUL8AL0LA144652"
}
print(requests.post(url, headers=headers, json=payload).json())

JavaScript

const payload = {
  "vin": "LSGUL8AL0LA144652"
};
const res = await fetch("https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/vin", {
  method: "POST",
  headers: {
    Authorization: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Java

String json = "{\n  \"vin\": \"LSGUL8AL0LA144652\"\n}";
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/vin"))
    .header("Authorization", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

PHP

<?php
$ch = curl_init("https://api.sopei.cn/api/sopei/openservice/v1.0/carmodel/vin");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: YOUR_API_KEY",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => '{
  "vin": "LSGUL8AL0LA144652"
}',
]);
echo curl_exec($ch);

成功响应

{
  "code": 0,
  "msg": "OK",
  "status": "ok",
  "data": [
    {
      "cm_brand": "别克",
      "cm_factory": "上汽别克",
      "cm_model": "GL8 Avenir",
      "cm_model_year": "2020",
      "cm_displacement": "2.0T",
      "cm_fuel_type": "汽油",
      "cm_engine_model": "LSY",
      "cm_chassis_model": "",
      "cm_engine_start_stop": "有",
      "cm_gearbox": "手自一体变速器(AT)",
      "cm_conf_level": "手自一体 四座尊礼版 前轮驱动",
      "cm_model_price": "52.99万"
    }
  ]
}

失败响应

{
  "code": 20002,
  "msg": "VIN码校验规则不通过",
  "status": "fail",
  "error": ""
}

查询品牌品类

查询当前商户、当前应用已开通且未关闭的品牌品类。

POST https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/category/brand
100 点 / 次 application/json
  • 无需请求体。
  • 已在应用中关闭的品类或品牌不会返回。

请求参数

无请求体。POST 即可,可带空 JSON。

返回参数 data

参数类型说明
category_code string 品类编码
category_name string 品类名称
category_precise_query boolean 是否为精准查询品类
brands object[] 该品类下可查询的商户品牌
ten_brand_name string 商户品牌名称
ten_brand_code string 商户品牌编码

错误码

codemsg说明
10023 非法请求,授权无效 API Key 无效、缺失,或网关未能解析授权信息
4004 CallServiceError 下游服务调用失败

调用示例

curl

curl -X POST 'https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/category/brand' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Python

import requests

url = "https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/category/brand"
headers = {
  "Authorization": "YOUR_API_KEY",
  "Content-Type": "application/json",
}
print(requests.post(url, headers=headers).json())

JavaScript

const payload = {};
const res = await fetch("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/category/brand", {
  method: "POST",
  headers: {
    Authorization: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Java

String json = "{}";
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/category/brand"))
    .header("Authorization", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

PHP

<?php
$ch = curl_init("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/category/brand");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: YOUR_API_KEY",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => '{}',
]);
echo curl_exec($ch);

成功响应

{
  "code": 0,
  "msg": "OK",
  "status": "ok",
  "data": [
    {
      "category_code": "B0046",
      "category_name": "机油滤清器",
      "category_precise_query": false,
      "brands": [
        {
          "ten_brand_name": "搜配",
          "ten_brand_code": "47657eeceaae67f8"
        }
      ]
    }
  ]
}

失败响应

{
  "code": 4004,
  "msg": "CallServiceError",
  "status": "fail",
  "error": ""
}

VIN 查询产品

按车架号查询指定品类、品牌的适配产品。

POST https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/vin
1-10 个品类 5 点 / 次;11-20 个品类 10 点 / 次 application/json
  • 单次最多 20 个品类,每个品类最多 5 个品牌;11-20 个品类由服务内部拆批查询并合并返回。
  • ten_brand_code 可不传,未传时查询该品类下已开通品牌,最多 5 个。
  • keyword 可选,按产品名称、产品编码、品牌名、品类名称/别名、配件应用名称模糊过滤。
  • VIN 无法解析或未查到产品时返回成功且 data 为 [],不会返回 20007。

请求参数

参数类型说明
vin必填 string 车架号,校验规则同 VIN 查车型
categories必填 object[] 要查询的品类和品牌,不能为空
category_code必填 string 品类编码,来自「查询品牌品类」
ten_brand_code可选 string 商户品牌编码。不传则查询该品类下已开通的全部品牌,最多 5 个
keyword可选 string 可选。对查询结果做模糊过滤

返回参数 data

参数类型说明
ten_brand_name string 商户品牌名称
ten_brand_code string 商户品牌编码
category_code string 品类编码
category_name string 品类名称
ten_partsku_code string 产品编码(搜配系统)
ten_partsku_external_code string 产品外部编码(ERP 等)
ten_partsku_name string 产品名称
ten_partsku_feature string 产品特点
ten_partsku_values object[] 产品属性列表。属性值已拼接单位
category_pro_name string 属性名
ten_partsku_value string 属性值,已拼接单位,例如 345mm
ten_partsku_images string[] 产品图片完整 URL,域名为 https://img.sopei.cn
part_names string[] 配件应用名称,例如 前左、前右

错误码

codemsg说明
10023 非法请求,授权无效 API Key 无效、缺失,或网关未能解析授权信息
4003 ParametersError 请求参数不合法。具体原因见 error,例如「无效的车架号(vin)」
4004 CallServiceError 下游服务调用失败
20001 暂无可查询品类数据 品类/品牌未开通、已关闭,或当前应用无权查询
20002 VIN码校验规则不通过 VIN 不是 17 位,或包含 I/O/Q,或为纯数字
20004 品类数量超过上限 VIN 查产品接口最多 20 个品类;其他相关接口最多 10 个品类
20005 品牌数量超过上限 VIN 查产品接口每个品类最多 5 个品牌;其他相关接口每个品类最多 10 个品牌
30001 商户的调用点数不足,请及时充值! 当前应用的剩余调用点数不足

调用示例

curl

curl -X POST 'https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/vin' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "vin": "LSGUL8AL0LA144652",
    "categories": [
      {
        "category_code": "G0001",
        "ten_brand_code": "47657eeceaae67f8"
      }
    ],
    "keyword": ""
  }'

Python

import requests

url = "https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/vin"
headers = {
  "Authorization": "YOUR_API_KEY",
  "Content-Type": "application/json",
}
payload = {
  "vin": "LSGUL8AL0LA144652",
  "categories": [
    {
      "category_code": "G0001",
      "ten_brand_code": "47657eeceaae67f8"
    }
  ],
  "keyword": ""
}
print(requests.post(url, headers=headers, json=payload).json())

JavaScript

const payload = {
  "vin": "LSGUL8AL0LA144652",
  "categories": [
    {
      "category_code": "G0001",
      "ten_brand_code": "47657eeceaae67f8"
    }
  ],
  "keyword": ""
};
const res = await fetch("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/vin", {
  method: "POST",
  headers: {
    Authorization: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Java

String json = "{\n  \"vin\": \"LSGUL8AL0LA144652\",\n  \"categories\": [\n    {\n      \"category_code\": \"G0001\",\n      \"ten_brand_code\": \"47657eeceaae67f8\"\n    }\n  ],\n  \"keyword\": \"\"\n}";
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/vin"))
    .header("Authorization", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

PHP

<?php
$ch = curl_init("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/vin");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: YOUR_API_KEY",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => '{
  "vin": "LSGUL8AL0LA144652",
  "categories": [
    {
      "category_code": "G0001",
      "ten_brand_code": "47657eeceaae67f8"
    }
  ],
  "keyword": ""
}',
]);
echo curl_exec($ch);

成功响应

{
  "code": 0,
  "msg": "OK",
  "status": "ok",
  "data": [
    {
      "ten_brand_name": "搜配",
      "ten_brand_code": "47657eeceaae67f8",
      "category_name": "玻璃升降器总成",
      "category_code": "G0001",
      "ten_partsku_code": "SPC0105",
      "ten_partsku_external_code": "",
      "ten_partsku_name": "",
      "ten_partsku_feature": "玻璃0105",
      "ten_partsku_values": [
        {
          "category_pro_name": "开关功能",
          "ten_partsku_value": "打开"
        }
      ],
      "ten_partsku_images": [
        "https://img.sopei.cn/tenant/partsku/example.jpg"
      ],
      "part_names": [
        "前左",
        "前右",
        "后左",
        "后右"
      ]
    }
  ]
}

失败响应

{
  "code": 20002,
  "msg": "VIN码校验规则不通过",
  "status": "fail",
  "error": ""
}

VIN 多车型精准查询

按 VIN 精准查询产品。VIN 命中多个候选车型时,先选择车型,再按所选车型返回分组产品。

POST https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/vin/precise
返回产品时:1-10 个品类 5 点 / 次;11-20 个品类 10 点 / 次。返回候选车型时免费 application/json
  • 首次请求通常只传 vin、categories 和可选 keyword;如已调用「VIN 查车型」,也可同时传本文列出的可选车型属性进行筛选。
  • result_type 为 CARMODELS 时,从 carmodels 中选择完整的一项,将六个基础 cm_* 字段原样加入首次请求并再次调用本接口。不要自行拼接或省略字段。
  • 可选车型属性仅支持 cm_model_year、cm_engine_model、cm_chassis_model、cm_engine_start_stop、cm_gearbox;cm_conf_level 和 cm_model_price 不支持筛选。
  • result_type 为 PARTSKUS 时直接读取 partsku_groups;carmodels 中同时返回本次唯一确定或已选择的车型。VIN 未解析到车型时,carmodels 和 partsku_groups 均为空数组。
  • carmodels 表示 VIN 的候选或已确定车型,与具体品类是否需要区分应用车型无关。
  • result_type 为 CARMODELS 时不扣点、不记录消费日志;result_type 为 PARTSKUS 时按请求品类数分档计费。
  • 单次最多 20 个品类,每个品类最多 5 个品牌;11-20 个品类由服务内部拆批查询并合并返回。
  • ten_brand_code 可不传;未传时查询该品类下已开通的品牌,最多 5 个。
  • cm_diff_string 是同品类下用于区分产品适配车型的差异描述。
  • cm_remarks 是产品在当前车型分组下的适配备注。

接口调用流程

可左右滑动查看完整流程,点击图片可查看原图。

请求参数

参数类型说明
vin必填 string 车架号,17 位,不能包含 I/O/Q,不能为纯数字
categories必填 object[] 要查询的品类和品牌,不能为空
category_code必填 string 品类编码,来自「查询品牌品类」
ten_brand_code可选 string 商户品牌编码。不传则查询该品类下已开通的全部品牌,最多 5 个
keyword可选 string 可选。对查询结果做模糊过滤
cm_brand可选 string 汽车品牌;第二次请求时从候选车型原样带回
cm_factory可选 string 主机厂;第二次请求时从候选车型原样带回
cm_car可选 string 车系;第二次请求时从候选车型原样带回
cm_model可选 string 车型;第二次请求时从候选车型原样带回
cm_displacement可选 string 排量;第二次请求时从候选车型原样带回
cm_fuel_type可选 string 燃料类型;第二次请求时从候选车型原样带回
cm_model_year可选 string 年款;可从「VIN 查车型」返回结果原样传入
cm_engine_model可选 string 发动机型号;可从「VIN 查车型」返回结果原样传入
cm_chassis_model可选 string 底盘号;可从「VIN 查车型」返回结果原样传入
cm_engine_start_stop可选 string 发动机启停,有/无/选配;可从「VIN 查车型」返回结果原样传入
cm_gearbox可选 string 变速箱类型;可从「VIN 查车型」返回结果原样传入

返回参数 data

参数类型说明
result_type string CARMODELS 表示需要选择车型后再次请求;PARTSKUS 表示已返回产品分组
carmodels object[] VIN 车型列表。CARMODELS 时为待选择的候选车型;PARTSKUS 时为本次唯一确定或已选择的车型;VIN 未解析到车型时为 []
cm_brand string 汽车品牌
cm_factory string 主机厂
cm_car string 车系
cm_model string 车型
cm_displacement string 排量
cm_fuel_type string 燃料类型
partsku_groups object[] 按品类和车型差异分组的产品。result_type 为 PARTSKUS 时读取
category_code string 品类编码
category_name string 品类名称
cm_diff_string string 同品类下用于区分适配车型的差异描述;无需区分时为空字符串
partskus object[] 该车型差异分组下的产品列表
ten_brand_name string 商户品牌名称
ten_brand_code string 商户品牌编码
category_code string 品类编码
category_name string 品类名称
ten_partsku_code string 产品编码(搜配系统)
ten_partsku_external_code string 产品外部编码(ERP 等)
ten_partsku_name string 产品名称
ten_partsku_feature string 产品特点
ten_partsku_values object[] 产品属性列表。属性值已拼接单位
category_pro_name string 属性名
ten_partsku_value string 属性值,已拼接单位,例如 345mm
ten_partsku_images string[] 产品图片完整 URL,域名为 https://img.sopei.cn
part_names string[] 配件应用名称,例如 前左、前右
cm_remarks string[] 该产品在当前车型分组下的适配备注

错误码

codemsg说明
10023 非法请求,授权无效 API Key 无效、缺失,或网关未能解析授权信息
4003 ParametersError 请求参数不合法。具体原因见 error,例如「无效的车架号(vin)」
4004 CallServiceError 下游服务调用失败
20001 暂无可查询品类数据 品类/品牌未开通、已关闭,或当前应用无权查询
20002 VIN码校验规则不通过 VIN 不是 17 位,或包含 I/O/Q,或为纯数字
20004 品类数量超过上限 VIN 查产品接口最多 20 个品类;其他相关接口最多 10 个品类
20005 品牌数量超过上限 VIN 查产品接口每个品类最多 5 个品牌;其他相关接口每个品类最多 10 个品牌
30001 商户的调用点数不足,请及时充值! 当前应用的剩余调用点数不足

调用示例

curl

curl -X POST 'https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/vin/precise' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "vin": "LSGUL8AL0LA144652",
    "categories": [
      {
        "category_code": "G0001",
        "ten_brand_code": "47657eeceaae67f8"
      }
    ],
    "keyword": "",
    "cm_model_year": "2020",
    "cm_engine_start_stop": "有"
  }'

Python

import requests

url = "https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/vin/precise"
headers = {
  "Authorization": "YOUR_API_KEY",
  "Content-Type": "application/json",
}
payload = {
  "vin": "LSGUL8AL0LA144652",
  "categories": [
    {
      "category_code": "G0001",
      "ten_brand_code": "47657eeceaae67f8"
    }
  ],
  "keyword": "",
  "cm_model_year": "2020",
  "cm_engine_start_stop": "有"
}
print(requests.post(url, headers=headers, json=payload).json())

JavaScript

const payload = {
  "vin": "LSGUL8AL0LA144652",
  "categories": [
    {
      "category_code": "G0001",
      "ten_brand_code": "47657eeceaae67f8"
    }
  ],
  "keyword": "",
  "cm_model_year": "2020",
  "cm_engine_start_stop": "有"
};
const res = await fetch("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/vin/precise", {
  method: "POST",
  headers: {
    Authorization: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Java

String json = "{\n  \"vin\": \"LSGUL8AL0LA144652\",\n  \"categories\": [\n    {\n      \"category_code\": \"G0001\",\n      \"ten_brand_code\": \"47657eeceaae67f8\"\n    }\n  ],\n  \"keyword\": \"\",\n  \"cm_model_year\": \"2020\",\n  \"cm_engine_start_stop\": \"有\"\n}";
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/vin/precise"))
    .header("Authorization", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

PHP

<?php
$ch = curl_init("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/vin/precise");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: YOUR_API_KEY",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => '{
  "vin": "LSGUL8AL0LA144652",
  "categories": [
    {
      "category_code": "G0001",
      "ten_brand_code": "47657eeceaae67f8"
    }
  ],
  "keyword": "",
  "cm_model_year": "2020",
  "cm_engine_start_stop": "有"
}',
]);
echo curl_exec($ch);

成功响应

{
  "code": 0,
  "msg": "OK",
  "status": "ok",
  "data": {
    "result_type": "CARMODELS",
    "carmodels": [
      {
        "cm_brand": "别克",
        "cm_factory": "上汽通用别克",
        "cm_car": "GL8",
        "cm_model": "GL8 Avenir",
        "cm_displacement": "2.0T",
        "cm_fuel_type": "汽油"
      }
    ],
    "partsku_groups": []
  }
}

失败响应

{
  "code": 4003,
  "msg": "ParametersError",
  "status": "fail",
  "error": "无效的车架号(vin)"
}

编码搜索

按关键词搜索商户产品编码、大厂码、配件标准码、OE 码,返回候选编码供下一步精确查询。

POST https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/keyword
2 点 / 次 application/json
  • 会去除 keyword 首尾空白。
  • keyword 长度小于 3 时返回成功且 data 为 []。
  • 最多返回 20 条。长度达到 6 时,下游按精确匹配优先检索。
  • 返回的 code、category_code、ten_brand_name 用于「编码查询产品」。

请求参数

参数类型说明
keyword必填 string 编码关键词,例如 D1819

返回参数 data

参数类型说明
code string 命中的编码
category_code string 品类编码
category_name string 品类名称
ten_brand_name string 商户品牌名称

错误码

codemsg说明
10023 非法请求,授权无效 API Key 无效、缺失,或网关未能解析授权信息
4003 ParametersError 请求参数不合法。具体原因见 error,例如「无效的车架号(vin)」
4004 CallServiceError 下游服务调用失败

调用示例

curl

curl -X POST 'https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/keyword' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "keyword": "D1819"
  }'

Python

import requests

url = "https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/keyword"
headers = {
  "Authorization": "YOUR_API_KEY",
  "Content-Type": "application/json",
}
payload = {
  "keyword": "D1819"
}
print(requests.post(url, headers=headers, json=payload).json())

JavaScript

const payload = {
  "keyword": "D1819"
};
const res = await fetch("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/keyword", {
  method: "POST",
  headers: {
    Authorization: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Java

String json = "{\n  \"keyword\": \"D1819\"\n}";
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/keyword"))
    .header("Authorization", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

PHP

<?php
$ch = curl_init("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/keyword");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: YOUR_API_KEY",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => '{
  "keyword": "D1819"
}',
]);
echo curl_exec($ch);

成功响应

{
  "code": 0,
  "msg": "OK",
  "status": "ok",
  "data": [
    {
      "code": "D1819",
      "category_code": "D0006",
      "category_name": "刹车片",
      "ten_brand_name": "正大"
    },
    {
      "code": "3D1819643",
      "category_code": "B0048",
      "category_name": "空调滤清器",
      "ten_brand_name": "OE码"
    }
  ]
}

失败响应

{
  "code": 4003,
  "msg": "ParametersError",
  "status": "fail",
  "error": "无效的编码关键词(keyword)"
}

编码查询产品

用编码搜索接口返回的编码、品类和品牌,精确查询产品详情。

POST https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/code
3 点 / 次 application/json
  • code、category_code、ten_brand_name 必须与编码搜索结果一致。
  • 未命中时返回成功且 data 为 []。

请求参数

参数类型说明
code必填 string 编码,来自编码搜索接口的 code
category_code必填 string 品类编码,来自编码搜索接口
ten_brand_name必填 string 商户品牌名称,来自编码搜索接口

返回参数 data

参数类型说明
ten_brand_name string 商户品牌名称
ten_brand_code string 商户品牌编码
category_code string 品类编码
category_name string 品类名称
ten_partsku_code string 产品编码(搜配系统)
ten_partsku_external_code string 产品外部编码(ERP 等)
ten_partsku_name string 产品名称
ten_partsku_feature string 产品特点
ten_partsku_values object[] 产品属性列表。属性值已拼接单位
category_pro_name string 属性名
ten_partsku_value string 属性值,已拼接单位,例如 345mm
ten_partsku_images string[] 产品图片完整 URL,域名为 https://img.sopei.cn
part_names string[] 配件应用名称,例如 前左、前右

错误码

codemsg说明
10023 非法请求,授权无效 API Key 无效、缺失,或网关未能解析授权信息
4003 ParametersError 请求参数不合法。具体原因见 error,例如「无效的车架号(vin)」
4004 CallServiceError 下游服务调用失败
20001 暂无可查询品类数据 品类/品牌未开通、已关闭,或当前应用无权查询

调用示例

curl

curl -X POST 'https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/code' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "3D1819643",
    "category_code": "B0048",
    "ten_brand_name": "OE码"
  }'

Python

import requests

url = "https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/code"
headers = {
  "Authorization": "YOUR_API_KEY",
  "Content-Type": "application/json",
}
payload = {
  "code": "3D1819643",
  "category_code": "B0048",
  "ten_brand_name": "OE码"
}
print(requests.post(url, headers=headers, json=payload).json())

JavaScript

const payload = {
  "code": "3D1819643",
  "category_code": "B0048",
  "ten_brand_name": "OE码"
};
const res = await fetch("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/code", {
  method: "POST",
  headers: {
    Authorization: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Java

String json = "{\n  \"code\": \"3D1819643\",\n  \"category_code\": \"B0048\",\n  \"ten_brand_name\": \"OE码\"\n}";
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/code"))
    .header("Authorization", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

PHP

<?php
$ch = curl_init("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/code");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: YOUR_API_KEY",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => '{
  "code": "3D1819643",
  "category_code": "B0048",
  "ten_brand_name": "OE码"
}',
]);
echo curl_exec($ch);

成功响应

{
  "code": 0,
  "msg": "OK",
  "status": "ok",
  "data": [
    {
      "ten_brand_name": "曼牌",
      "ten_brand_code": "7d78058019c208a5",
      "category_code": "B0048",
      "category_name": "空调滤清器",
      "ten_partsku_code": "CUK35000-2",
      "ten_partsku_external_code": "",
      "ten_partsku_name": "",
      "ten_partsku_feature": "",
      "ten_partsku_values": [
        {
          "category_pro_name": "长",
          "ten_partsku_value": "345mm"
        },
        {
          "category_pro_name": "宽",
          "ten_partsku_value": "221mm"
        },
        {
          "category_pro_name": "高",
          "ten_partsku_value": "30mm"
        }
      ],
      "ten_partsku_images": [],
      "part_names": [
        "内置"
      ]
    }
  ]
}

失败响应

{
  "code": 4003,
  "msg": "ParametersError",
  "status": "fail",
  "error": "无效的查询code(code)"
}

查询全量产品

按单个品类 + 单个品牌分页拉取产品列表,可用于全量同步。

POST https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/list
100 点 / 次 application/json
  • data 是对象,不是数组,包含 total 和 skus。
  • 图片 URL 带 ?type=thumbnail。
  • 该接口不返回产品属性、配件应用和特点。

请求参数

参数类型说明
category_code必填 string 品类编码
ten_brand_code必填 string 商户品牌编码
page可选 number 页码,最小 1,默认 1
page_size可选 number 每页条数,默认 100,最大 1000
last_sync_time可选 string 增量同步时间,格式 YYYY-MM-DD HH:mm:ss 或 YYYY-MM-DD,只返回该时间之后更新的产品

返回参数 data

参数类型说明
total number 符合条件的产品总数
skus object[] 当前页产品
category_code string 品类编码
category_name string 品类名称
ten_brand_code string 商户品牌编码
ten_brand_name string 商户品牌名称
ten_partsku_code string 产品编码
ten_partsku_external_code string 产品外部编码
ten_partsku_name string 产品名称
ten_partsku_images string[] 缩略图 URL
update_time string 产品更新时间

错误码

codemsg说明
10023 非法请求,授权无效 API Key 无效、缺失,或网关未能解析授权信息
4003 ParametersError 请求参数不合法。具体原因见 error,例如「无效的车架号(vin)」
4004 CallServiceError 下游服务调用失败
20001 暂无可查询品类数据 品类/品牌未开通、已关闭,或当前应用无权查询

调用示例

curl

curl -X POST 'https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/list' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "category_code": "C0002",
    "ten_brand_code": "91222f17d30d3099",
    "page": 1,
    "page_size": 100,
    "last_sync_time": "2026-04-15 18:00:00"
  }'

Python

import requests

url = "https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/list"
headers = {
  "Authorization": "YOUR_API_KEY",
  "Content-Type": "application/json",
}
payload = {
  "category_code": "C0002",
  "ten_brand_code": "91222f17d30d3099",
  "page": 1,
  "page_size": 100,
  "last_sync_time": "2026-04-15 18:00:00"
}
print(requests.post(url, headers=headers, json=payload).json())

JavaScript

const payload = {
  "category_code": "C0002",
  "ten_brand_code": "91222f17d30d3099",
  "page": 1,
  "page_size": 100,
  "last_sync_time": "2026-04-15 18:00:00"
};
const res = await fetch("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/list", {
  method: "POST",
  headers: {
    Authorization: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
console.log(await res.json());

Java

String json = "{\n  \"category_code\": \"C0002\",\n  \"ten_brand_code\": \"91222f17d30d3099\",\n  \"page\": 1,\n  \"page_size\": 100,\n  \"last_sync_time\": \"2026-04-15 18:00:00\"\n}";
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/list"))
    .header("Authorization", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

PHP

<?php
$ch = curl_init("https://api.sopei.cn/api/sopei/openservice/v1.0/partsku/list");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: YOUR_API_KEY",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => '{
  "category_code": "C0002",
  "ten_brand_code": "91222f17d30d3099",
  "page": 1,
  "page_size": 100,
  "last_sync_time": "2026-04-15 18:00:00"
}',
]);
echo curl_exec($ch);

成功响应

{
  "code": 0,
  "msg": "OK",
  "status": "ok",
  "data": {
    "total": 1789,
    "skus": [
      {
        "category_code": "C0002",
        "category_name": "轮毂单元",
        "ten_brand_code": "91222f17d30d3099",
        "ten_brand_name": "彼斯得轴承.",
        "ten_partsku_code": "04-0683",
        "ten_partsku_external_code": "",
        "ten_partsku_name": "",
        "ten_partsku_images": [
          "https://img.sopei.cn/tenant/partsku/example.jpg?type=thumbnail"
        ],
        "update_time": "2025-08-07 20:08:35"
      }
    ]
  }
}

失败响应

{
  "code": 4003,
  "msg": "ParametersError",
  "status": "fail",
  "error": "page_size 最大1000"
}