Nhanh.vn Open API
Trang chủHướng dẫn sử dụngApps
Search…
v2
Giới thiệu
Change log
Product
Danh sách sản phẩm
Thêm sản phẩm
Chi tiết sản phẩm
Danh mục sản phẩm
Danh mục nội bộ
Quà tặng sản phẩm
Danh sách IMEI
Tra cứu IMEI bán ra theo ngày
Lịch sử IMEI
Order
Danh sách đơn hàng
Thêm đơn hàng
Cập nhật đơn hàng
Gửi khiếu nại đơn hàng
Lịch sử đơn hàng
Shipping
Hãng vận chuyển
Thành phố, quận huyện
Tính phí vận chuyển
Bill
Phiếu xuất nhập kho
Sản phẩm xuất nhập kho
Sản phẩm xuất nhập kho nháp
Customer
Danh sách khách hàng
Thêm khách hàng
Website
Tin tức
Danh mục tin tức
Thêm subscriber
Thêm liên hệ
Supplier
Nhà cung cấp
Promotion
Danh sách coupon
Store
Kho hàng
Nhân viên
Accounting
Bút toán
Webhooks
Giới thiệu
Đơn hàng
Sản phẩm
Tồn kho
Powered By GitBook
Giới thiệu

  • Nhanh API cung cấp các giải pháp để đồng bộ dữ liệu sản phẩm, đơn hàng, khách hàng, tồn kho... giữa Nhanh.vn và các hệ thống khác. Các giải pháp này phù hợp cho cả các website bình thường (website của 1 cá nhân, công ty) và cả các sàn thương mại điện tử có nhiều gian hàng.
  • Phiên bản 2.0 sử dụng access token và cơ chế cấp quyền linh hoạt, giúp người dùng dễ dàng lựa chọn dữ liệu cho phép ứng dụng được truy cập (thay vì được truy cập toàn bộ dữ liệu nếu dùng bản 1.0). Bản 2.0 cũng nâng cấp và bổ sung thêm nhiều webhooks mới.
  • Xem các thay đổi và cách nâng cấp từ bản 1.0 lên 2.0.

  • Để bắt đầu sử dụng Nhanh API, bạn cần đăng kí tài khoản developer và tạo ứng dụng tại đây.
    • Chú ý: tài khoản developer chỉ dùng để quản trị ứng dụng trên open.nhanh.vn, không yêu cầu phải có quyền quản trị trên Nhanh.vn, tài khoản cấp quyền cho ứng dụng mới cần có quyền trên Nhanh.vn.
  • Ứng dụng của bạn có thể dùng được cho 1 hoặc nhiều doanh nghiệp ở trên Nhanh.vn, khi người dùng (VD chủ doanh nghiệp) cấp quyền cho ứng dụng của bạn, Nhanh API sẽ tạo ra 1 access token gắn với doanh nghiệp và appId của bạn, kèm theo các permissions (quyền được thao tác với dữ liệu nào) do người dùng chọn ở bước đăng nhập cấp quyền cho app.
Tạo ứng dụng

Sơ đồ 3 bước để lấy access token
  • Bước 1: Ứng dụng của bạn cần chuyển tới trang đăng nhập của Nhanh.vn https://nhanh.vn/oauth?appId={YOUR_APPID}&returnLink={YOUR_RETURN_LINK}
    Chú ý: returnLink phải là 1 tên miền chạy https và nằm trong danh sách Redirect URL của ứng dụng.
Param
Type
Description
appId
int (required)
ID app
returnLink
string (required)
Sau khi người dùng đăng nhập và cấp quyền, Nhanh.vn sẽ redirect về URL này, kèm GET param accessCode. Chú ý returnLink bắt buộc chạy https, và phải được đăng ký trên app của bạn​
  • Bước 2: Người dùng sẽ đăng nhập và chọn các quyền được cấp cho ứng dụng.
