API đăng đơn hàng

Đối tác gửi danh sách đơn hàng sang hệ thống của OMS thông qua APIs. Sau khi các đơn hàng được lưu thành công vào hệ thống của OMS, hệ thống sẽ trả về danh sách đơn hàng tương ứng chứa các thông tin liên quan của mỗi đơn hàng.

Đường dẫn

POST /api/v1/orders

Headers

Authorization: Bearer {JWT}
X-Client-Source: {PARTNER_CODE}
Content-Type: application/json

CURL

curl --location '{{url}}/api/v1/orders' \
--header 'Authorization: Bearer {{token}}' \
--header 'X-Client-Source: mwg' \
--header 'Content-Type: application/json' \
--data-raw '{
    "delivery": {
        "name": "Trần Thị B",
        "address": "Trường Đại học Quốc gia Hà Nội",
        "province": "Hà Nội",
        "ward": "Phường Cầu Giấy",
        "hamlet": "Khác",
        "tel": "0912345678",
        "email": "tran.b@example.com",
        "work_shift": 2,
        "date": "2025-08-01",
        "method": "xteam"
    },
    "pickup": {
        "name": "Nguyễn Văn A",
        "address_id": "ADDR001",
        "address": "Số 97 ngõ 14 Mễ Trì Hạ",
        "province": "Hà Nội",
        "ward": "Phường Từ Liêm",
        "tel": "0901234567",
        "email": "nguyenvana@example.com",
        "work_shift": 1,
        "date": "2025-07-30",
        "method": "cod"
    },
    "items": [
        {
            "name": "Áo thun",
            "price": 200000,
            "weight": 0.3,
            "quantity": 2,
            "code": "TSHIRT001"
        },
        {
            "name": "Quần jeans",
            "price": 400000,
            "weight": 0.8,
            "quantity": 1,
            "code": "JEANS123"
        }
    ],
    "order": {
        "partner_id": "MGW_ORDER_1",
        "service_type": 1,
        "cod_amount": 100000,
        "note": "Giao giờ hành chính",
        "is_freeship": 1,
        "weight_option": "kilogram",
        "total_weight": 1.4,
        "label_id": "LBL001",
        "expired": "2025-08-10T17:00:00+07:00",
        "declared_value": 500000,
        "opm": 0,
        "actual_transfer_method": "fly",
        "transport": "road",
        "tags": [
        "fragile",
        "new_customer"
        ],
        "sub_tags": [
        "plant",
        "bonsai"
        ]
    },
    "metadata": {
        "delivery_instructions": "Gọi trước 5 phút khi giao"
    },
    "txid": "ABCD123456"
}'

HTTP

POST /api/v1/orders HTTP/1.1
Authorization: Bearer {{token}}
X-Client-Source: mwg
Content-Type: application/json
{
    "delivery": {
        "name": "Trần Thị B",
        "address": "Trường Đại học Quốc gia Hà Nội",
        "province": "Hà Nội",
        "ward": "Phường Cầu Giấy",
        "hamlet": "Khác",
        "tel": "0912345678",
        "email": "tran.b@example.com",
        "work_shift": 2,
        "date": "2025-08-01",
        "method": "xteam"
    },
    "pickup": {
        "name": "Nguyễn Văn A",
        "address_id": "ADDR001",
        "address": "Số 97 ngõ 14 Mễ Trì Hạ",
        "province": "Hà Nội",
        "ward": "Phường Từ Liêm",
        "tel": "0901234567",
        "email": "nguyenvana@example.com",
        "work_shift": 1,
        "date": "2025-07-30",
        "method": "cod"
    },
    "items": [
        {
            "name": "Áo thun",
            "price": 200000,
            "weight": 0.3,
            "quantity": 2,
            "code": "TSHIRT001"
        },
        {
            "name": "Quần jeans",
            "price": 400000,
            "weight": 0.8,
            "quantity": 1,
            "code": "JEANS123"
        }
    ],
    "order": {
        "partner_id": "MGW_ORDER_1",
        "service_type": 1,
        "cod_amount": 100000,
        "note": "Giao giờ hành chính",
        "is_freeship": 1,
        "weight_option": "kilogram",
        "total_weight": 1.4,
        "label_id": "LBL001",
        "expired": "2025-08-10T17:00:00+07:00",
        "declared_value": 500000,
        "opm": 0,
        "actual_transfer_method": "fly",
        "transport": "road",
        "tags": [
        "fragile",
        "new_customer"
        ],
        "sub_tags": [
        "plant",
        "bonsai"
        ]
    },
    "metadata": {
        "delivery_instructions": "Gọi trước 5 phút khi giao"
    },
    "txid": "ABCD123456"
}

