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.
Download PHP SDK
Nhanh.vn hỗ trợ đồng bộ sản phẩm 2 chiều:
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ộ.
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.
Hiện tại tài khoản API chỉ cấp cho khách hàng đã kí hợp đồng với Nhanh.vn, xin vui lòng liên hệ với nhân viên Nhanh.vn đã kí hợp đồng với anh/chị để được trợ giúp.
(The register form will be available soon) Các câu hỏi trong quá trình tích hợp API xin gửi về dev@nhanh.vn đội ngũ kĩ thuật sẽ tiếp nhận và trả lời quý khách.
An API account includes:
Param | Data type (Max-length) | Description |
apiUsername | string(32) | API Username |
secretKey | string(32) | used to create the checksum |
Testing: https://dev.nhanh.vn
Production: https://graph.nhanh.vn
RESTful applications use HTTP requests to post data. The POST params include:
Param | Data Type (Max-length) | 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 sàn. |
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}}
PHP SDK: https://github.com/nhanhapi/pos-api-php
Simple request: send product information
<?php$apiUsername = "_YOUR_API_USERNAME_";$secretKey = "_YOUR_SECRET_KEY_";$dataArray = array(// product 1array('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 messagesif(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 KeyDevelopment 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);
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 |
ChangeDepot | Đổi kho xuất hàng |
Pickup | Chờ đi lấy hàng |
Pickingup | Đang đi lấy hàng |
Pickedup | Đã lấy hàng từ kho |
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 |