Chọn quyền
  • Các quyền của token sẽ tương ứng với các quyền được thao tác trên Nhanh.vn của tài khoản đang lấy token. VD bạn dùng tài khoản Giám đốc sẽ có thể chọn toàn bộ quyền, bạn dùng tài khoản nhân viên chỉ đang được thao tác với "Danh sách sản phẩm", thì ở bước cấp quyền, tài khoản này cũng chỉ chọn được "Danh sách sản phẩm" và accessToken do tài khoản này tạo ra cũng sẽ chỉ gọi được "/api/product/search" mà không dùng được với các API khác.
  • Khi người dùng chọn "Đồng ý", Nhanh.vn sẽ redirect ngược lại về YOUR_RETURN_LINK kèm theo mã accessCode. VD bên trên nếu YOUR_RETURN_LINK = https://example.org/nhanh/auth thì Nhanh API sẽ redirect ngược lại về link https://example.org/nhanh/auth?accessCode=
  • Bước 3: App của bạn dùng accessCode này POST sang https://nhanh.vn/oauth/access_token để lấy được accessToken và các permissions được cấp cho accessToken này.
    • Request params:
Param
Type
Description
appId
int (required)
Your appId
accessCode
string (required)
accessCode sẽ hết hạn ngay sau khi lấy accessToken thành công hoặc sau 10 phút
secretKey
string (required)
Vào Danh sách app, click vào tên app, vào trang chi tiết để lấy secretKey của app
Dùng accessCode lấy accessToken
  • Response data:
Param
Type
Description
code
int
1 = success or 0 = failed
messages
array
is an array of error messages if code = 0
accessToken
string
Access token (random from 128 to 256 characters)
expiredDateTime
string
Hạn sử dụng token (Y-m-d H:i:s), VD: 2022-09-25 15:30:00, token sẽ có hạn 1 năm. Hệ thống của bạn cần có cơ chế cảnh báo người dùng để đăng nhập cấp quyền và lấy accessToken mới khi gần hết hạn accessToken cũ.
businessId
int
ID doanh nghiệp trên Nhanh.vn
depotIds
array
Các kho hàng được phép thao tác theo token. Nếu mảng rỗng thì sẽ được thao tác với toàn bộ các kho hàng.
permissions
string
Các quyền được phép thao tác: Sản phẩm, đơn hàng... Do user chọn ở bước cấp quyền

Chú ý: Bạn chỉ nên gọi nhanh.vn để lấy accessCode và accessToken, các API 2.0 về sau đều dùng open.nhanh.vn, không dùng nhanh.vn để tránh lỗi có thể xảy ra khi hệ thống bỏ hỗ trợ bản 1.0
  • Sau khi lấy được accessToken, bạn có thể bắt đầu gọi các API tới open.nhanh.vn, bản 2.0 sẽ dùng POST method, body form-data và các params bắt buộc như sau:
Param
Type
Description
version
string (required)
2.0
appId
int (required)
Your app ID
businessId
int (required)
ID doanh nghiệp trên Nhanh.vn. Lúc bạn lấy accessToken, Nhanh API có trả về businessId
accessToken
string (required)
Your access token
data
string (required)
json encoded string of data array. Dữ liệu data array bạn xem tại từng API cụ thể

  • Dùng Postman lấy danh sách sản phẩm có phân trang.
  • Khi bạn gửi request sang và nhận được response là invalid data: Lỗi này do data không phải là 1 chuỗi json string hợp lệ, thường do bạn không dùng các hàm json encode mà gõ thủ công gây thừa thiếu dấu, sai hoặc không encode các kí tự đặc biệt. Bạn có thể kiểm tra chuỗi data json string bằng cách: Vào https://jsonformatter.org hoặc https://jsonlint.com copy paste chuỗi của bạn vào textarea và click Validate
Postman: Lấy danh sách sản phẩm có phân trang
  • Lấy danh sách địa chỉ vận chuyển
Postman: Lấy danh sách địa chỉ vận chuyển

