> For the complete documentation index, see [llms.txt](https://apidoc.247express.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidoc.247express.vn/customer/tao-don-hang.md).

# Tạo đơn hàng

## Địa chỉ người nhận

* Đối với địa chỉ có cấu trúc 3 cấp (Tỉnh/thành, quận/huyện, phường/xã theo cấu trúc địa giới Việt Nam trước ngày 01.07.2025) truyền thông tin như sau:
  * ReceiverProvinceName: tên tỉnh/thành người nhận.
  * ReceiverDistrictName: tên quận/huyện người nhận.
  * ReceiverWardName: tên phường/xã người nhận.
* Đối với địa chỉ có cấu trúc 2 cấp (Tỉnh/thành, phường/xã theo cấu trúc địa giới Việt Nam từ ngày 01.07.2025) truyền thông tin như sau:
  * ReceiverProvinceName: tên tỉnh/thành người nhận.
  * <mark style="color:red;">ReceiverDistrictName: không truyền.</mark>
  * ReceiverWardName: tên phường/xã người nhận.

## CustomerAPICreateOrder

<mark style="color:green;">`POST:`</mark>`/Api/Customer/CustomerAPICreateOrder`

**Headers**

| Name     | Value                |
| -------- | -------------------- |
| ClientID | Lấy từ api đăng nhập |
| Token    | Lấy từ api đăng nhập |

**Body**

<table><thead><tr><th width="231">Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>ClientHubID</td><td>number</td><td>Mã địa chỉ khách hàng (Bắt buộc khi không truyền CusWareHouseID và KH có địa chỉ gửi cố định)</td></tr><tr><td>CusWareHouseID</td><td>string</td><td>Mã kho/shop (Bắt buộc khi không truyền ClientHubID và KH có địa chỉ gửi cố định)</td></tr><tr><td>ContactName</td><td>string</td><td>Tên người liên hệ gửi hàng</td></tr><tr><td>ContactPhone</td><td>string</td><td>SĐT người liên hệ gửi hàng (bắt buộc khi KH có địa chỉ gửi không cố định)</td></tr><tr><td>DirectSenderName</td><td>string</td><td>Người đi gửi Thư/Hàng (bắt buộc khi KH có địa chỉ gửi không cố định)</td></tr><tr><td>SenderAddress</td><td>string</td><td>Địa chỉ đầy đủ người gửi, bao gồm: số nhà, tên đường, tên xã, tên huyện, tên tỉnh. (bắt buộc khi KH có địa chỉ gửi không cố định)</td></tr><tr><td>ReceiverPhone<mark style="color:red;">*</mark></td><td>string</td><td>Số điện thoại người nhận</td></tr><tr><td>ReceiverName</td><td>string</td><td>Tên người nhận</td></tr><tr><td>ReceiverAddress<mark style="color:red;">*</mark></td><td>string</td><td>Địa chỉ đầy đủ của người nhận (Cấu trúc địa chỉ 3 cấp: số nhà, tên đường, tên xã, tên huyện, tên tỉnh/ Cấu trúc địa chỉ 2 cấp: Số nhà, tên đường, tên xã, tên tỉnh)</td></tr><tr><td>ReceiverProvinceName<mark style="color:red;">*</mark></td><td>string</td><td>Tên Tỉnh/Thành phố người nhận</td></tr><tr><td>ReceiverDistrictName<mark style="color:red;">*</mark></td><td>string</td><td>Tên Quận/Huyện người nhận (null nếu sử dụng địa chỉ 2 cấp Tỉnh/thành phố, Phường/xã)</td></tr><tr><td>ReceiverWardName</td><td>string</td><td>Tên Phường/Xã người nhận</td></tr><tr><td>ReceiveCompanyName</td><td>string</td><td>Công ty nhận</td></tr><tr><td>RealWeight</td><td>number</td><td>Trọng lượng thực tế (kg)</td></tr><tr><td>Length</td><td>number</td><td>Chiều dài (cm)</td></tr><tr><td>Width</td><td>number</td><td>Chiều rộng (cm)</td></tr><tr><td>Height</td><td>number</td><td>Chiều cao (cm)</td></tr><tr><td>Quantity</td><td>number</td><td>Số lượng kiện</td></tr><tr><td>Note</td><td>string</td><td>Ghi chú</td></tr><tr><td>ServiceTypeID<mark style="color:red;">*</mark></td><td>string</td><td>Mã dịch vụ</td></tr><tr><td>MailerType</td><td>string</td><td>Mã loại hàng hóa vận chuyển: HH - Hàng hóa. TL - Tài liệu.</td></tr><tr><td>CODAmount</td><td>number</td><td>Tiền thu người nhận</td></tr><tr><td>ExternalCode</td><td>string</td><td>Mã vận đơn khách hàng (tối đa 20 ký tự)</td></tr><tr><td>ReferenceCode</td><td>string</td><td>Mã tham chiếu khách hàng</td></tr><tr><td>SpecialInstructionId</td><td>number</td><td>Mã ghi chú đặc biệt chỉ đối với đơn hàng COD: 1 - Cho xem hàng. 0 - Không cho xem hàng.</td></tr><tr><td>InformFee</td><td>string</td><td>Giá trị kê khai. Các trường hợp lưu ý khi kê khai: 1 - Trọng lượng tính giá >= 2.5kg bắt buộc chọn Loại hình = HH(hàng hóa) 2 - Loại hình = HH bắt buộc nhập giá trị kê khai 3 - Đơn chọn DVBH (Dịch vụ bảo hiểm) thì bắt buộc nhập giá trị kê khai.</td></tr><tr><td>ExtraServices</td><td>array</td><td>Danh sách các dịch vụ gia tăng</td></tr><tr><td>Packages</td><td>array</td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">{
    "PackageID": "", //Mã kiện,
    "Length": 100, // Kích thước (Dài - bắt buộc khi có nhập Rộng, Cao)(cm),
    "Width": 50, // Kích thước (Rộng - bắt buộc khi có nhập Dài, Cao)(cm),
    "Height": 80,// Kích thước (Cao - Bắt buộc khi có nhập Dài, Rộng)(cm),
    "RealWeight": 25// Trọng lượng thực của kiện (kg)
}
</code></pre><p>(*)Số lượng Packages phải khớp với Quantity. Trường hợp Quantity = 1 thì Packages = []</p></td></tr><tr><td>COPAmt</td><td>number</td><td>Tiền COP (Cash on pickup)</td></tr><tr><td>RequestedDeliveryTime</td><td>DateTime</td><td>Thời gian hẹn phát (*chỉ áp dụng cho các DVGT có hẹn giờ phát)</td></tr><tr><td>RequestedDeliveryType</td><td>string</td><td>Loại hẹn phát:
<br>"DUNGGIO" : Đúng giờ
<br>"TRUOCGIO" : Trước giờ
<br>(*chỉ áp dụng cho các DVGT có hẹn giờ phát)</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "Errors": [],
    "ErrorCode": "0",
    "OrderInfo": {
        "OrderCode": "HD000003",
        "ReferenceCode": "HD000003",
        "ExternalCode": "HD000003",
        "TotalServiceCost": 44176,
        "ExtraServices": [
            {
                "ServiceName": "Chuyển phát nhanh",
                "ServiceID": "DE",
                "Cost": 16800
            },
            {
                "ServiceName": "Hàng đông lạnh",
                "ServiceID": "HDL",
                "Cost": 15000
            },
            {
                "ServiceName": "Báo phát",
                "ServiceID": "BP",
                "Cost": 5000
            },
            {
                "ServiceName": "Phí xăng dầu",
                "ServiceID": "Fuel",
                "Cost": 3360
            },
            {
                "ServiceName": "Phí VAT",
                "ServiceID": "VAT",
                "Cost": 4016
            }
        ],
        "DeliveryType": "1"
    },
    "ErrorMessage": ""
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "IsError": true,
    "ErrorMessage": "Bạn cần đăng nhập để truy cập chức năng này."
}
```

{% endtab %}
{% endtabs %}

| Name             | Type         | Description                                                             |
| ---------------- | ------------ | ----------------------------------------------------------------------- |
| Errors           | array object | Mảng các lỗi trả về                                                     |
| ErrorCode        | string       | Mã lỗi                                                                  |
| ErrorMessage     | string       | Thông báo lỗi                                                           |
| **OrderInfo**    | object       | Thông tin đơn hàng tạo thành công                                       |
| OrderCode        | string       | Mã đơn hàng                                                             |
| ReferenceCode    | string       | Mã tham chiếu khách hàng                                                |
| ExternalCode     | string       | Mã đơn hàng khách hàng                                                  |
| TotalServiceCost | number       | Tổng phí                                                                |
| **ExtraService** | array object | Danh sách các dịch vụ của đơn hàng                                      |
| ServiceName      | string       | Tên dịch vụ                                                             |
| ServiceID        | string       | Mã dịch vụ                                                              |
| Cost             | number       | Phí dịch vụ                                                             |
| DeliveryTimeType | string       | <p>Đơn vị thực hiện phát:<br>"1" - 247 phát<br>"2" - Bên thứ 3 phát</p> |

### Mẫu ví dụ

```json5
{
   "OrderInfo":{
      "ClientHubID":11583,
      "CusWareHouseID":"30984",
      "ContactName": "Trần Văn B",
      "ContactPhone": "0332318317",
      "DirectSenderName": "Nguyễn Văn A",
      "SenderAddress": "145/6C Trần Bá Giao, Phường 5, Gò Vấp, HCM",      
      "ReceiverPhone":"0345555777",
      "ReceiverName":"Trương Chí Nhân",
      "ReceiverAddress":"326 Võ Văn Kiệt, phường Cầu Ông Lãnh, Hồ Chí Minh, Việt Nam",
      "ReceiverProvinceName":"Hồ Chí Minh",
      "ReceiverDistrictName": null,
      "ReceiverWardName":"Phường Cầu Ông Lãnh",   
      "RealWeight":1,
      "Length":0,
      "Width":0,
      "Height":0,
      "Quantity":1,
      "Note":"Tài liệu",
      "ServiceTypeID":"DE",
      "MailerType":"TL",
      "CODAmount":0,
      "ExternalCode":"HD000003",
      "ReferenceCode": "HD000003",
      "SpecialInstructionId":1,
      "ExtraServices":[
         {
            "ServiceID":"PTN",
            "Type":2
         },
         {
            "ServiceID":"BP",
            "Type":2
         }
      ]
   }
}
```

### Thông tin mã lỗi

{% hint style="danger" %}

* 1: Thông tin Phường/Xã không chính xác
* 2: Thông tin Quận/Huyện không chính xác
* 3: Thông tin Tỉnh/Thành không chính xác
* 4: Trùng mã đơn hàng
* 5: Server error
* 6: Có lỗi xảy ra trong quá trình xử lý
* 9: Lỗi chưa cập nhật ghi chú đặc biệt
* 10: Lỗi chưa truyền dịch vụ
* 11: Địa chỉ gửi hàng không hợp lệ
* 12: Tài khoản khách hàng không hợp lệ
* 15: Chưa truyền mã đơn hàng
* 16: Đơn hàng không hợp lệ
* 17: Địa chỉ người nhận không hợp lệ
* 18: Mã loại hàng hóa vận chuyển không hợp lệ
* 19: Số lượng kiện không hợp lệ
* 20: Chi tiết kiện không hợp lệ
* 21: Thông tin người gửi chưa đầy đủ
* 25: Tiền COP không hợp lệ
  {% endhint %}