Giới thiệu

Search…
Giới thiệu
Giới thiệu Nhanh.vn
​Nhanh.vn là giải pháp quản lý bán hàng trên nền tảng điện toán đám mây, đồng bộ dữ liệu với website, dịch vụ vận chuyển, giúp doanh nghiệp quản lý toàn bộ quy trình bán hàng, chăm sóc khách hàng, tăng doanh thu, giảm chi phí, phát triển kinh doanh hiệu quả hơn.
​Phần mềm quản lý bán hàng​
​Dịch vụ vận chuyển​
​Thiết kế website bán hàng​
​Phần mềm quản lý Facebook Fanpage​
Giới thiệu Nhanh.vn API 2.0
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.
Khởi tạo ứng dụng
Để 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
Lấy access token
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
Request params
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ể
Postman Sample
Dùng Postman lấy danh sách sản phẩm có phân trang.
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
Code Sample
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 code sample tạo sản phẩm /api/product/add​
1
<?php
2
​
3
    $appId => "_YOUR_APP_ID";
4
    $accessToken => "_YOUR_ACCESS_TOKEN";
5
    $businessId => "_YOUR_BUSINESS_ID"; // ID doanh nghiệp trên Nhanh.vn
6
​
7
    $dataArray = array(
8
        array(
9
            "id"  => "1741235",
10
            "parentId"  => null,
11
            "code" => "SSGS2",
12
            "barcode" => null,
13
            "name" => "Samsung galaxy S2",
14
            "image" => "http://example.com/images/samsung-galaxy-s-2.jpg",
15
            "images" => array(),
16
            "shippingWeight" => 370, // gram
17
            "importPrice" => 12000000,
18
            "price"  => 13500000,
19
            "vat" => 10, // 10%
20
            "status" => "Active",
21
        )
22
        // product 2
23
        // ...
24
    );
25
​
26
    $dataString = json_encode($dataArray);
27
​
28
    $postArray = array(
29
        "version" => "2.0",
30
        "appId" => $appId,
31
        "businessId" => $businessId,
32
        "accessToken" => $accessToken,
33
        "data" => $dataString
34
    );
35
​
36
    $curl = curl_init("https://open.nhanh.vn/api/product/add");
37
    curl_setopt($curl, CURLOPT_POST, 1);
38
    curl_setopt($curl, CURLOPT_POSTFIELDS, $postArray);
39
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
40
​
41
    $curlResult = curl_exec($curl);
42
​
43
    if(! curl_error($curl)) {
44
        // success
45
        $response = json_decode($curlResult);
46
    } else {
47
        // failed, cannot connect nhanh.vn
48
        $response = new stdClass();
49
        $response->code = 0;
50
        $response->messages = array(curl_error($curl));
51
    }
52
    curl_close($curl);
53
​
54
    if ($response->code == 1) {
55
        // send product successfully
56
    } else {
57
        // failed, show error messages
58
        if(isset($response->messages) && is_array($response->messages)) {
59
            foreach($response->messages as $message) {
60
                echo $message;
61
            }
62
        }
63
    }
Copied!
Nhanh API SDK
Đang cập nhật
Thuật ngữ
Trạng thái sản phẩm
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
Order
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
Inventory
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