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.

• Các sản phẩm và dịch vụ chính:

  • Phần mềm quản lý bán hàng: Quản lý sản phẩm, kho hàng, đơn hàng, bán lẻ, bán sỉ, sàn thương mại điện tử, khách hàng, khuyến mại, kế toán, công nợ, báo cáo.

  • Phần mềm quản lý chat đa kênh: Quản lý chat từ Messenger, Instagram, Zalo, Shopee, Lazada, Tiktok.

  • Thiết kế website bán hàng: Tạo website bán hàng chuẩn SEO, tăng tốc bán hàng.

  • Dịch vụ vận chuyển: Kết nối hơn 15 hãng vận chuyển lớn nhất, nhiều ưu đãi vận chuyển.

  • Dịch vụ marketing: Xây dựng và chăm sóc fanpage, gian hàng trên các sàn thương mại điện tử, chạy quảng cáo (Facebook, Google, Tiktok), SEO, Backlink, SMS brandname, Zalo OA, Zalo ZNS.

Giới thiệu Open API 2.0

• Nhanh Open 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 https://open.nhanh.vn. 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.

• Một ứng dụng có thể được dùng cho nhiều doanh nghiệp trên Nhanh.vn. Một doanh nghiệp trên Nhanh.vn cũng có thể dùng nhiều ứng dụng khác nhau. VD bạn có thể dùng 1 app thiết kế landing page, 1 app affiliate, cả 2 app đều đồng bộ đơn hàng về Nhanh.vn để xử lý tập trung.

• Khi người dùng (VD tài khoản giám đốc doanh nghiệp trên Nhanh.vn) 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 (businessId) 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.

Khái niệm	Giải thích
Tên App	Do bạn tự đặt, dùng để hiển thị cho user khi đăng nhập cấp quyền cho app của bạn
Trạng thái	Dùng để bật tắt ứng dụng. Khi bạn đổi trạng thái sang Ngừng hoạt động, thì app sẽ không thể gọi API và không nhận được webhooks nữa
Redirect URL	Là link trên hệ thống của bạn, sau khi user đăng nhập cấp quyền, Nhanh sẽ redirect về URL này, kèm accessCode, bạn dùng accessCode để đổi lấy accessToken (Đọc thêm các bước lấy accessCode và accessToken bên dưới)
Bật webhooks	Dùng để bật tắt việc nhận webhooks, đọc thêm về webhooks tại đây
Webhooks callback URL	Là link trên hệ thống của bạn dùng để nhận webhooks Nhanh bắn sang
Webhooks verify token	Là 1 chuỗi kí tự do bạn tự định nghĩa, có độ dài từ 16 -> 128 kí tự, bao gồm cả số và chữ. Khi Nhanh.vn gửi webhooks data cho bạn, sẽ bao gồm cả webhooksVerifyToken giúp bạn xác minh request đến từ Nhanh.vn. Chú ý: verify token sẽ được gửi kèm trong request body, không phải gửi theo header Authentication, đọc thêm về việc nhận webhooks tại đây

Tạo ứng dụng

Lấy access token

Sơ đồ 3 bước để lấy access token

Lấy access code

• 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?version=API_VERSION&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
version	string $^{{\color{red}*}}$	Phiên bản API (phiên bản hiện tại: 2.0).
appId	int $^{{\color{red}*}}$	ID app.
returnLink	string $^{{\color{red}*}}$	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.

Đăng nhập cấp quyề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ú ý: Chú ý doanh nghiệp cần mở cài đặt cho phép kết nối Open API: Dùng tài khoản Giám đốc, đăng nhập vào trang quản trị, mục cài đặt chung > Cài đặt Open API và bật "Cho phép kết nối Open API".

• Giao diện khi user đăng nhập cấp quyền:

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=

Đổi access token

• Bước 3: App của bạn dùng accessCode này POST sang https://open.nhanh.vn/api/oauth/access_token để lấy được accessToken và các permissions được cấp cho accessToken này.

  • Request params:

Param	Type	Description
version	string $^{{\color{red}*}}$	Phiên bản API (phiên bản hiện tại: 2.0)
appId	int $^{{\color{red}*}}$	Your appId
accessCode	string $^{{\color{red}*}}$	accessCode chỉ tồn tại trong vòng 10 phút, và sẽ hết hạn ngay sau khi lấy accessToken thành công
secretKey	string $^{{\color{red}*}}$	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:

Key	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 accessToken (Y-m-d H:i:s), VD: 2022-09-25 15:30:00. - Token sẽ có hạn 1 năm. - Hiện Nhanh chưa hỗ trợ refresh token. 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 token mới khi gần hết hạn token 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

• 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:

Chú ý: Nếu param type có dấu $^{{\color{red}*}}$ là param bắt buộc (required), nếu không có là param không bắt buộc (optional).

Param	Type	Description
version	string $^{{\color{red}*}}$	2.0
appId	int $^{{\color{red}*}}$	Your app ID
businessId	int $^{{\color{red}*}}$	ID doanh nghiệp trên Nhanh.vn. Lúc bạn lấy accessToken, Nhanh API có trả về businessId
accessToken	string $^{{\color{red}*}}$	Your access token
data	string $^{{\color{red}*}}$	json string của data array. Các key của 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