Các tham số

Tham số	Bắt buộc	Kiểu dữ liệu	Mô tả
pickup	yes	object	Thông tin điểm lấy hàng
delivery	yes	object	Thông tin điểm giao hàng
items	yes	array	Thông tin sản phẩm
order	yes	object	Các thông tin của đơn hàng
use_return_address	no	integer	Integer - mặc định là 0. Field này có thể truyền vào một trong hai giá trị 0 hoặc 1. Bằng 0 nghĩa là địa chỉ trả hàng giống địa chỉ lấy hàng nên các field địa chỉ trả hàng không cần truyền qua. Bằng 1 nghĩa là sử dụng địa chỉ trả hàng khác địa chỉ lấy hàng và cần truyền vào giá trị cho các field tiếp theo
return	no	object	Thông tin điểm trả hàng
metadata	no	object	Các thông tin thêm
txid	no	string	Mã tracing request

Tham số pickup - Thông tin điểm lấy hàng

Tham số	Bắt buộc	Kiểu dữ liệu	Mô tả
name	yes	string	Tên người liên hệ lấy hàng hóa
address_id	yes	integer	ID địa điểm lấy hàng từ trang quản lý của khách hàng
last_update	yes	String	Thời gian cuối cùng update địa chỉ (yyyy-MM-dd HH:mm:ss)
address	yes	string	Địa chỉ chi tiết lấy hàng (VD nhà số 5, tổ 3, ngách 11, ngõ 45)
lat	no	number	Vĩ độ của điểm lấy hàng
lng	no	number	Kinh độ của điểm lấy hàng
province	yes	string	Tỉnh/Thành phố lấy hàng
ward	yes	string	Phường/xã lấy hàng (bắt buộc khi không có street)
street	yes	string	Đường/phố lấy hàng (bắt buộc khi không có ward)
tel	yes	string	Số điện thoại nơi lấy hàng
email	no	string	Email nơi lấy hàng
work_shift	no	integer	Ca lấy hàng (1 = sáng, 2 = chiều, 3 = tối)
date	no	string	Ngày lấy hàng (YYYY-MM-DD, yêu cầu cấu hình riêng)
method	no	string	Hình thức lấy hàng ([cod, post] COD tới lấy, shop gửi tại bưu cục). Mặc định là cod

Tham số delivery - Thông tin điểm giao hàng

Tham số	Bắt buộc	Kiểu dữ liệu	Mô tả
name	yes	string	Tên người nhận hàng
address_id	Yes	integer	ID địa điểm lấy hàng từ trang quản lý của khách hàng
last_update	Yes	String	Thời gian cuối cùng update địa chỉ (yyyy-MM-dd HH:mm:ss)
address	yes	string	Địa chỉ chi tiết người nhận hàng
province	yes	string	Tỉnh/thành phố người nhận
ward	yes	string	Phường/xã người nhận (bắt buộc khi không có street)
street	yes	string	Tên đường người nhận (bắt buộc khi không có ward)
hamlet	yes	string	Thôn/áp/xóm/tổ... người nhận. Nếu không có, dùng "Khác"
lat	no	number	Vĩ độ của điểm nhận hàng
lng	no	number	Kinh độ của điểm nhận hàng
tel	yes	string	Số điện thoại người nhận
email	yes	string	Email người nhận
work_shift	no	integer	Ca giao hàng (1 = sáng, 2 = chiều, 3 = tối)
date	no	string	Ngày giao hàng (YYYY/MM/DD, yêu cầu cấu hình riêng)

Tham số items - Thông tin sản phẩm

Tham số	Bắt buộc	Kiểu dữ liệu	Mô tả
name	yes	string	Tên hàng hóa
price	no	integer	Giá trị hàng hóa
weight	yes	float	Khối lượng hàng hóa (kg)
quantity	yes	integer	Số lượng hàng hóa
code	yes	string	Mã sản phẩm

