# Tính phí

> Tính phí vận chuyển cho một tuyến và kiện hàng trước khi tạo đơn.

## Endpoint

| Môi trường | URL |
| --- | --- |
| Production | `https://online-gateway.ghn.vn/shiip/public-api/v2/shipping-order/fee` |
| Staging | `https://dev-online-gateway.ghn.vn/shiip/public-api/v2/shipping-order/fee` |

**Method**: `POST`

## Headers

| Header | Bắt buộc | Mô tả |
| --- | --- | --- |
| `Content-Type` | Có | `application/json` |
| `Token` | Có | Token của shop (do GHN cấp) — [lấy token](https://developer.ghn.vn/vi/docs/token/get-token.md) |
| `ShopId` | Có | Shop ID (số nguyên) — shop được dùng để tính giá |

## Tham số

- **weight** (Int): Khối lượng kiện (gram). Phải khác 0
- **to_district_id** (Int): Mã quận/huyện giao (từ [Lấy Quận/Huyện](https://developer.ghn.vn/vi/docs/master-data/get-district.md))
- **to_ward_code** (String): Mã phường/xã giao (từ [Lấy Phường/Xã](https://developer.ghn.vn/vi/docs/master-data/get-ward.md))
- **from_district_id** (Int): Mã quận/huyện lấy hàng. Mặc định: địa chỉ đã đăng ký của shop
- **from_ward_code** (String): Mã phường/xã lấy hàng. Mặc định: địa chỉ đã đăng ký của shop
- **service_type_id** (Int): Loại dịch vụ, chọn theo khối lượng:<br>`2`: tổng khối lượng **dưới 20 kg**<br>`5`: tổng khối lượng **từ 20 kg trở lên**, hoặc đơn nhiều kiện
- **service_id** (Int): Mã dịch vụ cụ thể (từ [Lấy Dịch vụ](https://developer.ghn.vn/vi/docs/master-data/get-service.md)). Thay thế cho `service_type_id`
- **length** (Int): Chiều dài (cm)
- **width** (Int): Chiều rộng (cm)
- **height** (Int): Chiều cao (cm)
- **insurance_value** (Int): Giá trị khai giá (VND), dùng để bồi thường
- **cod_value** (Int): Số tiền COD cần thu (VND)
- **coupon** (String): Mã giảm giá
- **items** (Object[]): Danh sách sản phẩm — cùng cấu trúc [Tạo đơn](https://developer.ghn.vn/vi/docs/order/create.md); dùng cho hàng nặng

## Ví dụ Request

```bash
curl -X POST https://dev-online-gateway.ghn.vn/shiip/public-api/v2/shipping-order/fee \
  -H "Token: 5c1d8a9e-2f4b-11ed-..." \
  -H "ShopId: 92837" \
  -H "Content-Type: application/json" \
  -d '{
    "from_district_id": 1452,
    "from_ward_code": "21007",
    "to_district_id": 1444,
    "to_ward_code": "20308",
    "service_type_id": 2,
    "weight": 600,
    "length": 25,
    "width": 20,
    "height": 8,
    "insurance_value": 285000
  }'
```

## Response

### Thành công (HTTP 200)

_Lấy từ một lần gọi thật trên môi trường Staging._

```json
{
  "code": 200,
  "message": "Success",
  "data": {
    "total": 20900,
    "service_fee": 20900,
    "insurance_fee": 0,
    "cod_fee": 0,
    "pick_station_fee": 0,
    "coupon_value": 0,
    "r2s_fee": 0,
    "return_again": 0,
    "document_return": 0,
    "double_check": 0,
    "pick_remote_areas_fee": 0,
    "deliver_remote_areas_fee": 0,
    "cod_failed_fee": 0,
    "change_to_address_fee": 0,
    "change_return_address_fee": 0,
    "return": 0
  }
}
```

### Các trường Response

Mọi số tiền đơn vị VND.

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `total` | Int | Tổng phí |
| `service_fee` | Int | Phí vận chuyển cơ bản |
| `insurance_fee` | Int | Phí bảo hiểm (theo giá trị khai) |
| `cod_fee` | Int | Phí thu hộ COD |
| `pick_station_fee` | Int | Phí lấy hàng tại bưu cục |
| `coupon_value` | Int | Giá trị giảm giá coupon |
| `r2s_fee` | Int | Phí giao lại ("trả về shop") |
| `return_again` | Int | Phí trả hàng lặp lại |
| `document_return` | Int | Phí trả chứng từ |
| `double_check` | Int | Phí đồng kiểm |
| `pick_remote_areas_fee` | Int | Phí lấy hàng vùng xa |
| `deliver_remote_areas_fee` | Int | Phí giao hàng vùng xa |
| `cod_failed_fee` | Int | Phí thu tiền khi giao thất bại |
| `change_to_address_fee` | Int | Phí đổi địa chỉ giao |
| `change_return_address_fee` | Int | Phí đổi địa chỉ trả |
| `return` | Int | Phí trả hàng đã ghi nhận trên đơn |

## Bảng mã lỗi

| code_message | HTTP | Khi nào |
| --- | --- | --- |
| `USER_ERR_COMMON` | 400 | Thiếu/`0` `weight`, hoặc dữ liệu không hợp lệ |
| `CLIENT_NOT_OWNER_OF_SHOP` | 400 | Token không sở hữu shop |
| `SERVER_ERROR_COMMON` | 500 | Lỗi hệ thống |