Webhook

Luồng webhook được sử dụng để đồng bộ trạng thái mã vận đơn OMS tới hệ thống của đối tác tích hợp APIs.

info

Giả sử đơn hàng mã "614727610891980800" (mã trên hệ thống khách hàng là "1234567") được cập nhật ""đã giao hàng thành công".

Giả sử callback link của đối tác là

https://partner.example.com/updateShipment?hash=XXX

Data OMS sẽ gửi tới callback link của đối tác theo nội dung

{
    "partner_order_id" : "1234567",
    "oms_order_id": "614727610891980800",
    "status": "ORDER_CREATED",
    "sub_status": "ORDER_CREATED",  
    "action_time": "2016-11-02T12:18:39+07:00",
    "pick_time": {
      "date": "2025-07-30",
      "work_shift": 1
    },
    "deliver_time": {
      "date": "2025-08-01",
      "work_shift": 1
    },
    "shipment_info": {
        "partner_code": "ghtk"
    }
}

Request gửi từ máy chủ của OMS gọi sang hệ thống của đối tác

CURL

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'label_id=614727610891980800&partner_order_id=1234567&action_time=2016-11-02T12:18:39+07:00&status_id=5' \
  "https://partner.example.com/updateShipment?hash=XXX"

info

OMS sử dụng response HTTP Status code để xác định là có gửi cập nhật cho đối tác thành công hay không.

Nếu nhận được response code 200, OMS ghi nhận đã cập nhật thành công cho đối tác

HTTP/1.1 200 OK

HTTP/1.1 500 Internal Server Error

Danh sách tham số cung cấp cho đối tác

Tham số	Kiểu dữ liệu	Mô tả
oms_order_id	String	Mã đơn hàng của hệ thống OMS
partner_order_id	String	Mã đơn hàng thuộc hệ thống của đối tác
status	String	Mã trạng thái chính đơn hàng
sub_status	String	Mã trạng thái phụ đơn hàng
action_time	String	ISO 8601 - Thời gian cập nhật trạng thái đơn hàng
pick_time	Object	Thông tin hẹn lấy
deliver_time	Object	Thông tin hẹn giao
shipment_info	Object	Thông tin đơn vị vận chuyển

Danh sách tham số shipment_info - Thông tin đơn vị vận chuyển

Tham số	Kiểu dữ liệu	Mô tả
partner_code	String	Code đơn vị vận chuyển tương ứng (Giá trị: ghtk/ahamove)

Danh sách tham số pick_time - Thông tin hẹn lấy