Bạn có thể dùng Postman điền các params và click vào Code Snippet trên Postman để xem cách tạo syntax cho các ngôn ngữ.
Postman generate code syntax
<?php
​
$appId => "_YOUR_APP_ID";
$accessToken => "_YOUR_ACCESS_TOKEN";
$businessId => "_YOUR_BUSINESS_ID"; // ID doanh nghiệp trên Nhanh.vn
​
$dataArray = array(
array(
"id" => "1741235",
"parentId" => null,
"code" => "SSGS2",
"barcode" => null,
"name" => "Samsung galaxy S2",
"image" => "http://example.com/images/samsung-galaxy-s-2.jpg",
"images" => array(),
"shippingWeight" => 370, // gram
"importPrice" => 12000000,
"price" => 13500000,
"vat" => 10, // 10%
"status" => "Active",
)
// product 2
// ...
);
​
$dataString = json_encode($dataArray);
​
$postArray = array(
"version" => "2.0",
"appId" => $appId,
"businessId" => $businessId,
"accessToken" => $accessToken,
"data" => $dataString
);
​
$curl = curl_init("https://open.nhanh.vn/api/product/add");
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArray);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
​
$curlResult = curl_exec($curl);
​
if(! curl_error($curl)) {
// success
$response = json_decode($curlResult);
} else {
// failed, cannot connect nhanh.vn
$response = new stdClass();
$response->code = 0;
$response->messages = array(curl_error($curl));
}
curl_close($curl);
​
if ($response->code == 1) {
// send product successfully
} else {
// failed, show error messages
if(isset($response->messages) && is_array($response->messages)) {
foreach($response->messages as $message) {
echo $message;
}
}
}

Value
Mô tả
New
Mới: Trạng thái này dùng để bán hàng ở cửa hàng offline
Active
Đang bán: Trạng thái này dùng để hiện bán ở trên website online (nếu dùng website của Nhanh.vn) và cửa hàng offline
Inactive
Ngừng bán: Trạng thái này để ẩn sản phẩm cả webiste online và cửa hàng offline, gõ gợi ý và mặc định ở danh sách sản phẩm cũng không hiện ra trừ khi lọc trạng thái Ngừng bán hoặc lọc chính xác id sản phẩm đó
OutOfStock
Hết hàng: Dùng để hiện trên website nhưng sẽ hiện thêm chữ Hết hàng và không cho đặt hàng, thường để website giữ link sản phẩm cũ, tránh lỗi 404

Các thuật ngữ của đơn hàng online
  • shippingWeight: bao gồm cân nặng thực tế của sản phẩm và toàn bộ cân nặng của các phụ kiện và vỏ hộp đóng gói đi kèm. Shipping weight được sử dụng để tính phí vận chuyển của đơn hàng. VD: Sản phẩm “Samsung Galaxy S2” nặng 300gr, Sản phẩm fullbox còn bao gồm 1 sạc (30gr), 1 tai nghe (10gr) and vỏ hộp đóng gói (30gr), vậy thì shippingWeight để tính phí vận chuyển sẽ là: 300 + 30 + 10 + 30 = 370 gr.
  • COD: Cash on delivery (Collect on delivery) là 1 loại giao dịch mà người mua hàng sẽ trả tiền khi nhận được hàng. Nếu người mua không đồng ý thanh toán khi nhận hàng, đơn hàng sẽ được chuyển trả lại cho người bán. Phí thu tiền hộ codFee tùy thuộc vào số tiền cần thu của đơn hàng.
  • shipFee: Phí vận chuyển, được tính dựa vào trọng lượng đơn hàng, địa chỉ gửi hàng và địa chỉ nhận hàng.
  • customerShipFee: Phí thu của khách, là mức phí mà website thông báo cho khách đặt hàng, thường sẽ lấy bằng shipFee + codFee. Tình huống website có chương trình miễn phí vận chuyển cho khách thì set customerShipFee = 0.
  • Order Status:
    Trạng thái đơn hàng
