Nhanh.vn Open API
Trang chủHướng dẫn sử dụngApps
Search…
v1
Giới thiệu
Get data from Nhanh.vn
Lấy hãng vận chuyển
Lấy danh sách thành phố, quận huyện
Tính phí vận chuyển
Lấy danh sách đơn hàng
Lấy danh sách lịch sử đơn hàng
Lấy danh mục sản phẩm
Lấy danh sách sản phẩm
Lấy thông tin chi tiết sản phẩm
Lấy danh sách quà tặng sản phẩm
Lấy danh sách IMEI
Tra cứu IMEI bán ra theo ngày
Lấy danh sách khách hàng
Lấy danh mục tin tức
Lấy danh sách tin tức
Lấy danh sách nhà cung cấp
Lấy danh sách phiếu xuất nhập kho
Lấy danh sách sản phẩm xuất nhập kho
Lấy danh sách sản phẩm xuất nhập kho nháp
Lấy danh sách kho doanh nghiệp
Lấy danh sách coupon
Lấy danh sách nhân viên
Lấy danh sách bảo hành
Nhúng khung đặt hàng Nhanh
Tích hợp-elastix
Send data to Nhanh.vn
Tạo gian hàng
Thêm sản phẩm
Thêm đơn hàng
Cập nhật đơn hàng
Gửi khiếu nại đơn hàng
Thêm khách hàng
Cấu hình webhooks
Listen webhooks from Nhanh.vn
Nhận cập nhật trạng thái đơn hàng
Nhận cập nhật sản phẩm
Nhận cập nhật tồn kho
Nhận cập nhật thay đổi cấp độ, thêm điểm, trừ điểm
Nhận cập nhật hóa đơn mới
Nhận cập nhật khiếu nại
Powered By GitBook
Giới thiệu

​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.

  • 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 website 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.
  • Nhanh API sử dụng RESTful và JSON format.
  • ​Khởi tạo API Account, Environment, Request, Response, Code Sample.

  • Từ ngày 01/12/2021 hệ thống ra mắt bản API 2.0 sử dụng access token và cơ chế cấp quyền linh hoạt, giúp người sử dụng có thể dễ dàng lựa chọn các loại dữ liệu mà một ứng dụng được phép truy cập, thay vì được truy cập toàn bộ dữ liệu như phiên bản 1.0
  • Hệ thống đã ngừng hỗ trợ cấp tài khoản API 1.0, mọi kết nối mới xin vui lòng sử dụng bản 2.0
  • API 1.0 sẽ được hỗ trợ duy trì thêm trong vòng 2 năm tới 31/12/2023 (hệ thống sẽ chỉ sửa lỗi nếu có, không cập nhật thêm các tính năng mới ở bản 1.0).

  • Khi gửi request sang NhanhAPI, cả 2 bản đều dùng POST method, body form-data. Bản 1.0 yêu cầu 4 params: version, apiUsername, checksum, data. Bản 2.0 yêu cầu 5 params: version, appId, businessId, accessToken, data.
    • Bản 1.0 bạn điền version = 1.0, bản 2.0 điền version = 2.0
    • Authentication: Bản 1.0 dùng apiUsername và checksum, bản 2.0 sẽ dùng appId, businessId và accessToken. Xem cách khởi tạo appId và lấy accessToken, khi lấy được accessToken thì NhanhAPI có trả về thông tin businessId.
    • Cách tạo param data ở cả 2 bản vẫn giống hệt nhau: cho dữ liệu vào 1 mảng array, sau đó json encode mảng này.
  • Webhooks:
    • Bản 1.0 mỗi webhooks cần đăng ký 1 link riêng, NhanhAPI sẽ gửi sang content-type: multipart/form-data và body form-data.
    • Bản 2.0 thì webhooks chỉ đăng ký 1 link chung, NhanhAPI sẽ gửi sang content-type: application/json và request body là json string, các webhooks sẽ phân biệt bằng trường event để biết sự kiện của webhooks là gì. Xem cách bật và nhận webhooks bản 2.0.
  • Môi trường test:
    • Bản 1.0: phân biệt ra 2 môi trường dev (https://dev.nhanh.vn) và production riêng (https://nhanh.vn).
    • Bản 2.0: developer có thể tự tạo 2 app riêng biệt:
      • 1 app cho môi trường test, và đăng kí 1 doanh nghiệp mới trên Nhanh.vn, dùng tài khoản doanh nghiệp test này để đăng nhập cấp quyền cho app test.
      • 1 app cho môi trường production: cho tài khoản thật của doanh nghiệp đăng nhập cấp quyền.

Nhanh.vn hỗ trợ đồng bộ sản phẩm 2 chiều:
  1. 1.
    Bạn dùng Nhanh.vn trước, sau đó muốn lấy dữ liệu sản phẩm sang các hệ thống khác: Đồng bộ sản phẩm từ Nhanh.vn về hệ thống của bạn => nên dùng id sản phẩm bên Nhanh.vn làm key đồng bộ.
  2. 2.
    Bạn có website từ trước, sau đó mới dùng Nhanh.vn: Bạn có thể đồng bộ sản phẩm từ website về Nhanh => nên dùng id sản phẩm bên website làm key đồng bộ.
    khi đồng bộ sản phẩm từ website cũ về Nhanh, Nhanh sẽ trả về id sản phẩm trên Nhanh, bên web sau đó có thể lưu lại idNhanh này và tất cả các API khác sau đó dùng idNhanh làm key đồng bộ

  • Tồn kho chỉ được đồng bộ từ Nhanh.vn sang các hệ thống khác, Nhanh.vn không nhận cập nhật tồn kho từ bên ngoài.
  • Khi tồn kho trên Nhanh.vn có thay đổi, hệ thống của bạn sẽ nhận được 1 webhooks (xem thêm mục Listen Inventory.

  • Nhanh.vn hỗ trợ đồng bộ đơn hàng từ các hệ thống khác về, thường dùng khi bạn có website từ trước:
    • Khi khách đặt hàng: Đồng bộ thông tin đơn hàng về Nhanh.vn.
    • Khi khách hủy đơn hoặc thanh toán online cho đơn hàng: Cập nhật thông tin đơn hàng
    • Khi nhân viên xử lý các đơn hàng ở Nhanh.vn, Nhanh.vn sẽ gửi webhooks về hệ thống của bạn để cập nhật trạng thái đơn hàng, lịch trình vận đơn.
  • Nhanh.vn hỗ trợ các API về tính phí vận chuyển, và các cài đặt gửi Email, gửi SMS để thông báo cho khách hàng về thông tin đơn hàng.

  • Từ ngày 01/12/2021 hệ thống đã ngừng gia hạn và cấp mới tài khoản API v1.0 theo thông báo tại đây.
Param
Type
Description
apiUsername
string(32)
API Username
secretKey
string(32)
used to create the checksum

  • RESTful applications use HTTP requests to post data. The POST params include:
Param
Type
Mandatory
Description
version
string(10)
Yes
The current version is 1.0
storeId
string(20)
No
id gian hàng trên các sàn thương mại điện tử. Param này chỉ bắt buộc với các tài khoản được admin Nhanh.vn cấu hình là loại sàn TMĐT, các tài khoản bình thường không gửi thêm param storeId này để tránh lỗi "Store not found"
apiUsername
string(32)
Yes
API Username
data
string
Yes
The JSON encoded string of an array. Xem data array ở từng API bạn cần sử dụng. Chú ý: Một vài API sẽ có data là 1 string cố định (VD lấy danh mục sản phẩm sẽ là: productcategory, lấy danh sách hãng vận chuyển sẽ là: carriers...), bạn chú ý ở từng API sẽ có ghi chú về fixed dataString ở mục request của API đó
checksum
string(32)
Yes
checksum to validate the request. checksum = md5(md5(secretKey + data) + data)

  • The response is a JSON encoded string, which decodes into the following structure:
    {
    "code": 1, // 1 = success, 0 = failed (see errors in messages)
    "messages": { // if the code = 0 the server will return error messages
    "error code": "message 1",
    "error code": "message 2"
    },
    "data": {
    // structure will be explained in detail each request below
    }
    }

Postman Sample

  • Simple request: send product information
<?php
​
$apiUsername = "_YOUR_API_USERNAME_";
$secretKey = "_YOUR_SECRET_KEY_";
​
$dataArray = array(
// product 1
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);
$checksum = md5(md5($secretKey . $dataString) . $dataString);
​
$postArray = array(
"version" => "1.0",
"apiUsername" => $apiUsername,
"data" => $dataString,
"checksum" => $checksum
);
​
$curl = curl_init(“https://dev.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;
}
}
}