Tham số order - Các thông tin của đơn hàng

Tham số	Bắt buộc	Kiểu dữ liệu	Mô tả
partner_id	yes	string	Mã đơn hàng thuộc hệ thống của đối tác
service_type	yes	integer	Loại dịch vụ (1: Giao hỏa tốc / 2: Giao nhanh/ 3: Giao tiêu chuẩn)
cod_amount	yes	integer	Số tiền COD (VND). Nếu bằng 0 thì không thu tiền
declared_value	no	integer	Giá trị đóng khai giá, là căn cứ để tính phí khai giá và bồi thường khi có sự cố
note	no	string	Ghi chú đơn hàng (tối đa 120 ký tự)
is_freeship	no	integer	1 = người nhận không chịu phí ship (COD chỉ thu cod_amount)
weight_option	yes	string	Đơn vị khối lượng (gram hoặc kilogram)
total_weight	no	number	Tổng khối lượng đơn hàng (sẽ tính theo products.weight nếu không truyền)
label_id	no	string	Mã vận đơn cấp trước (yêu cầu cấu hình riêng)
expired	no	string	Thời gian hết hạn đơn hàng (yêu cầu cấu hình riêng)
opm	no	integer	1 = đơn chỉ thu tiền, 0 = bình thường (mặc định)
actual_transfer_method	no	string	Hình thức vận chuyển thực tế (mặc định fly)
transport	no	string	Phương thức vận chuyển
tags	no	array	Danh sách nhãn gắn vào đơn hàng
sub_tags	no	array	Chi tiết nhân đơn hàng (bắt buộc khi đơn là hàng cấy cối)

Mô tả dịch vụ vận chuyển order.service_type

Giá trị	Loại dịch vụ
1	Hỏa tốc (< 2h)
2	Nhanh (< 4h)
3	Tiêu chuẩn

Tham số return - Thông tin điểm trả hàng

Tham số	Bắt buộc	Kiểu dữ liệu	Mô tả
name	yes	string	Tên người nhận hàng trả
address_id	Yes	integer	ID địa điểm lấy hàng từ trang quản lý của khách hàng
last_update	Yes	String	Thời gian cuối cùng update địa chỉ (yyyy-MM-dd HH:mm:ss)
address	yes	string	Địa chỉ chi tiết người nhận hàng trả
lat	no	number	Vĩ độ của điểm nhận hàng trả
lng	no	number	Kinh độ của điểm nhận hàng trả
province	yes	string	Tỉnh/thành phố người nhận hàng trả
ward	yes	string	Phường/xã người nhận hàng trả (bắt buộc khi không có street)
street	yes	string	Tên đường người nhận hàng trả (bắt buộc khi không có ward)
tel	yes	string	Số điện thoại người nhận hàng trả
email	no	string	Email người nhận hàng trả

Phản hồi

Kết quả trả về khi đăng đơn thành công:

{
  "status": 201,
  "message": "Tạo đơn hàng thành công",
  "timestamp": "2025-10-10T15:36:56.794Z",
  "data": {
    "partner_id": "MGW_ORDER_1",
    "oms_order_id": 631772143381778432,
    "items": [
      {
        "name": "Áo thun",
        "price": 200000.00,
        "weight": 0.3,
        "quantity": 2,
        "code": "TSHIRT001"
      },
      {
        "name": "Quần jeans",
        "price": 400000.00,
        "weight": 0.8,
        "quantity": 1,
        "code": "JEANS123"
      }
    ],
    "status": "ORDER_CREATED"
  }
}

Trường hợp có lỗi

{
  "status": 400,
  "message": "Thiếu thông tin địa chỉ",
  "error_code": 4010106,
  "timestamp": "2025-10-10T11:33:00.458Z"
}

Lưu ý

info

Lưu ý: Đơn vị khối lượng sử dụng cho từng sản phẩm là KG

warning

Lưu ý: Phí ship ban đầu sẽ được tính theo tổng khối lượng các sản phẩm có trong đơn hàng

warning

Lưu ý:

• Nếu đơn hàng được set is_freeship = 1, COD sẽ chỉ thu người nhận hàng số tiền bằng pick_money
• Nếu giá trị được set bằng 0, COD sẽ thu tiền người nhận số tiền bằng pick_money + phí ship của đơn hàng, giá trị mặc định bằng 0