# Thời gian giao dự kiến

> Ước tính thời gian giao hàng dự kiến cho một tuyến trước khi tạo đơn.

## Endpoint

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

**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) |

## Tham số

- **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
- **weight** (Int): Khối lượng (gram) — ảnh hưởng ước tính với hàng nặng
- **length** (Int): Chiều dài (cm)
- **width** (Int): Chiều rộng (cm)
- **height** (Int): Chiều cao (cm)

> **NOTE**
> Dùng `service_type_id`, không dùng `service_id`. Trang api.ghn.vn có hiển thị `service_id` nhưng nó không ảnh hưởng đến kết quả ước tính.

## Ví dụ Request

```bash
curl -X POST https://dev-online-gateway.ghn.vn/shiip/public-api/v2/shipping-order/leadtime \
  -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
  }'
```

## 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": {
    "leadtime": 1784221199,
    "leadtime_order": {
      "from_estimate_date": "2026-07-16T16:59:59Z",
      "to_estimate_date": "2026-07-16T16:59:59Z"
    }
  }
}
```

### Các trường Response

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `code` | Int | Mã HTTP (`200` nếu thành công) |
| `message` | String | Thông báo kết quả (`Success`) |
| `data.leadtime` | Int | Thời gian giao dự kiến dạng **Unix timestamp (giây)** (không phải ngày ISO) |
| `data.leadtime_order.from_estimate_date` | String | Thời điểm giao sớm nhất dự kiến (ISO 8601) |
| `data.leadtime_order.to_estimate_date` | String | Thời điểm giao muộn nhất dự kiến (ISO 8601) |

### Lỗi — thiếu to_district_id (HTTP 400)

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

```json
{
  "code": 400,
  "message": "Key: 'myRequest.ToDistrictID' Error:Field validation for 'ToDistrictID' failed on the 'required' tag",
  "data": null,
  "code_message": "USER_ERR_COMMON",
  "code_message_value": "Sai thông tin đầu vào. Vui lòng thử lại."
}
```

## Bảng mã lỗi

| code_message | HTTP | Khi nào |
| --- | --- | --- |
| `USER_ERR_COMMON` | 400 | Thiếu `to_district_id` / `to_ward_code`, 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 |