Thêm đơn hàng

/api/order/add: Tính năng này dùng để gửi thông tin đơn hàng từ website của bạn sang Nhanh.vn. Khi khách hàng đặt hàng trên website của bạn, sau khi lưu thông tin đơn hàng vào cơ sở dữ liệu, website của bạn gửi thông tin đơn hàng sang Nhanh.vn, sau đó chủ gian hàng có thể xử lý toàn bộ các bước từ việc xác nhận đơn hàng, nhặt hàng và đóng gói, gửi đơn hàng sang hãng vận chuyển, đối soát tình trạng thanh toán (tiền thu hộ) các đơn hàng với hãng vận chuyển bên trong hệ thống Nhanh.vn.
Đơn hàng tạo từ API nếu có gắn kho hàng (depotId) sẽ áp dụng các logic tính số Tạm giữ và Đang chuyển như đơn tạo từ trang quản trị. VD 1 sản phẩm trên hệ thống đang tồn 10, tạm giữ 1, sau khi API có bắn về thêm 1 đơn hàng trạng thái Mới, số lượng = 1, có gắn depotId, thì hệ thống sẽ tự động tính toán lại số Tạm giữ = 2.
Mỗi khi trạng thái đơn hàng có sự thay đổi, website của bạn sẽ nhận được 1 webhooks cập nhật trạng thái đơn hàng từ Nhanh.vn.

Request

Xem common request params.
Xem /api/order/add - Postman sample
Các key của mảng data array dùng để tạo data json string:
- Chú ý: Nhanh.vn hỗ trợ 2 hình thức kết nối vận chuyển, có sự khác nhau về request params:
  - Dùng luôn bảng cước ưu đãi của Nhanh.vn
    Để tính phí vận chuyển cho đơn hàng: Dùng /api/shipping/fee
    request params gửi đơn hàng sang Nhanh: bạn set sendCarrierType = 1, set đúng carrierId và carrierServiceId muốn dùng (đọc thêm ở bảng bên dưới).
  - Dùng bảng cước riêng shop tự ký hợp đồng với hãng vận chuyển
    Để tính phí vận chuyển cho đơn hàng: Dùng /api/shipping/feeselfconnect
    request params gửi đơn hàng sang Nhanh: bạn set sendCarrierType = 2, set đúng carrierAccountId, carrierShopId,và carrierServiceCode muốn dùng (đọc thêm ở bảng bên dưới).

