> For the complete documentation index, see [llms.txt](https://apidocs.nhanh.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.nhanh.vn/v3/ship/cancel.md).

# Hủy đơn

* Hủy đơn hàng đã tạo hoặc đã gửi sang hãng vận chuyển.
* Đơn hàng cần có `orderId` để truy xuất thông tin.

## Request

* Xem [common request params](/v3/readme.md#request-params).
* Xem [Postman sample](/v3/ship/cancel.md).

```curl
curl --location 'https://ship.open.nhanh.vn/v3.0/shipment/cancel?businessId={{businessId}}&appId={{appId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
    "orderId": 12345,
    "cancelReason": "Khách hàng yêu cầu hủy"
}'
```

### Body

| Key          | Type                     | Description                |
| ------------ | ------------------------ | -------------------------- |
| orderId      | int $$^{\color{red}\*}$$ | ID đơn hàng trong hệ thống |
| cancelReason | string                   | Lý do hủy đơn (optional)   |

## Luồng thực hiện

```
1. Tạo đơn hàng: POST /v3.0/shipment/create
   ↓
2. (Tùy chọn) Gửi đơn sang hãng: POST /v3.0/shipment/send
   ↓
3. Hủy đơn: POST /v3.0/shipment/cancel
   ↓
4. Nhận response xác nhận hủy
```

> **Lưu ý:**
>
> * Đơn hàng chưa gửi sang hãng: hủy trực tiếp trong hệ thống.
> * Đơn hàng đã gửi sang hãng: hệ thống sẽ gọi API hủy của hãng vận chuyển tương ứng.

## Trạng thái đơn hàng

| Trạng thái                | Giá trị | Mô tả                     |
| ------------------------- | ------- | ------------------------- |
| STATUS\_NEW               | 54      | Đơn mới tạo               |
| STATUS\_CARRIER\_CANCELED | 58      | Hãng vận chuyển đã hủy    |
| STATUS\_CANCELED          | 63      | Khách hàng/người dùng hủy |
| STATUS\_ABORTED           | 64      | Hệ thống hủy              |

## Response

* Xem cấu trúc chung [tại đây](/v3/readme.md#response).

### Failed response

* Xem các mã lỗi chung [tại đây](/v3/readme.md#failed-response).

Các mã lỗi riêng của API này:

| Mã lỗi                        | Ý nghĩa                                           |
| ----------------------------- | ------------------------------------------------- |
| ERR\_INVALID\_DATA            | Không tìm thấy đơn hàng với orderId và businessId |
| ERR\_CARRIER\_CANCEL\_ORDER   | Lỗi khi hủy đơn trên hãng vận chuyển              |
| ERR\_CANNOT\_CONNECT\_CARRIER | Lỗi kết nối với hãng vận chuyển                   |

### Successful response

```json
{
  "code": 1,
  "data": {
    "orderId": "(int) ID đơn hàng trong hệ thống",
    "status": "(int) Trạng thái mới của đơn hàng",
    "statusName": "(string) Tên trạng thái (VD: 'Khách hủy')",
    "createdDate": "(string) Ngày tạo đơn (YYYY-MM-DD HH:ii:ss)"
  },
  "messages": [],
  "errorCode": null
}
```

## Ví dụ

### Bước 1: Tạo đơn và gửi sang hãng

```bash
# Tạo đơn
curl --location 'https://ship.open.nhanh.vn/v3.0/shipment/create' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
    "businessStoreId": 123,
    "sender": {
        "name": "Nguyễn Văn A",
        "mobile": "0901234567",
        "shippingLocation": {
            "provinceId": 1,
            "wardId": 100,
            "address": "123 Nguyễn Trãi, Hà Nội",
            "longitude": 105.804567,
            "latitude": 21.001234
        }
    },
    "receiver": {
        "name": "Trần Thị B",
        "mobile": "0912345678",
        "shippingLocation": {
            "provinceId": 48,
            "wardId": 12345,
            "address": "456 Lê Lợi, Đà Nẵng"
        }
    },
    "weight": 1500,
    "carrierId": 18,
    "carrierServiceId": 100,
    "totalFee": 25000,
    "shipFee": 25000,
    "customerShipFee": 22000,
    "totalCod": 650000,
    "sendCarrier": 1
}'
```

### Bước 2: Hủy đơn hàng

```bash
curl --location 'https://ship.open.nhanh.vn/v3.0/shipment/cancel?businessId={{businessId}}&appId={{appId}}' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
    "orderId": 12345,
    "cancelReason": "Khách hàng yêu cầu hủy đơn"
}'
```

**Response:**

```json
{
  "code": 1,
  "data": {
    "orderId": 12345,
    "status": 63,
    "statusName": "Khách hủy",
    "createdDate": "2024-08-25 10:30:00"
  },
  "messages": [],
  "errorCode": null
}
```