端点、输入字段与响应封装

每个操作一个端点

每个操作都有独立端点，调用一律使用 POST。路径最后一段是完整的动作标识，包含 polovniautomobili- 前缀和连字符： POST /api/v1/polovniautomobili/polovniautomobili-brands POST /api/v1/polovniautomobili/polovniautomobili-filter-options POST /api/v1/polovniautomobili/polovniautomobili-listing POST /api/v1/polovniautomobili/polovniautomobili-models POST /api/v1/polovniautomobili/polovniautomobili-search

polovniautomobili-brandspolovniautomobili-filter-optionspolovniautomobili-listingpolovniautomobili-modelspolovniautomobili-search

网关输入必须使用 body 包装

网关接收 JSON 对象 {"body": {...}}；放在 body 之外的输入不符合操作 schema。listing 必填 body.ad_id，类型为字符串；body.slug 为可选字符串。ad_id 是搜索结果返回的数字标识，为 4–12 位数字（模式 \d{4,12}）；本站在准入时接受任意字符串作为 ad_id，不是 4–12 位数字的标识之后可能失败。models 必填封闭枚举中精确拼写的 body.brand；可选 body.sample_pages 为 1 至 10 的整数。brands 与 filter-options 未声明 body 字段：可省略 body 属性（发送 {}），或将 body 设为空对象（{"body":{}}）。

body.ad_idbody.slugbody.brandbody.sample_pagespolovniautomobili-brandspolovniautomobili-filter-options

搜索边界与成功响应

搜索字段全部可选。body.page 为 1 至 750 的整数；body.page_size 只能是 25、50、100 或 200。成功响应为 {ok:true, data, meta:{requestId, chargedCreditUnits, simulated, sourceAttribution}}。data 为该操作的结果，可以为 null。即使 data:null，也可能按该操作已批准的每次调用价格计费成功。

body.pagebody.page_sizeokdatapriceCreditUnits

失败代码与不确定结果

已受理的请求失败时返回 {ok:false, error:{code,message}, meta:{requestId, chargedCreditUnits:"0", status}}，首次响应的 status 为 "failure" 或 "uncertain"。REQUEST_NOT_FULFILLED（502）表示操作报告未成功，REQUEST_REJECTED（502）表示操作拒绝了请求；SERVICE_UNAVAILABLE 与 SERVICE_BUSY（503）表示服务端的状况，与你的密钥或钱包无关。这些失败不扣费。OPERATION_TIMEOUT（504）、OUTCOME_UNKNOWN（504 或 502）与 RESULT_INVALID（502）属于结果未知：价格先被预留，随后释放，绝不迟到扣费。不要换新的 Idempotency-Key 重试。用同一个 key 原样重发只返回已记录的状态，不会再次执行：未决时为 REQUEST_PENDING（409，meta.status 为 "dispatching" 或 "uncertain"），预留释放后为 OUTCOME_UNKNOWN_RELEASED（504，meta.status 为 "released"，chargedCreditUnits 为 "0"）。

errorokdataIdempotency-Key

准入错误与同键回放

受理前的错误采用 {ok:false,error:{code,message},requestId}，requestId 在顶层，没有 meta。例如 AUTH_FAILED（401）、INSUFFICIENT_CREDITS（402）、IDEMPOTENCY_CONFLICT（409）、请求体不是有效 JSON 时的 INVALID_REQUEST（400），以及输入不符合操作 schema（类型、枚举、边界、必填字段）时的 INVALID_PARAM（400）。body 内契约未声明的字段处理方式不同：请求先被受理，随后以 INVALID_INPUT（400）拒绝，meta.chargedCreditUnits 为 "0"，meta.status 为 "failure"。操作不会执行，也不扣费，但仍要求操作已启用且可用积分足以支付其价格。已存储的最终响应在 24 小时内按原状态码和响应体回放；此后已成功的请求返回 RESULT_EXPIRED（410，meta.status 为 "succeeded"），这并非退款；失败的请求返回其已记录的错误码和 HTTP 状态码。

okerrorIdempotency-Key

查询汽车品牌

POST /api/v1/polovniautomobili/polovniautomobili-brands

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {}
}

null

查看筛选词表

POST /api/v1/polovniautomobili/polovniautomobili-filter-options

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {}
}

null

读取单条汽车广告

POST /api/v1/polovniautomobili/polovniautomobili-listing

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "ad_id": "example",
    "slug": "example"
  }
}

null

查询品牌下的车型

POST /api/v1/polovniautomobili/polovniautomobili-models

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "brand": "Alfa Romeo",
    "sample_pages": 1
  }
}

null

筛选汽车广告

POST /api/v1/polovniautomobili/polovniautomobili-search

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "air_conditioning": [
      "none"
    ],
    "attest": "attested",
    "body_type": [
      "sedan"
    ],
    "brand": "Alfa Romeo",
    "colour": [
      "white"
    ],
    "country": "RS",
    "country_of_origin": "ME",
    "damaged": [
      "notDamaged"
    ],
    "doors": "3",
    "drive": [
      "front"
    ],
    "emission_class": "euro1",
    "engine_cc_max": 0,
    "engine_cc_min": 0,
    "flywheel": "floatingFlywheel",
    "fuel": [
      "gasoline"
    ],
    "gearbox": [
      "manual4Gears"
    ],
    "interior_colour": [
      "black"
    ],
    "interior_material": [
      "cloth"
    ],
    "listing_age": "all",
    "mileage_max": 0,
    "mileage_min": 0,
    "model": [
      "example"
    ],
    "only_with_price": false,
    "page": 1,
    "page_size": 25,
    "plates": [
      "domesticPlates"
    ],
    "power_kw_max": 0,
    "power_kw_min": 0,
    "price_max": 0,
    "price_min": 0,
    "registered_to_seller": false,
    "seats": "2",
    "trade_in": [
      "noExchange"
    ],
    "wheel_side": "left",
    "year_max": 1900,
    "year_min": 1900
  }
}

null