合作伙伴 API
面向合作伙伴的 Avtoorder API
只读 JSON API，提供 avtoorder.com 上可售的车辆（包括位于中国的车辆），并附带整车到门的估价。
API 提供的内容
所有接口均为只读，返回 JSON。基础地址：
https://avtoorder.com/api/v1- 车辆列表，支持筛选、排序和分页。
- 车辆详情，含按您选择的目的地计算的整车到门估价。
- 品牌及各品牌下可用的车型。
- 通过我们自己的 CDN 链接提供图片，共四种宽度（384、640、1080 和 1920 像素）。
车辆列表筛选参数（未知参数或最小值大于最大值时，会以 400 拒绝）：
GET /cars
page (default 1), pageSize (1-100, default 24),
brand, model (needs brand),
yearMin, yearMax, priceMinCny, priceMaxCny,
mileageMinKm, mileageMaxKm,
fuel (gasoline|diesel|electric|hybrid|plugin_hybrid),
condition (new|used),
sort (recommended|price_asc|price_desc|mileage_asc|year_desc|newest),
default recommended
locale (en|ru|zh), default ru
GET /cars/{id} destination (default RU_VLA),
locale (default ru)
GET /brands
GET /brands/{brand}/models
GET /me
GET /media/{token} w=384|640|1080|1920 (default 1080),
no API key needed如何获得访问权限
密钥由我们的团队签发，不提供自助注册。请告诉我们您的公司以及数据的使用方式，我们会与您商定密钥范围和限额。
- 打开联系表单，选择“合作机会”主题。
- 写明“API access”、公司名称、使用场景以及您将从哪些服务器 IP 地址发起调用。
- 我们为您创建客户账户，并通过私密渠道发送密钥。密钥只显示一次，请妥善保管。
- 密钥有适用范围：完整目录，或仅限 Avtoorder 自有库存车辆。调用 GET /me 即可查看。
快速开始
在 Authorization 请求头中发送密钥，并将占位符替换为您的密钥。
列出某品牌的车辆
curl -H "Authorization: Bearer avto_live_YOUR_KEY" \
"https://avtoorder.com/api/v1/cars?brand=BRAND_KEY&pageSize=24&sort=price_asc"获取单辆车及整车到门估价
curl -H "Authorization: Bearer avto_live_YOUR_KEY" \
"https://avtoorder.com/api/v1/cars/CAR_ID?locale=en"品牌键来自 GET /brands，车辆 id 来自列表响应。
GET /cars/{id} 的 destination 可选值（默认 RU_VLA）：
RU_VLA, RU_NSK, RU_MOW, KZ_ALA, UZ_TAS, BY_MSK, KG_FRU每个接口的完整结构见交互式参考文档。
身份验证与安全
- 只能以 Authorization: Bearer avto_live_… 的形式在请求头中发送密钥。
- URL 查询字符串中的密钥会被以 400 key-in-query 拒绝，且该密钥会被标记为已暴露，因为 URL 会进入日志和浏览器历史记录。若发生这种情况，请轮换密钥。
- 可以将密钥限制在一组 IP 地址内。
- 密钥可以带宽限期轮换（期间旧密钥仍可使用），也可随时立即吊销。
- 请将密钥保存在服务器端，切勿放入浏览器或移动应用中。
请求限额
每个密钥都有每分钟速率限制和每日配额（按 UTC 计日）。您的限额可通过 GET /me 查看。此外，我们的网络入口还对每个 IP 设有限制。
- 每个通过身份验证的响应都带有 RateLimit 和 RateLimit-Policy 头。RateLimit 只反映每分钟窗口；当日用量请通过 GET /me 查看。
- 超出限制时返回 429 并带有 Retry-After 头（秒）。请等待相应时间后再重试。
- 身份验证失败的尝试会单独限流。
- 对 429 和 503 请使用指数退避重试。其他 4xx 错误不要原样重试。
- 部分未缓存的查询可能需要 10–15 秒，请为每个请求预留最多 30 秒。
错误
错误采用 application/problem+json 格式（RFC 9457）。type 字段是指向下表对应行的链接。detail 文本为英文，面向开发者。仅支持 GET 和 HEAD：其他方法会被拒绝（返回 405 且响应体为空；图片链接返回 403）；对 JSON 接口发送 OPTIONS 会列出允许的方法。
示例
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
RateLimit-Policy: "minute";q=60;w=60, "day";q=20000;w=86400
RateLimit: "minute";r=0;t=12
{
"type": "https://avtoorder.com/en/developers#error-rate-limited",
"title": "Rate limit exceeded",
"status": 429,
"requestId": "0f3c…"
}| 代码 | HTTP | 含义 |
|---|---|---|
| missing-credentials | 401 | 未发送 Authorization 请求头，或其认证方案不是 Bearer。 |
| invalid-credentials | 401 | 密钥未知或格式错误。 |
| key-revoked | 401 | 密钥已被吊销，请向我们申请新密钥。 |
| key-expired | 401 | 密钥已过期。 |
| client-disabled | 401 | 您的账户已被停用，请联系我们。 |
| ip-not-allowed | 403 | 请求来自不在该密钥允许名单中的 IP 地址。 |
| key-in-query | 400 | 密钥被放在了 URL 中。请改用 Authorization 头并轮换密钥。 |
| invalid-request | 400 | 参数未知或无效，或最小值大于最大值（例如 yearMin > yearMax）。errors 数组按路径列出每个问题。 |
| not-found | 404 | 车辆或品牌不存在，或不在您的密钥范围内。 |
| rate-limited | 429 | 超出每分钟限制，请参见 Retry-After。 |
| quota-exceeded | 429 | 超出每日配额，将在 UTC 00:00 重置。 |
| auth-throttled | 429 | 来自您 IP 地址的身份验证失败次数过多，请等待后重试。 |
| upstream-busy | 503 | 目录暂时繁忙，请退避后重试。 |
| unavailable | 503 | API 暂时不可用：正在部署更新，或 API 尚未配置。请稍后重试。 |
| internal | 500 | 我们这边发生了意外错误。联系我们时请提供 requestId。 |
| edge-rate-limited | 429 | 同一 IP 地址的请求过多，在到达 API 之前已被网络入口拒绝。请降低频率并稍后重试。 |
同步完整目录
单次查询不会返回整个目录，请按品牌分段遍历。
- 调用 GET /brands 获取所有品牌键。
- 对每个品牌请求 GET /cars?brand=KEY&pageSize=100，并递增 page，直到 data 为空或 page.hasMore 为 false。
- 将每个品牌拆分为多个切片：先按单一年份（yearMin 和 yearMax 设为同一年），再按价格区间（例如每段 10 000 CNY，使用 priceMinCny 和 priceMaxCny）。每个切片都以同样方式逐页遍历。切片越窄，覆盖越完整。
- truncated: true 表示结果可能不完整：目录中有部分数据只能扫描一部分。缩小筛选范围可以提高覆盖率，但即使切片为空或已完整返回，truncated 也可能仍为 true，因此不要为了等它变为 false 而不断缩小范围：它可能永远不会变。
- 车辆 id 是稳定的：请将其用作主键，车辆每次再次出现时更新。某辆车在一次响应中缺失并不代表它已下架：只有在一次完整同步中始终未出现时才将其删除。
- fetchedAt 是您收到响应的时间，而不是数据的时间。数据最多可能滞后 24 小时，因此每小时同步多于一次收益不大。
数据说明
- 整车到门价格（turnkeyEstimate）是估价而非报价，带有 isEstimate: true、所用汇率及其来源（fx.rateSource）和获取时间（fx.capturedAt）。
- 估价所做的全部假设都列在 customs.assumptions 中。totalIsLowerBound: true（发动机功率或关税未知）表示实际总价可能更高。首次登记日期未知时会单独标注（registrationUnknown），但不会使总价成为下限。
- 车辆价格未知时，priceCny 为 null，priceOnRequest 为 true，绝不会是 0。此类车辆没有估价，turnkeyUnavailableReason 为 price_on_request。对于部分车辆，我们不提供整车到门估价（例如以美元标价的车辆，见 askingPrice.currency），此时 turnkeyUnavailableReason 为 not_offered_for_listing。
- 列表中的 totalEstimate 是近似值，各页之间可能变化，且在 truncated 为 true 时也可能为 0。请勿用它判断何时停止翻页。
- sort=recommended（默认）是将不同库存的车辆交替排列的综合排序；newest 同样是跨库存的综合排序，只是在每个库存内较新的车辆排在前面，并非严格按上架时间排序；price_asc 和 price_desc 按价格从低到高和从高到低；mileage_asc 里程最少的在前；year_desc 按 year 从大到小。year 是车辆信息中标注的年份：大多数二手车为首次登记年份，少数为车型年份。firstRegistration 是已知时的首次登记年月。
- fuel 取自车辆信息：在可靠时取信息中注明的能源类型，否则取标题中明确的动力技术名称或发动机代号（例如 DM-i 即 plugin_hybrid，280TSI 即 gasoline）；两者都未注明时为 null。fuel 为 null 的车辆不会匹配 fuel 筛选，因此筛选结果是已知为该动力类型的车辆，未必是全部。增程式电动车（EREV）归入 hybrid。condition: used 表示车辆未被标记为新车；condition 为 null 的车辆也可能出现在结果中，包括筛选 condition=used 时。
- locale 决定有译文时标题和标签所用的语言；无论 locale 如何，车辆标题、配置名称和部分参数值常常是英文或中文。
- GET /brands 返回目录已知的品牌键：其中部分品牌当前可能没有车辆，数量未知时 count 为 null。品牌和车型键可能包含非 ASCII 字符（例如中文），请进行 URL 编码。
- 图片通过我们自己的图片链接提供（通过 ?w= 选择 384、640、1080 或 1920 宽度）。链接稳定但不保证永久有效：密钥被吊销后，这些链接将不再获取新的图片，但已缓存的图片可能仍会在一段时间内正常显示；图片被移除后，其链接也会失效。重新同步时请从 API 刷新链接。
- 除 Avtoorder 自有库存车辆外，VIN 均已做掩码处理。
使用条款
- 不得将原始 API 数据作为数据产品转售或再分发。向您自己的客户展示车辆是允许的。
- 无需署名。
- 如违反本条款、密钥泄露或滥用服务，我们可随时吊销密钥。
- 限额和配额将被严格执行。
- 请对密钥保密，一旦暴露请立即告知我们。
- API 可能变更。向后兼容的新增不另行通知，破坏性变更将发布在新的版本路径下。
交互式参考文档
可在浏览器中试用所有接口，并下载机器可读的 OpenAPI 规范。