# 国际快递价格查询

## 接口信息

- Method: `POST`
- URL: `https://tms-go.czl.net/api/tms/price-search`
- Auth: 无需鉴权
- Content-Type: `application/json`

## 适用场景

- 自定义报价页
- 内部客服查价工具
- 把包裹信息交给后端统一计算计费重

## 推荐请求方式

优先传 `packages`，由服务端统一计算重量并查价。

如果你的系统已经提前算好了重量，也可以只传 `weight` 做兼容接入。

## 请求体

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `country` | `string` | 是 | 国家二字码，例如 `US`、`GB`、`DE` |
| `cargoType` | `string` | 否 | 包裹类型，常见值：`P`、`D`、`B` |
| `postcode` | `string` | 否 | 邮编或补充目的地信息 |
| `express_type` | `string` | 否 | 快递类型筛选，不传或传 `ALL` 表示全部 |
| `group_code` | `string` | 否 | 渠道分组代码 |
| `packages` | `PackageItem[]` | 否 | 推荐方式。包裹数组，结构见下方 |
| `weight` | `string` | 否 | 兼容旧版的直接重量参数 |

### PackageItem

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `weight` | `number` | 是 | 单件实重，单位 KG |
| `length` | `number` | 否 | 长，单位 CM |
| `width` | `number` | 否 | 宽，单位 CM |
| `height` | `number` | 否 | 高，单位 CM |
| `count` | `number` | 是 | 件数 |

## 请求示例

```bash
curl --request POST \
  --url https://tms-go.czl.net/api/tms/price-search \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "US",
    "cargoType": "P",
    "postcode": "10001",
    "packages": [
      {
        "weight": 0.2,
        "length": 20,
        "width": 15,
        "height": 10,
        "count": 1
      }
    ]
  }'
```

## 成功响应

当请求体包含 `packages` 时，接口返回：

```json
{
  "products": [
    {
      "product_id": "1001",
      "product_name": "DHL 特惠",
      "total_amount": "128.00",
      "product_aging": "3-5个工作日",
      "product_note": "具体价格以下单时为准"
    },
    {
      "product_id": "2001",
      "product_name": "FedEx IE",
      "total_amount": "136.00",
      "product_aging": "4-6个工作日",
      "product_note": ""
    }
  ],
  "half_kg_weight": 0.5,
  "raw_weight": 0.2
}
```

## 响应说明

- `products`: 渠道列表
- `half_kg_weight`: 按进位规则计算后的重量
- `raw_weight`: 原始汇总重量

`products` 中常用字段：

- `product_id`: 产品 ID
- `product_name`: 产品名称
- `total_amount`: 总价
- `product_aging`: 时效描述
- `product_note`: 产品备注

## 接入建议

- 推荐统一传 `packages`
- 多件包裹时，系统会直接按进位规则查价
- 前端展示重量时，可按自己的产品体验选择是否显示 `raw_weight`