1688 商品运费模板

POST /v1/products/freight/template

按商品查询国内运费、计费模板和件重尺,直接调用官方接口。本接口不创建订单,预估运费不代表最终下单应付运费。

com.alibaba.fenxiao.crossborder:product.freight.estimate-1 · 1688 

使用具有 product:detail 权限的 Live API Key,沿用现有 1688 授权。成功计 2 API Units,已包含 SKU 映射与运费查询;失败不扣单位。即使携带 shop 或 X-Shop-Domain,也不检查或扣除 AI Credits。Sandbox 返回 422 SANDBOX_CAPABILITY_UNAVAILABLE。

请求

skus[].spec_id 取 1688 标准商品详情的 variants[].sku_id,与订单预览、创单一致。内部映射为原始 skuId,无需开发者处理。支持 1–100 个不重复 SKU,数量及合计必须为正安全整数;total_quantity 自动求和。无法匹配的规格会在运费查询前拒绝。

POST /v1/products/freight/template
{
  "channel": "1688",
  "product_id": "111111111",
  "destination": {
    "province": "浙江省",
    "city": "杭州市",
    "district": "滨江区"
  },
  "skus": [
    {
      "spec_id": "b266e0726506185beaf205cbae88530d",
      "quantity": 3
    }
  ]
}

省市区名称与编码

提供完整中文省、市、区县名称,或下方完整六位编码。支持全称和可唯一识别的简称;名称与编码同时提供时必须一致。内置中国大陆数据截至 2023-06-30,来源仓库已停止更新;新设地区可提供当前编码,是否接受由 1688 决定。直辖市在省级范围内解析;东莞、中山、儋州、嘉峪关的镇街名称映射为六位县级等价城市编码,不向上游传九位街道码。找不到或存在歧义时明确报错,不猜测地区。未收录的显式编码,其城市、区县名称可能为 null。

province / city / district → province_code / city_code / district_code

{
  "destination": {
    "province_code": "330000",
    "city_code": "330100",
    "district_code": "330108"
  }
}

Administrative-divisions-of-China 

响应

标准金额统一为人民币分(CNY_minor),490 表示 ¥4.90。重量单位千克,长宽高单位厘米。dimensions_source=product 对应官方 sizeValueType=1,读取 product_dimensions;sku 对应类型 2,读取各 SKU 的 dimensions。未知或无效字段返回 null;明确包邮时运费为 0。discount 不再次折算运费。response_format=upstream 保留官方信封、字段、原始 skuId 和元单位,不附加 monetary_unit。两种格式的上游业务失败均返回 502。下方响应为示例数据。

charge_type: weight / quantity / volume → charge_unit: kg / item / m3

template.type: seller_paid / custom / official_custom

template.shipping_method: express / freight / cash_on_delivery / official

{
  "request_id": "req_example",
  "monetary_unit": "CNY_minor",
  "freight_template": {
    "channel": "1688",
    "product_id": "111111111",
    "destination": {
      "province": "浙江省",
      "province_code": "330000",
      "city": "杭州市",
      "city_code": "330100",
      "district": "滨江区",
      "district_code": "330108"
    },
    "total_quantity": 3,
    "free_postage": false,
    "freight": {
      "amount": 490,
      "currency": "CNY"
    },
    "discount": 1,
    "template": {
      "id": "123456789",
      "name": "普通快递运费模板",
      "type": "custom",
      "shipping_method": "express",
      "charge_type": "weight",
      "charge_unit": "kg",
      "first_unit": 1,
      "first_fee": {
        "amount": 290,
        "currency": "CNY"
      },
      "next_unit": 1,
      "next_fee": {
        "amount": 200,
        "currency": "CNY"
      }
    },
    "dimensions_source": "sku",
    "product_dimensions": null,
    "skus": [
      {
        "spec_id": "b266e0726506185beaf205cbae88530d",
        "quantity": 3,
        "dimensions": {
          "weight_kg": 0.5,
          "length_cm": 20,
          "width_cm": 15,
          "height_cm": 10
        }
      }
    ]
  }
}

错误

HTTPCode
400INVALID_DESTINATION, REGION_NOT_FOUND, REGION_AMBIGUOUS, REGION_CODE_MISMATCH, INVALID_PRODUCT_ID, INVALID_SKUS, INVALID_SPEC_ID, DUPLICATE_SPEC_ID, INVALID_QUANTITY
401 / 403Authentication
404NOT_FOUND
422SANDBOX_CAPABILITY_UNAVAILABLE
429Rate limits
502CHANNEL_UPSTREAM_ERROR

POST /v1/products/freight/estimate · POST /v1/orders/preview

获取支持

需要集成帮助?请联系开发者支持 support@hiobuy.com · 预计 1–2 个工作日内回复

发送邮件