Postman collection

• Bạn có thể dùng NhanhAPI Postman Collection tham khảo params cho 1 số API hay dùng.
• Để sử dụng: Bạn click vào collection mình cần -> click Fork

Postman: Tải về và tạo collection trên My Workspace của bạn

• Ở phần Create Fork: điền Fork label (Tên collection ở Workspace của bạn), Workspace (Chọn một không gian làm việc mà bạn muốn phân nhánh), xong click Fork Collection

Postman: Tải về và tạo collection trên My Workspace của bạn

Code sample

Chú ý: Bản 2.0 hệ thống chưa hỗ trợ dùng javascript để gọi API (Sẽ bị báo lỗi CORS). API 3.0 dự kiến sẽ hỗ trợ mở CORS. 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ữ (Nodejs, PHP, C#, Go, Java...):

Postman generate code syntax

Lỗi thường gặp

Invalid data

• Khi bạn gửi request 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 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 copy paste chuỗi của bạn vào textarea và click Validate.

Error ERR_PAGE_403

• Khi bạn gửi request và nhận được response có errorCode = ERR_PAGE_403, messsages = The app or accessToken is not authorized for this feature: Lỗi này là do user đăng nhập cấp quyền chưa chọn quyền hoặc không có quyền thao tác với hành động đó. VD: user đăng nhập cấp quyền, chỉ có quyền xem danh sách sản phẩm, nên sẽ không hiện ra quyền danh sách đơn hàng, hoặc user có quyền nhưng không chọn ở bước đăng nhập cấp quyền, thì sau đó bạn sẽ không thể dùng accessToken để gọi API /api/order/index.
• Cách sửa: Báo user đăng nhập đúng tài khoản có quyền thao tác với dữ liệu và chọn quyền ở bước đăng nhập cấp quyền.

API Rate Limit

• Rate Limit là số lệnh gọi API mà ứng dụng của bạn có thể thực hiện trong khoảng thời gian nhất định. Nếu vượt quá giới hạn này thì ứng dụng có thể bị giới hạn tốc độ. Các lệnh gọi API do ứng dụng đang bị giới hạn tốc độ sẽ không thành công. Lỗi này thường gặp phải khi ứng dụng không lưu dữ liệu mà luôn gọi API (VD liên tục gọi API lấy danh sách sản phẩm, danh sách đơn hàng...). Khuyến cáo: Bạn cần lưu dữ liệu ở hệ thống của bên bạn, cập nhật dữ liệu mới từ webhooks, khi gọi API chỉ nên lấy các dữ liệu có thay đổi, không lấy toàn bộ dữ liệu cũ (các API có hỗ trợ lọc theo updatedDateTimeFrom - updatedDateTimeTo hoặc updatedAtFrom - updatedAtTo).
• Rate Limit sẽ được kết hợp từ appId + businessId + API URL, nên ứng dụng của bạn có thể sẽ bị giới hạn ở 1 URL này, nhưng vẫn có thể gọi URL khác nếu URL đó không bị giới hạn, hoặc nếu ứng dụng của bạn dùng cho nhiều doanh nghiệp, thì bạn có thể bị giới hạn với businessId 1, nhưng vẫn có thể dùng được với businessId 2. Chú ý: Nếu bạn cố tình dùng nhiều ứng dụng để gọi liên tục API, hệ thống sẽ khóa toàn bộ các ứng dụng. Các ứng dụng bị khóa, sẽ không thể gọi bất kì API nào nữa.

• Rate Limit sẽ có mức chung mặc định là: 150 requests / 30 giây. Nếu 1 API có mức riêng, thì tài liệu của API đó sẽ có mô tả riêng.

• Khi vượt quá Rate Limit, bạn sẽ nhận được errorCode = 429. Bạn cần tạm ngừng gọi API tới URL này cho tới khi quá thời gian unlockedAt. Nếu vẫn tiếp tục phát sinh gọi API khi đang bị Rate Limit, lockedSeconds và unlockedAt sẽ bị tăng lên.

{
  "code": 0,
  "message": "Your app exceeded the API Rate Limit",
  "errorCode": 429,
  "data": {
    "lockedSeconds": 10,
    "unlockedAt": 1733387520
  }
}

Key	Description
lockedSeconds	Số giây bị khóa
unlockedAt	Thời gian được mở khóa theo Unix timestamp. VD: 1733387520 = 2024-12-05 15:32:00 GMT+07

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 chuyển
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

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 ở hóa đơn bán lẻ
5	Kiểu nhà cung cấp
6	Kiểu bán sỉ
8	Kiểu kiểm kho
10	Kiểu khác
18	Kiểu quà tặng ở đơn hàng

Hỗ trợ kỹ thuật

• Nếu bạn có câu hỏi xin vui lòng gửi email tới [e-mail] để đượ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).

• Chú ý: Bạn nên gửi kèm link chi tiết tới dữ liệu bạn đang thao tác, VD link tới trang chi tiết đơn hàng, chi tiết sản phẩm, chi tiết hóa đơn bán lẻ để kỹ thuật của Nhanh.vn dễ dàng tìm kiếm thông tin để hỗ trợ bạn nhanh nhất.

• 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