Status
Description
New
Đơn mới
Confirming
Đang xác nhận
CustomerConfirming
Chờ khách xác nhận
Confirmed
Đã xác nhận
Packing
Đang đóng gói
Packed
Đã đóng gói
ChangeDepot
Đổi kho xuất hàng
Pickup
Chờ thu gom
Shipping
Đang giao hàng
Success
Thành công
Failed
Thất bại
Canceled
Khách hủy
Aborted
Hệ thống hủy
CarrierCanceled
Hãng vận chuyển hủy đơn
SoldOut
Hết hàng
Returning
Đang chuyển hoàn
Returned
Đã chuyển hoàn
  • Order Reason
    Lý do theo trạng thái đơn hàng
Reason
Description
WrongProduct
Đặt nhầm sản phẩm
HighShipFee
Phí vận chuyển cao
NotTransfer
Không muốn chuyển khoản
Duplicated
Đơn trùng
CannotCall
Không gọi được khách
SoldOut
Hết hàng
WaitingTransfer
Chờ chuyển khoản
NotLikeProduct
Khách không thích sản phẩm
NotPleasureDeliverer
Khách không hài lòng về nhân viên vận chuyển
SlowShipping
Giao hàng chậm
Bought
Đã mua sản phẩm tại cửa hàng
CustomerNotAtHome
Khách đi vắng (sẽ giao hàng vào hôm khác)
WrongAddress
Sai địa chỉ người nhận
NotBuy
Khách không muốn mua nữa
CannotCallSender
Không liên hệ được với người gửi
SellerNotSellOnline
Người gửi không bán hàng Online / Ngoại tỉnh
SellerNotHandoverCarrier
Người gửi không bàn giao hàng cho hãng vận chuyển
SellerNotProcessOrder
Người gửi không xử lý đơn hàng
WrongPickupAddress
Sai địa chỉ kho lấy hàng
WrongPrice
Sai giá sản phẩm
SelfShipping
Người gửi tự vận chuyển
CarrierPickupLate
Hãng vận chuyển lấy hàng muộn
CarrierLostProduct
Hãng vận chuyển làm mất hàng
Other
Lý do khác

Các thuật ngữ về kho hàng
  • Phiếu XNK, Sản phẩm XNK có 2 loại (type) là phiếu nhập, phiếu xuất và nhiều kiểu (mode) XNK khác nhau:
  • Loại XNK:
Type (int)
Description
1
Loại nhập kho
2
Loại xuất kho
  • Kiểu XNK:
Mode (int)
Description
1
Kiểu giao hàng
2
Kiểu bán lẻ
3
Kiểu chuyển kho
4
Kiểu quà tặng
5
Kiểu nhà cung cấp
6
Kiểu bán sỉ
8
Kiểu kiểm kho
10
Kiểu khác

  • Nếu bạn có câu hỏi xin vui lòng gửi email tới [email protected] để được giải đáp (mô tả rõ doanh nghiệp cần hỗ trợ, tình huống thao tác với dữ liệu, các request params gọi sang Nhanh Open API).
  • Cách dùng postman để test và copy các request params xin vui lòng xem ảnh bên dưới:
    • Bước 1: Điền đầy đủ các request params bạn đang test.
    • Bước 2: Click nút Send và đợi Nhanh Open API phản hồi, chụp ảnh postman như hình bên dưới.
    • Bước 3: Click icon Code Snippet, chọn cURL và click icon Copy để copy hết request params.
Postman copy request params
Next
Change log
Last modified 15d ago
Copy link
On this page
Giới thiệu Nhanh.vn
Giới thiệu Nhanh.vn API 2.0
Khởi tạo ứng dụng
Lấy access token
Request params
Postman Sample
Code Sample
Thuật ngữ
Trạng thái sản phẩm
Order
Inventory
Hỗ trợ kỹ thuật