Phiên bản: 3.0.0

Tạo đơn

Tạo đơn hàng với một hoặc nhiều điểm giao hàng

Tạo đơn dùng `service_id` và `requests`

cURL
JavaScript

curl --location 'https://partner-apistg.ahamove.com/v3/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "order_time": 0,
    "path": [
        {
            "lat": 10.76975346,
            "lng": 106.6636615,
            "address": "7/28 Thành Thái, Phường 14, Quận 10, Thành phố Hồ Chí Minh",
            "short_address": "Thành Thái, Quận 10",
            "name": "Lan",
            "mobile": "84944309348",
            "remarks": "Đến nơi lấy hàng đọc mã đơn để nhận hàng"
        },
        {
            "lat": 10.8018493,
            "lng": 106.714466,
            "address": "475A Điện Biên Phủ, Phường 25, Bình Thạnh, Thành phố Hồ Chí Minh",
            "short_address": "Đại Học Hutech, Quận Bình Thạnh, Hồ Chí Minh",
            "name": "Anh",
            "mobile": "0912345678",
            "cod": 100000,
            "item_value": 250000,
            "tracking_number": "ABCD1234",
            "remarks": "Gọi điện trước khi giao. Giao hàng cẩn thận"
        }
    ],
    "service_id": "SGN-BIKE",
    "requests": [
        {
            "_id": "SGN-BIKE-TIP",
            "num": 1
        },
        {
            "_id": "SGN-BIKE-BULKY",
            "tier_code": "TIER_2"
        }
    ],
    "payment_method": "CASH",
    "remarks": "Ghi chú đơn hàng",
    "promo_code" : "AHMKM",
    "items": [
        {
            "_id": "TG",
            "num": 1,
            "name": "Tủ gỗ nhỏ",
            "price": 450000
        },
        {
            "_id": "GDB",
            "num": 2,
            "name": "Gương để bàn",
            "price": 120000
        }
    ],
    "package_detail": [
        {
            "weight": 10,
            "length": 1.2,
            "width": 0.8,
            "height": 2.0,
            "description": "Nội thất"
        }
    ]
}'

const myHeaders = new Headers();
myHeaders.append('Content-Type', 'application/json');
myHeaders.append('Authorization', 'Bearer <token>');

const raw = JSON.stringify({
  order_time: 0,
  path: [
    {
      lat: 10.76975346,
      lng: 106.6636615,
      address: '7/28 Thành Thái, Phường 14, Quận 10, Thành phố Hồ Chí Minh',
      short_address: 'Thành Thái, Quận 10',
      name: 'Lan',
      mobile: '84944309348',
      remarks: 'Đến nơi lấy hàng đọc mã đơn để nhận hàng',
    },
    {
      lat: 10.8018493,
      lng: 106.714466,
      address:
        '475A Điện Biên Phủ, Phường 25, Bình Thạnh, Thành phố Hồ Chí Minh',
      short_address: 'Đại Học Hutech, Quận Bình Thạnh, Hồ Chí Minh',
      name: 'Anh',
      mobile: '0912345678',
      cod: 100000,
      item_value: 250000,
      tracking_number: 'ABCD1234',
      remarks: 'Gọi điện trước khi giao. Giao hàng cẩn thận',
    },
  ],
  service_id: 'SGN-BIKE',
  requests: [
    {
      _id: 'SGN-BIKE-TIP',
      num: 1,
    },
    {
      _id: 'SGN-BIKE-BULKY',
      tier_code: 'TIER_2',
    },
  ],
  payment_method: 'CASH',
  remarks: 'Ghi chú đơn hàng',
  promo_code: 'AHMKM',
  items: [
    {
      _id: 'TG',
      num: 1,
      name: 'Tủ gỗ nhỏ',
      price: 450000,
    },
    {
      _id: 'GDB',
      num: 2,
      name: 'Gương để bàn',
      price: 120000,
    },
  ],
  package_detail: [
    {
      weight: 10,
      length: 1.2,
      width: 0.8,
      height: 2,
      description: 'Nội thất',
    },
  ],
});

const requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow',
};

fetch('https://partner-apistg.ahamove.com/v3/orders', requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Tạo đơn dùng `group_service_id` và `group_requests`

Ahamove sẽ tự xác định service_id dựa vào định vị của địa chỉ lấy hàng và group_service_id

cURL
JavaScript

curl --location 'https://partner-apistg.ahamove.com/v3/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "order_time": 0,
    "path": [
        {
            "lat": 10.76975346,
            "lng": 106.6636615,
            "address": "7/28 Thành Thái, Phường 14, Quận 10, Thành phố Hồ Chí Minh",
            "short_address": "Thành Thái, Quận 10",
            "name": "Lan",
            "mobile": "84944309348",
            "remarks": "Đến nơi lấy hàng đọc mã đơn để nhận hàng"
        },
        {
            "lat": 10.8018493,
            "lng": 106.714466,
            "address": "475A Điện Biên Phủ, Phường 25, Bình Thạnh, Thành phố Hồ Chí Minh",
            "short_address": "Đại Học Hutech, Quận Bình Thạnh, Hồ Chí Minh",
            "name": "Anh",
            "mobile": "0912345678",
            "cod": 100000,
            "item_value": 250000,
            "tracking_number": "ABCD1234",
            "remarks": "Gọi điện trước khi giao. Giao hàng cẩn thận"
        }
    ],
    "group_service_id": "BIKE",
    "group_requests": [
        {
            "_id": "TIP",
            "num": 1
        },
        {
            "_id": "BULKY",
            "tier_code": "TIER_2"
        }
    ],
    "payment_method": "CASH",
    "remarks": "Ghi chú đơn hàng",
    "promo_code" : "AHMKM",
    "items": [
        {
            "_id": "TG",
            "num": 1,
            "name": "Tủ gỗ nhỏ",
            "price": 450000
        },
        {
            "_id": "GDB",
            "num": 2,
            "name": "Gương để bàn",
            "price": 120000
        }
    ],
    "package_detail": [
        {
            "weight": 10,
            "length": 1.2,
            "width": 0.8,
            "height": 2.0,
            "description": "Nội thất"
        }
    ]
}'

const myHeaders = new Headers();
myHeaders.append('Content-Type', 'application/json');
myHeaders.append('Authorization', 'Bearer <token>');

const raw = JSON.stringify({
  order_time: 0,
  path: [
    {
      lat: 10.76975346,
      lng: 106.6636615,
      address: '7/28 Thành Thái, Phường 14, Quận 10, Thành phố Hồ Chí Minh',
      short_address: 'Thành Thái, Quận 10',
      name: 'Lan',
      mobile: '84944309348',
      remarks: 'Đến nơi lấy hàng đọc mã đơn để nhận hàng',
    },
    {
      lat: 10.8018493,
      lng: 106.714466,
      address:
        '475A Điện Biên Phủ, Phường 25, Bình Thạnh, Thành phố Hồ Chí Minh',
      short_address: 'Đại Học Hutech, Quận Bình Thạnh, Hồ Chí Minh',
      name: 'Anh',
      mobile: '0912345678',
      cod: 100000,
      item_value: 250000,
      tracking_number: 'ABCD1234',
      remarks: 'Gọi điện trước khi giao. Giao hàng cẩn thận',
    },
  ],
  group_service_id: 'BIKE',
  group_requests: [
    {
      _id: 'TIP',
      num: 1,
    },
    {
      _id: 'BULKY',
      tier_code: 'TIER_2',
    },
  ],
  payment_method: 'CASH',
  remarks: 'Ghi chú đơn hàng',
  promo_code: 'AHMKM',
  items: [
    {
      _id: 'TG',
      num: 1,
      name: 'Tủ gỗ nhỏ',
      price: 450000,
    },
    {
      _id: 'GDB',
      num: 2,
      name: 'Gương để bàn',
      price: 120000,
    },
  ],
  package_detail: [
    {
      weight: 10,
      length: 1.2,
      width: 0.8,
      height: 2,
      description: 'Nội thất',
    },
  ],
});

const requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow',
};

fetch('https://partner-apistg.ahamove.com/v3/orders', requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

HTTP Request

POST https://partner-apistg.ahamove.com/v3/orders

Headers

Parameter	Value	Yêu cầu	Mô tả
Content-Type	application/json	Có
Authorization	Bearer `<token>`	Có	Token của người tạo đơn

Body

{
  "order_time": 0,
  "path": [
    {
      "lat": 10.76975346,
      "lng": 106.6636615,
      "address": "7/28 Thành Thái, Phường 14, Quận 10, Thành phố Hồ Chí Minh",
      "short_address": "Thành Thái, Quận 10",
      "name": "Lan",
      "mobile": "84944309348",
      "remarks": "Đến nơi lấy hàng đọc mã đơn để nhận hàng"
    },
    {
      "lat": 10.8018493,
      "lng": 106.714466,
      "address": "475A Điện Biên Phủ, Phường 25, Bình Thạnh, Thành phố Hồ Chí Minh",
      "short_address": "Đại Học Hutech, Quận Bình Thạnh, Hồ Chí Minh",
      "name": "Anh",
      "mobile": "0912345678",
      "cod": 100000,
      "item_value": 250000,
      "tracking_number": "ABCD1234",
      "remarks": "Gọi điện trước khi giao. Giao hàng cẩn thận"
    }
  ],
  "service_id": "SGN-BIKE",
  "requests": [
    {
      "_id": "SGN-BIKE-TIP",
      "num": 1
    },
    {
      "_id": "SGN-BIKE-BULKY",
      "tier_code": "TIER_2"
    }
  ],
  "payment_method": "CASH",
  "remarks": "Ghi chú đơn hàng",
  "promo_code": "AHMKM",
  "items": [
    {
      "_id": "TG",
      "num": 1,
      "name": "Tủ gỗ nhỏ",
      "price": 450000
    },
    {
      "_id": "GDB",
      "num": 2,
      "name": "Gương để bàn",
      "price": 120000
    }
  ],
  "package_detail": [
    {
      "weight": 10,
      "length": 1.2,
      "width": 0.8,
      "height": 2.0,
      "description": "Nội thất"
    }
  ]
}

Parameters

Parameter	Type	Yêu cầu	Mô tả
order_time	Float (Unix timestamp)	Có	Thời gian giao hàng. Đặt đơn hàng giao ngay thì `order_time = 0`
path	Array	Có	Danh sách các điểm lấy và giao hàng. Tối thiểu phải có 2 path (thông tin lấy và giao)
service_id	String	Có	Mã dịch vụ của AhaMove (SGN-BIKE, SGN-ECO,...)
requests	Array	Có	Danh sách các dịch vụ kèm theo
group_service_id	String	Có	Nhóm mã dịch vụ của AhaMove (BIKE, ECO, TRUCK-500,...)
group_requests	Array	Có	Nhóm các mã của dịch vụ kèm theo (TIP, BULKY, D2D,...)
payment_method	String	Có	Phương thức thanh toán đơn hàng - `BALANCE`: Thanh toán bằng tài khoản người tạo đơn - `CASH`: Thanh toán bằng tiền mặt bởi người gửi hàng - `CASH_BY_RECIPIENT`: Thanh toán bằng tiền mặt bởi người nhận hàng
promo_code	String	Không	Mã khuyến mãi
remarks	String	Không	Chú thích cho tài xế
idle_until	Float (Unix timestamp)	Không	Hẹn giờ giao hàng. Truyền `idle_until = order_time` (nếu order_time > 0 ) là thời điểm đơn bắt đầu tìm tài xế
items	Array	Không	Danh sách hàng hóa (nếu có)
package_detail	Array	Không	Các thông số kích thước đơn hàng
route_optimized	Boolean	Không	`True` trong trường hợp Đối tác muốn Ahamove tối ưu giao hàng để tiết kiệm chi phí (1 điểm lấy hàng, nhiều hơn 2 điểm giao hàng)

Cách để lấy `group_service_id` và `group_requests`

Cấu trúc của mã dịch vụ:

service_id = city_id + group_service_id

Ví dụ:

service_id	group_service_id
SGN-BIKE	BIKE
SGN-ECO	ECO
SGN-2H	2H
SGN-2H-PUBLIC	2H-PUBLIC
SGN-SAMEDAY	SAMEDAY
SGN-TRUCK-500	TRUCK-500
SGN-TRUCK-1000	TRUCK-1000
SGN-VAN-500	VAN-500

Cấu trúc của mã dịch vụ kèm theo:

requests._id = service_id + group_requests

Ví dụ:

requests._id	group_requests
SGN-BIKE-TIP	TIP
SGN-BIKE-BULKY	BULKY
SGN-BIKE-INSURANCE	INSURANCE
SGN-BIKE-D2D	D2D
SGN-BIKE-SMS	SMS
SGN-BIKE-FRAGILE	FRAGILE
SGN-BIKE-ROUND-TRIP	ROUND-TRIP

Path

Hiển thị từ path[0] đến nhiều path[x], x > 0

Parameter	Type	Yêu cầu	Mô tả
address	String	Có	Địa chỉ lấy hàng, giao hàng đúng định dạng
lat	Number	Có	Vĩ độ của địa điểm (Không bắt buộc nhưng đề xuất Đối tác nên sử dụng)
lng	Number	Có	Kinh độ của địa điểm (Không bắt buộc nhưng đề xuất Đối tác nên sử dụng)
name	String	Có	Tên người gửi, người nhận
mobile	String	Có	Số điện thoại người gửi, người nhận
tracking_number	String	Không	Mã theo dõi của gói hàng (Mã đơn hàng nội bộ của Đối tác, không bắt buộc nhưng Ahamove đề xuất nên có mã này trong `path[x]`)
remarks	String	Không	Chú thích dành cho tài xế của từng điểm lấy hàng, giao hàng
cod	Int	Không	Số tiền COD người gửi cần thu của người nhận (chỉ truyền ở điểm giao hàng)
item_value	Int64	Không	Giá trị thực của gói hàng, dùng cho mục đích bảo hiểm hàng hóa

Model của requests và group_requests

Key	Type	Yêu cầu	Mô tả
_id	String	Có	ID của dịch vụ kèm theo (ex: SGN-BIKE-TIP (requests) hoặc TIP (group_requests))
num	Int	Không	Số lượng, chỉ áp dụng với các dịch vụ kèm theo có Group ID là PER_UNIT
tier_code	String	Không	Mức cồng kềnh, chỉ áp dụng với các dịch vụ kèm theo có Group ID là BULKY

Model của items

Key	Type	Yêu cầu	Mô tả
_id	Int	Có	ID của hàng hóa
name	String	Có	Tên hàng hóa
price	Int	Có	Giá hàng hóa
num	Int	Có	Tổng số lượng hàng hóa

Model của package_detail

Key	Type	Yêu cầu	Mô tả
weight	Float	Có	Khối lượng gói hàng (kg)
length	Float	Không	Chiều dài gói hàng (m)
width	Float	Không	Chiều rộng gói hàng (m)
height	Float	Không	Chiều cao gói hàng (m)
description	String	Không	Mô tả về loại hàng hóa

Lưu ý

lat và lng là không bắt buộc nhưng trường address trong parameters cần phải đầy đủ thông tin và theo đúng định dạng như bên dưới:

[Số nhà] [Tên đường], [Phường/Xã], [Quận/Huyện], [Tỉnh/Thành], Việt Nam

Ví dụ: 117 Hùng Vương, Phường 4, Quận 5, Thành phố Hồ Chí Minh, Việt Nam
hoặc 117 Hùng Vương, Phường 4, Quận 5, Hồ Chí Minh

Các yêu cầu về địa chỉ khi truyền sang Ahamove

Địa chỉ rõ ràng, các phần thông tin cách nhau bởi dấu phẩy
Địa chỉ có thể tìm được trên google map (Có thể dùng luôn google plus code)
Địa chỉ không trùng lập các thông tin Phường/Quận/Tỉnh (Đối với các Đối tác cho Khách hàng chọn địa chỉ theo dạng dropdown)

Một số dạng Địa chỉ không hợp lệ :

658 võ văn kiệt p1 Quận 5 Hồ Chí Minh
58 Nghĩa Thục - Phường 5 - Quận 5 - Hồ Chí Minh - Việt Nam
22 Bùi Hữu Nghĩa
60/62 chiêu anh các
930 vo văn Kiệt p5q5
Có ji e gởi đia chỉ 835/17c trần hung dao p1 q5 tphcm giúp c nha, Phường 01, Quận 5, Thành phố Hồ Chí Minh
54 Bạch Vân (Nhà màu xanh cuối hẻm, gọi số 0908999999), Phường 5, Quận 5, TP Hồ Chí Minh
189 Trần Tuấn Khải F.5 Q.5 Ngay ngã 3 Trần Hưng Đạo
địa chỉ: 53 Huỳnh Mẫn Đạt phường 5 Quận 5 TP.HCM ĐT: 0912123456
14/20 .an binh p5q5
155 Trần Tuần Khải, p5, q5
Số 1 bạch Vân phường 5 quận 5 TPHCM
đc hẻm 93/107/16 đường bạch vân p5 q5
112 An Bình P5, Quận 5, HCM
1025, Phường 5, Quận 5

Response

JSON response example:

{
	"order_id": "24ABCD",
	"status": "ASSIGNING",
	"shared_link": "https://expressstg.ahamove.com/s/241018N83HHH",
	"order": {
		// order detail
		"_id": "24ABCD",
		"currency": "VND",
		"user_main_account": 0,
		"user_bonus_account": 0,
		"total_pay": 33000,
		"distance": 1.02,
		"duration": 268,
		"distance_fee": 23000,
		"request_fee": 10000,
		"stop_fee": 0,
		"vat_fee": 0,
		"discount": 0,
		"path": [
			{
				"lat": 10.76975346,
				"lng": 106.6636615,
				"address": "7/28 Thành Thái, Phường 14, Quận 10, Thành phố Hồ Chí Minh",
				"short_address": "Thành Thái, Quận 10",
				"name": "Lan",
				"mobile": "84944309348",
				"remarks": "Đến nơi lấy hàng đọc mã đơn để nhận hàng"
			},
			{
				"lat": 10.8018493,
				"lng": 106.714466,
				"address": "475A Điện Biên Phủ, Phường 25, Bình Thạnh, Thành phố Hồ Chí Minh",
				"short_address": "Đại Học Hutech, Quận Bình Thạnh, Hồ Chí Minh",
				"name": "Anh",
				"mobile": "0912345678",
				"cod": 100000,
				"item_value": 250000,
				"tracking_number": "ABCD1234",
				"remarks": "Gọi điện trước khi giao. Giao hàng cẩn thận"
			}
    	],
		"requests": [
			{
				"_id": "SGN-BIKE-TIP",
				"num": 1
       		},
			{
				"_id": "SGN-BIKE-BULKY",
				"tier_code": "TIER_2"
			}
		],
		"items": [],
		"total_fee": 33000,
		"remarks": "Ghi chú đơn hàng",
		"app": "Ahamove",
		"service_id": "SGN-BIKE",
		"city_id": "SGN",
		"user_id": "84xxxxxxxxx",
		"user_name": "TEST CREATE AN ORDER",
		"user_imei": null,
		"create_time": 1565577713.2757928,
		"order_time": 1565577713.2757928,
		"index": 12,
		"status": "ASSIGNING",
		"partner": "TESTPARTNER",
		"polylines": "ukx`A}rfjS~CuDhHnGlBnA|DoEdFcB|BhBxBtDzBmA",
		"online_pay": 0,
		"notify_package_return": true,
		"uniform_user_feedback": 2,
		"pending_period": 100,
		"stoppoint_price": 0,
		"special_request_price": 10000,
		"vat": 0,
		"distance_price": 23000,
		"voucher_discount": 0,
		"subtotal_price": 33000,
		"total_price": 33000
		...
	}
}

Status-Code: 200 OK

Các lỗi thường gặp

Mã lỗi	Code	Mô tả
`400`	`BAD_REQUEST`	Yêu cầu tạo đơn chứa dữ liệu không hợp lệ
`400`	`MISSING_REQUIRED_INFO`	Thiếu các trường thông tin bắt buộc
`400`	`MISSING_PATH_INFO`	Path không đủ số lượng điểm giao tối thiểu
`401`	`NOT_AUTHORIZED`	Token không hợp lệ (Token hết hạn. Khi token mới được tạo thì token cũ sẽ bị hết hạn)
`404`	`SERVICE_NOT_FOUND`	Không tìm thấy dịch vụ
`404`	`REQUEST_NOT_FOUND`	Không tìm thấy dịch vụ kèm theo
`406`	`INVALID_MAX_DISTANCE`	Khoảng cách giao hàng không hợp lệ, lớn hơn khoảng cách cho phép của dịch vụ
`406`	`INVALID_MAX_COD`	COD lớn hơn hạn mức COD tối đa của dịch vụ hoặc lớn hơn hạn mức COD của người dùng
`406`	`NOT_ENOUGH_CREDIT`	Tài khoản thanh toán không đủ tiền hoặc không phải tài khoản công nợ
`406`	`INVALID_MAX_STOP_POINT`	Số lượng điểm giao vượt quá số điểm giao tối đa của dịch vụ
`406`	`INVALID_MIN_STOP_POINT`	Số lượng điểm giao chưa đạt số điểm giao tối thiểu của dịch vụ
`406`	`SERVICE_NOT_VALID_AT_PICKUP`	Dịch vụ không hỗ trợ ở điểm lấy hàng
`406`	`INVALID_PICKUP_AREA`	Dịch vụ không hỗ trợ ở khu vực lấy hàng
`406`	`INVALID_DELIVERY_AREA`	Dịch vụ không hỗ trợ ở khu vực giao hàng
`406`	`INVALID_SERVICE_HOUR`	Thời điểm tạo đơn không nằm trong khung giờ hoạt động của dịch vụ
`406`	`INVALID_FUTURE_ORDER_TIME`	Thời gian hẹn giờ tạo đơn không phù hợp (vd: thời gian hẹn giờ tạo đơn lớn hơn một tháng kể từ thời điểm hiện tại)
`409`	`DUPLICATE_TRACKING_NUMBER`	Trùng mã tracking number (nếu partner có cấu hình chặn trùng mã tracking number khi tạo đơn)
`500`	`INTERNAL_SERVER_ERROR`	Hệ thống của chúng tôi có lỗi xảy ra. Xin thử lại sau - Không thể định vị được khu vực tỉnh thành của địa chỉ - Dữ liệu truyền lên chứa trường thông tin không đúng loại dữ liệu
`503`	`SERVICE_UNAVAILABLE`	Chúng tôi tạm thời đang không hoạt động để bảo trì. Xin vui lòng thử lại sau

Tạo đơn dùng service_id và requests​

Tạo đơn dùng group_service_id và group_requests​

HTTP Request​

Headers​

Body​

Parameters​

Cách để lấy group_service_id và group_requests​

Cấu trúc của mã dịch vụ:​

Cấu trúc của mã dịch vụ kèm theo:​

Path​

Model của requests và group_requests​

Model của items​

Model của package_detail​

Lưu ý​

Các yêu cầu về địa chỉ khi truyền sang Ahamove​

Một số dạng Địa chỉ không hợp lệ :​

Response​

Các lỗi thường gặp​