Tham số	Kiểu dữ liệu	Mô tả
date	String	Ngày hẹn lấy
work_shift	Integer	Ca hẹn lấy (1/2/3 - Sáng/Chiều/Tối

Danh sách tham số deliver_time - Thông tin hẹn giao

Tham số	Kiểu dữ liệu	Mô tả
date	String	Ngày hẹn giao
work_shift	Integer	Ca hẹn giao (1/2/3 - Sáng/Chiều/Tối

Trạng thái đơn hàng tiêu chuẩn

Các trạng thái chuyển của đơn hàng tiêu chuẩn trên hệ thống OMS.

STT	Main_status	CODE	Sub_status	CODE	Giải thích	Ghi chú
1	Đã tạo đơn	ORDER_CREATED	Đã tạo đơn	ORDER_CREATED	Hệ thống ghi nhận đơn hàng mới
2	Đã sẵn sàng bàn giao cho đơn vị vận chuyển	READY_TO_BE_SHIPPED	Đơn hàng sẵn sàng bàn giao ĐVVC	READY_TO_BE_SHIPPED	Đơn hàng đã được đóng gói/Chờ lấy hàng
			Đã tạo đơn cho ĐVVC	3PL_ASSIGNED	Đơn hàng đã được đẩy sang ĐVVC, có thông tin mã vận đơn
			Bắt đầu lấy hàng	PICKUP_START	Shipper bắt đầu lấy hàng
			Lấy hàng thành công	PICKUP_SUCCESS	Shipper đã lấy hàng từ shop
			Lấy hàng thất bại	PICKUP_FAILED	Shipper không lấy được hàng	Có lý do đi kèm, bộ lý do theo GHTK
3	Trung chuyển	IN_TRANSIT	Nhập kho trung chuyển	HUB_INBOUND	Đơn hàng đã nhập kho trung chuyển
			Xuất kho trung chuyển	HUB_OUTBOUND	Đơn hàng đã xuất kho trung chuyển
4	Đang giao hàng	DELIVERING	Nhập kho đích	STATION_IN	Đơn hàng được nhập đến kho giao hàng
			Đang giao hàng lần 1	DELIVERING	Đơn hàng đang được vận chuyển đến khách hàng
			Delay giao hàng	1ST_ATTEMPT_FAILED	Đơn hàng delay giao lần 1
			Đang giao hàng lần 2/3	RE_DELIVERING	Đơn hàng được xuất giao lần 2/3
			Delay giao lần 2/3	RE_ATTEMPT_FAILED	Đơn hàng delay giao
5	Giao hàng thành công	DELIVERED	Giao hàng thành công	DELIVERED	Khách hàng đã nhận hàng	Hoàn tất giao dịch
6	Không giao được hàng	DELIVERED_FAILED	Không giao được hàng	DELIVERED_FAILED	Giao hàng thất bại, đang xử lý lại	Có lý do đi kèm
7	Đang trả hàng	RETURN	Chờ trả hàng	AWAITING_RETURN	Đơn hàng chờ hoàn hàng/trả hàng. Hoặc đơn hàng giao đủ 3 ca không giao được
			Đang trả hàng	RETURNING	Đơn hàng đang trả hàng
			Delay trả hàng	RETURN_DELAYED	Đơn hàng delay trả hàng
8	Trả hàng thành công	RETURNED	Trả hàng thành công	RETURNED	Hệ thống/ cửa hàng đã nhận lại sản phẩm
9	Không trả được hàng	RETURNED_FAILED	Không trả được hàng	RETURNED_FAILED	Đơn hàng không trả được
10	Đơn hàng bị hủy	CANCELLED	Đơn hàng bị hủy	CANCELLED	Đơn hàng bị hủy bởi KH/hệ thống/shop	Có lý do đi kèm
11	Sự vụ	EXCEPTION	Đơn hàng bị vỡ hỏng	PKG_DAMAGED	Đơn hàng bị vỡ hỏng trong quá trình vận chuyển
			Đơn hàng bị thất lạc	PKG_LOST	Đơn hàng bị thất lạc trong quá trình vận chuyển

Trạng thái đơn hàng hỏa tốc/nhanh

Các trạng thái chuyển của đơn hàng hỏa tốc/nhanh trên hệ thống OMS.

STT	Main_status	Code	Sub_status	Code	Giải thích	Ghi chú
1	Đã tạo đơn	ORDER_CREATED	Đã tạo đơn	ORDER_CREATED	Hệ thống ghi nhận đơn hàng mới
2	Đã sẵn sàng bàn giao cho ĐVVC	READY_TO_BE_SHIPPED	Đơn hàng đã sẵn sàng bàn giao cho ĐVVC	READY_TO_BE_SHIPPED	Đơn hàng đã được xác nhận, người bán đang đóng gói/chuẩn bị
			Đang tìm tài xế	ASSIGNING_DRIVER	Chờ ĐVVC tìm tài xế. Mỗi lần tìm tài xế tương đương 1 MVD mới
			Không tìm thấy tài xế	ASSIGN_FAILED	Sau X thời gian không tìm thấy tài xế của 1 ĐVVC
3	Đang lấy hàng	PICK_UP	Đã tìm thấy tài xế. Biển số xe: XXX, Tên: YYY, SĐT: ZZZ	DRIVER_ASSIGNED	ĐVVC đã tìm thấy tài xế cho đơn hàng, đang lấy hàng
			Lấy hàng thất bại: Không liên hệ được shop	PICKUP_FAILED	Shipper ko lấy được hàng
4	Đang giao hàng	DELIVERING	Lấy hàng thành công, đang giao hàng	DELIVERING	Shipper đã xác nhận lấy hàng thành công, đi giao hàng
5	Giao hàng thành công	DELIVERED	Giao hàng thành công	DELIVERED	ĐVVC xác nhận đã giao hàng
6	Không giao được hàng	DELIVERED_FAILED	Không giao được hàng	DELIVERED_FAILED	Giao hàng không thành công	Có lý do đi kèm
7	Hoàn hàng	RETURN_INITIATED	Đang trả hàng	RETURNING	Đơn hàng đang trả hàng
8	Trả hàng thành công	RETURNED_SUCCESS	Trả hàng thành công	RETURNED	Hệ thống/cửa hàng đã nhận lại sản phẩm
9	Không trả được hàng	RETURN_FAILED	Không trả được hàng	RETURN_FAILED	Đơn hàng trả hàng thất bại
10	Đơn hàng bị hủy	CANCELLED	Đơn hàng bị hủy	CANCELLED	Đơn hàng bị hủy bởi KH/hệ thống/shop	Có lý do đi kèm
11	Sự vụ	EXCEPTION	Đơn hàng bị vỡ hỏng	PKG_DAMAGED	Đơn hàng bị vỡ hỏng trong quá trình vận chuyển
			Đơn hàng bị thất lạc	PKG_LOST	Đơn hàng bị thất lạc trong quá trình vận chuyển