Key	Type	Description
id	string(36) $^{{\color{red}*}}$	id đơn hàng trên website của bạn
depotId	int	id kho hàng trên Nhanh.vn (Lấy từ /api/store/depot)
type	string	Loại đơn hàng, giá trị có thể là: “Shipping” (Chuyển hàng) hoặc “Shopping” (Khách tới mua tại cửa hàng) “PreOrder”(Khách đặt hàng trước). Giá trị mặc định là Shipping.
customerName	string(255) $^{{\color{red}*}}$	Tên người nhận hàng
customerMobile	string(255) $^{{\color{red}*}}$	Mobile của người nhận hàng. Hệ thống sẽ dựa vào số điện thoại để kiểm tra khách hàng đã tồn tại hay chưa, nếu chưa tồn tại, hệ thống sẽ tự động tạo khách hàng.
customerEmail	string(255)	Địa chỉ email đặt hàng
customerAddress	string(255)	Địa chỉ người nhận hàng
customerCityName	string(255)	Tên thành phố của người nhận hàng (Lấy từ /api/shipping/location)
customerDistrictName	string(255)	Tên quận huyện của người nhận hàng (Lấy từ /api/shipping/location)
customerWardLocationName	string	Phường xã người nhận (Lấy từ /api/shipping/location)
moneyDiscount	double	Tiền chiết khấu
moneyTransfer	double	Số tiền khách chuyển khoản
moneyTransferAccountId	int	Tài khoản nhận tiền chuyển khoản
moneyDeposit	double	Số tiền khách đặt cọc
moneyDepositAccountId	int	Tài khoản nhận tiền đặt cọc
paymentMethod	string	Các giá trị có thể là: COD //Thanh toán tại nhà Store // Thanh toán tại cửa hàng Gateway // Thanh toán qua cổng thanh toán Online // thanh toán Online
paymentCode	string(255)	Mã giao dịch thanh toán
paymentGateway	string(255)	Tên cổng thanh toán
carrierId	int	id hãng vận chuyển (Lấy từ /api/shipping/fee) hoặc set = 12 nếu muốn chọn Tự vận chuyển
carrierServiceId	int	dịch vụ vận chuyển (Lấy từ /api/shipping/fee)
customerShipFee	int	Phí ship báo khách (Bạn có thể điền 0 nếu báo với khách hàng là miễn phí vận chuyển, hoặc điền các giá trị cố định như 20K, 30K, hoặc lấy theo tổng Phí vận chuyển shipFee + phí thu tiền hộ codFee + phí bảo hiểm declaredFee lấy từ /api/shipping/fee) )
deliveryDate	date	Ngày giao hàng của đơn hàng này, định dạng yyyy-mm-dd
status	string	Trạng thái của đơn hàng: New (Mới) hoặc Confirmed (Đã xác nhận).
description	string(255)	Ghi chú của khách hàng về đơn hàng này
privateDescription	string(255)	Ghi chú của chăm sóc khách hàng (Nội bộ)
trafficSource	string	Nguồn truy cập đơn hàng, bạn có thể đánh dấu xem đơn hàng đến từ nguồn nào qua referrer hoặc marketing campaign (utm_source, utm_medium, utm_campaign) và gửi kèm thông tin này theo đơn hàng để xem báo cáo thống kê theo nguồn truy cập ở bên Nhanh.vn
productList	array	Xem bảng dữ liệu bên dưới. Danh sách sản phẩm của đơn hàng là không bắt buộc, để hỗ trợ cả các đơn đồng bộ từ landing về, CSKH vẫn có số điện thoại để gọi điện tư vấn.
couponCode	string	Mã coupon
allowTest	int	1 - Cho xem hàng, không cho thử 2 - Cho phép thử 3 - Không cho xem hàng 4 - Cho xem, không lấy thu ship
saleId	int	Nhân viên bán hàng
autoSend	int	Biến đánh dấu gửi luôn đơn hàng sang hãng vận chuyển (Dùng trong tình huống bạn có hệ thống xác nhận đơn hàng từ trước, chỉ dùng Nhanh để hỗ trợ vận chuyển). Set value = 1: Gửi luôn đơn hàng sang hãng vận chuyển. Nếu gửi thành công hệ thống sẽ trả về mã vận đơn carrierCode. Chú ý khi có tham số này, hệ thống sẽ phải kết nối sang hãng vận chuyển, nên thời gian phản hồi có thể bị chậm hơn bình thường tùy thuộc vào phản hồi của các hãng vận chuyển.
sendCarrierType	int	Biến đánh dấu gửi đơn dùng bảng giá vận chuyển: 1 = Dùng bảng giá của Nhanh.vn, 2 = Dùng bảng giá kết nối tài khoản riêng của doanh nghiệp
carrierAccountId	int	ID tài khoản kết nối, required khi sendCarrierType = 2, Lấy từ /api/shipping/feeselfconnect.
carrierShopId	int	ID cửa hàng trên hệ thống hãng vận chuyển (Lấy từ /api/shipping/feeselfconnect nếu có).
carrierServiceCode	string	Mã dịch vụ hãng vận chuyển, required khi sendCarrierType = 2, Lấy từ /api/shipping/feeselfconnect.
utmCampaign	string	param khi gắn link đo đếm marketing utm_campaign
utmSource	string	param khi gắn link đo đếm marketing utm_source
utmMedium	string	param khi gắn link đo đếm marketing utm_medium
affiliate	array	Mã giới thiệu cho đơn hàng, xem Affiliate bên dưới
usedPoints	int	Tiêu điểm khách hàng
isPartDelivery	int	1 = Đơn hàng có giao hàng một phần, giá trị mặc định null

Key

Type

Description

string(36) $^{{\color{red}*}}$

id đơn hàng trên website của bạn

depotId

int

id kho hàng trên Nhanh.vn (Lấy từ /api/store/depot)

type

string

Loại đơn hàng, giá trị có thể là: “Shipping” (Chuyển hàng) hoặc “Shopping” (Khách tới mua tại cửa hàng) “PreOrder”(Khách đặt hàng trước). Giá trị mặc định là Shipping.

customerName

string(255) $^{{\color{red}*}}$

Tên người nhận hàng

customerMobile

string(255) $^{{\color{red}*}}$

Mobile của người nhận hàng. Hệ thống sẽ dựa vào số điện thoại để kiểm tra khách hàng đã tồn tại hay chưa, nếu chưa tồn tại, hệ thống sẽ tự động tạo khách hàng.

customerEmail

string(255)

Địa chỉ email đặt hàng

customerAddress

string(255)

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

customerCityName

string(255)

Tên thành phố của người nhận hàng (Lấy từ /api/shipping/location)

customerDistrictName

