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.

• Xem Postman sample.

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.

Failed response

• Xem các mã lỗi chung tại đây.

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

{
  "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

# 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

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:

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