Một số lỗi thường gặp

Nếu bạn nhận được response lỗi: authentication failed, xin vui lòng kiểm tra lại các mục sau:
  • Kiểm tra lại các thông số apiUsername, secretKey, environment (dev / production).
  • Trong code có set biến storeId, biến này chỉ dùng cho các sàn thương mại điện tử (VD: Lazada, Tiki, Shopee, Vatgia, Sendo...) có nhiều gian hàng, các website bình thường cần set biến này về null.

  • Khi bạn call API của Nhanh, lỗi này thường do nhầm lẫn giữa
    Development Secret Key và Production Secret Key
    Development Server (https://dev.nhanh.vn) và Production Server (https://graph.nhanh.vn)
  • Khi Nhanh.vn gửi data sang website của bạn, bạn có thể gặp phải lỗi ở đoạn kiểm tra tính hợp lệ của checksum:
    if (!$service->isValidChecksum($checksum, $data)) {
    echo 'Invalid checksum';
    return;
    }
    Nếu web server của bạn đang sử dụng magic quote thì các request nhận được từ nhanh sẽ bị tự động thêm các kí tự \ (đọc thêm về magic quote tại đây http://php.net/manual/en/security.magicquotes.what.php) nên checksum sẽ luôn bị báo sai.
  • Cách xử lý: http://docs.php.net/manual/en/security.magicquotes.disabling.php​
    if(ini_get("magic_quotes_runtime")) {
    $data = stripslashes($data);
    }

SSL certificate problem: unable to get local issuer certificate
Bạn có thể thử 1 trong các cách sau:
  • Tải file http://curl.haxx.se/ca/cacert.pem mở file php.ini của web server, add setting
    curl.cainfo=<path-to>cacert.pem
    Restart web server.
  • Mở file NhanhService.php Hàm sendRequest add thêm dòng
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
    ngay trước dòng
    $curlResult = curl_exec($curl);

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 buôn
8
Kiểu kiểm kho
10
Kiểu khác
Next - Get data from Nhanh.vn
Lấy hãng vận chuyển
Last modified 2mo ago
Copy link
On this page
Giới thiệu Nhanh.vn
Giới thiệu Nhanh.vn API 1.0
Chuyển đổi sang API 2.0
Các tình huống phổ biến
API Account
Một số lỗi thường gặp
Thuật ngữ