string(255)

Tên quận huyện của người nhận hàng (Lấy từ /api/shipping/location)

customerWardLocationName

string

Phường xã người nhận (Lấy từ /api/shipping/location)

moneyDiscount

double

Tiền chiết khấu

moneyTransfer

double

Số tiền khách chuyển khoản

moneyTransferAccountId

int

Tài khoản nhận tiền chuyển khoản

moneyDeposit

double

Số tiền khách đặt cọc

moneyDepositAccountId

int

Tài khoản nhận tiền đặt cọc

paymentMethod

string

Các giá trị có thể là: COD //Thanh toán tại nhà Store // Thanh toán tại cửa hàng Gateway // Thanh toán qua cổng thanh toán Online // thanh toán Online

paymentCode

string(255)

Mã giao dịch thanh toán

paymentGateway

string(255)

Tên cổng thanh toán

carrierId

int

id hãng vận chuyển (Lấy từ /api/shipping/fee) hoặc set = 12 nếu muốn chọn Tự vận chuyển

carrierServiceId

int

dịch vụ vận chuyển (Lấy từ /api/shipping/fee)

customerShipFee

int

Phí ship báo khách (Bạn có thể điền 0 nếu báo với khách hàng là miễn phí vận chuyển, hoặc điền các giá trị cố định như 20K, 30K, hoặc lấy theo tổng Phí vận chuyển shipFee + phí thu tiền hộ codFee + phí bảo hiểm declaredFee lấy từ /api/shipping/fee) )

deliveryDate

date

Ngày giao hàng của đơn hàng này, định dạng yyyy-mm-dd

status

string

Trạng thái của đơn hàng: New (Mới) hoặc Confirmed (Đã xác nhận).

description

string(255)

Ghi chú của khách hàng về đơn hàng này

privateDescription

string(255)

Ghi chú của chăm sóc khách hàng (Nội bộ)

trafficSource

string

Nguồn truy cập đơn hàng, bạn có thể đánh dấu xem đơn hàng đến từ nguồn nào qua referrer hoặc marketing campaign (utm_source, utm_medium, utm_campaign) và gửi kèm thông tin này theo đơn hàng để xem báo cáo thống kê theo nguồn truy cập ở bên Nhanh.vn

productList

array

Xem bảng dữ liệu bên dưới. Danh sách sản phẩm của đơn hàng là không bắt buộc, để hỗ trợ cả các đơn đồng bộ từ landing về, CSKH vẫn có số điện thoại để gọi điện tư vấn.

couponCode

string

Mã coupon

allowTest

int

1 - Cho xem hàng, không cho thử 2 - Cho phép thử 3 - Không cho xem hàng 4 - Cho xem, không lấy thu ship

saleId

int

Nhân viên bán hàng

autoSend

int

Biến đánh dấu gửi luôn đơn hàng sang hãng vận chuyển (Dùng trong tình huống bạn có hệ thống xác nhận đơn hàng từ trước, chỉ dùng Nhanh để hỗ trợ vận chuyển). Set value = 1: Gửi luôn đơn hàng sang hãng vận chuyển. Nếu gửi thành công hệ thống sẽ trả về mã vận đơn carrierCode. Chú ý khi có tham số này, hệ thống sẽ phải kết nối sang hãng vận chuyển, nên thời gian phản hồi có thể bị chậm hơn bình thường tùy thuộc vào phản hồi của các hãng vận chuyển.

sendCarrierType

int

Biến đánh dấu gửi đơn dùng bảng giá vận chuyển: 1 = Dùng bảng giá của Nhanh.vn, 2 = Dùng bảng giá kết nối tài khoản riêng của doanh nghiệp

carrierAccountId

int

ID tài khoản kết nối, required khi sendCarrierType = 2, Lấy từ /api/shipping/feeselfconnect.

carrierShopId

int

ID cửa hàng trên hệ thống hãng vận chuyển (Lấy từ /api/shipping/feeselfconnect nếu có).

carrierServiceCode

string

Mã dịch vụ hãng vận chuyển, required khi sendCarrierType = 2, Lấy từ /api/shipping/feeselfconnect.

utmCampaign

string

param khi gắn link đo đếm marketing utm_campaign

utmSource

string

param khi gắn link đo đếm marketing utm_source

utmMedium

string

param khi gắn link đo đếm marketing utm_medium

affiliate

array

Mã giới thiệu cho đơn hàng, xem Affiliate bên dưới

usedPoints

int

Tiêu điểm khách hàng

isPartDelivery

int

1 = Đơn hàng có giao hàng một phần, giá trị mặc định null

Product List

Các thuộc tính của 1 sản phẩm trong productList bao gồm:

Key	Type	Description
id	string(20) $^{{\color{red}*}}$	id sản phẩm bên website của bạn
idNhanh	bigint(20)	id sản phẩm bên Nhanh.vn (tham số này là bắt buộc nếu sản phẩm được đồng bộ từ Nhanh.vn sang website của bạn)
quantity	int or double $^{{\color{red}*}}$	số lượng đặt hàng
name	string(255) $^{{\color{red}*}}$	Bắt buộc để thêm sản phẩm mới trong tình huống sản phẩm chưa tồn tại (giúp cho việc đồng bộ đơn hàng không bị gián đoạn nếu sản phẩm chưa được đồng bộ trước đó)
code	string(255)	Mã sản phẩm
imei	string(255)	Số IMEI sản phẩm
type	string(255)	Loại sản phẩm (Product, Voucher, IMEI)
price	int $^{{\color{red}*}}$	Giá của sản phẩm. Bắt buộc để thêm sản phẩm mới trong tình huống sản phẩm chưa tồn tại
weight	int	Khối lượng sản phẩm
importPrice	int	Giá nhập của sản phẩm
description	string	Mô tả riêng của từng sản phẩm trong đơn hàng
gifts	Array	Quà tặng của sản phẩm trong đơn hàng [ 0 => [ Id => id sản phẩm trên website , productStoreId => id sản phẩm trên Nhanh , quantity => Số lượng, value => Giá sản phẩm quà tặng ], 1 => [ Id => id sản phẩm trên website, productStoreId => id sản phẩm trên Nhanh, quantity => Số lượng, value => Giá sản phẩm quà tặng ] ... ]

Key

Type

Description

string(20) $^{{\color{red}*}}$

id sản phẩm bên website của bạn

idNhanh

bigint(20)

id sản phẩm bên Nhanh.vn (tham số này là bắt buộc nếu sản phẩm được đồng bộ từ Nhanh.vn sang website của bạn)

quantity

int or double $^{{\color{red}*}}$

số lượng đặt hàng

name

string(255) $^{{\color{red}*}}$

Bắt buộc để thêm sản phẩm mới trong tình huống sản phẩm chưa tồn tại (giúp cho việc đồng bộ đơn hàng không bị gián đoạn nếu sản phẩm chưa được đồng bộ trước đó)

code

string(255)

Mã sản phẩm

imei

string(255)

Số IMEI sản phẩm

type

string(255)

Loại sản phẩm (Product, Voucher, IMEI)

price

int $^{{\color{red}*}}$

Giá của sản phẩm. Bắt buộc để thêm sản phẩm mới trong tình huống sản phẩm chưa tồn tại

weight

int

Khối lượng sản phẩm

importPrice

int

Giá nhập của sản phẩm

description

string

Mô tả riêng của từng sản phẩm trong đơn hàng

gifts

Array

Quà tặng của sản phẩm trong đơn hàng [ 0 => [ Id => id sản phẩm trên website , productStoreId => id sản phẩm trên Nhanh , quantity => Số lượng, value => Giá sản phẩm quà tặng ], 1 => [ Id => id sản phẩm trên website, productStoreId => id sản phẩm trên Nhanh, quantity => Số lượng, value => Giá sản phẩm quà tặng ] ... ]

Affiliate

[
    "code" =>  string, // mã giới thiệu
    "discount" => double, // Tiền chiết khấu cho đơn hàng theo mã affiliate
    "bonus" => double // Tiền hoa hồng nhận được theo mã affiliate
]

Response

{
    "code": 1, // 1 is success, 0 is error
    "messages": [ ], // error messages if code is 0
    "data": [
        "orderId": 125123098, // int ID đơn hàng trên Nhanh.vn
        // Các trường bên dưới chỉ có giá trị khi đơn hàng có dùng chức năng gửi sang hãng vận chuyển (autoSend=1)
        "shipFee": 20000, // int: Phí vận chuyển
        "codFee": 13000, // int: Phí thu tiền hộ
        "declaredFee": 10000, // int: Phí bảo hiểm (tùy theo giá trị đơn hàng và dịch vụ bạn lựa chọn sẽ có loại phí này)
        "carrierCode": string // Mã vận đơn, Nếu gửi đơn hàng thành công sang hãng vận chuyển hệ thống sẽ trả về carrierCode (mã vận đơn)
        "trackingUrl": string // Lịch trình đơn hàng
    ]
}

PreviousDanh sách đơn hàng NextCập nhật đơn hàng

Last updated 1 month ago