A. TẠI SAO CẦN DÙNG NHANH.VN OPEN API ĐỂ LẤY DỮ LIỆU DANH SÁCH ĐƠN HÀNG?

Bạn đang muốn sử dụng Nhanh.vn Open API (mình sẽ gọi tắt là Nhanhvn API) để lấy dữ liệu đơn hàng - có thể vì không muốn tải thủ công mỗi ngày, hoặc muốn tích hợp vào ETL pipeline phục vụ tự động hóa?

Thế nhưng sau khi đọc tài liệu của Nhanhvn, bạn vẫn không thể thực hiện được một truy vấn thành công 🤧

Đừng lo, vấn đề không nằm ở bạn đâu. Với những ai có nền tảng kỹ thuật, việc đọc hiểu tài liệu API sẽ rất dễ, nhưng nếu bạn không có background IT và mới tập tành tiếp xúc với API như mình đã từng, thì việc này thực sự mất nhiều thời gian và công sức để “vỡ” ra cách làm.

Bài viết này chính là dành cho bạn - mình sẽ hướng dẫn từng bước một, từ thiết lập tài khoản Nhanhvn Developer cho đến đọc dữ liệu từ response trả về.

Prerequisite: Bạn nên có 3 kiến thức sau để đọc hiểu bài viết này một cách hiệu quả nhất:

• Đã từng sử dụng Nhanhvn hoặc thao tác với dữ liệu tải về từ Nhanhvn;
• Hiểu biết cơ bản về API: hiểu biết cơ bản về các khái niệm: API, request, response, json;
• Biết sử dụng 1 công cụ hoặc 1 ngôn ngữ lập trình có thể gửi request và đọc response: ở bài viết này mình sẽ sử dụng Python để gửi request và đọc response. Các bạn có thể sử dụng các công cụ hay ngôn ngữ khác đều được nhé.

---

B. BẮT ĐẦU

Nội dung bài viết:

1. Giới thiệu sơ qua và cách hoạt động của Nhanhvn API
2. Sử dụng Nhanhvn API để lấy dữ liệu Danh Sách Đơn Hàng

• 2.1. Lấy App ID, Business ID, và Access Token
• 2.2. Gửi request lấy danh sách đơn hàng
• 2.3. Đọc dữ liệu trong response trả về
• 2.4. Một số chú ý

1. Giới thiệu sơ qua và cách hoạt động của Nhanhvn API

Giới thiệu: Nhanhvn API cho phép bạn tương tác trực tiếp với dữ liệu trên hệ thống Nhanhvn thông qua 4 loại requests GET, POST, PUT, DELETE; thay vì phải tương tác qua giao diện web hay ứng dụng.

Các tương tác bao gồm lấy dữ liệu (đơn hàng, khách hàng, sản phẩm, v.v.), tạo mới dữ liệu, cập nhật dữ liệu, hoặc xóa dữ liệu.

Chú ý: khác với các nền tảng khác, Nhanhvn API không có phương thức GET. Khi bạn muốn đọc dữ liệu, phải dùng phương thức POST gửi request đến một số endpoint cụ thể chuyên để xử lý requests đọc dữ liệu.

Lý do cho việc này, là do Nhanhvn API có rất nhiều tiêu chí lọc dữ liệu tải về từ API. Việc truyền các tiêu chí lọc này qua thông số data hoặc json trong phương thức POST sẽ hiệu quả hơn truyền qua thông số params trong phương thức GET.

Cách hoạt động: trong Nhanhvn API, 1 requests gửi đến server cần chứa 3 thông tin:

• App ID: ID của app bạn đã tạo trên https://open.nhanh.vn/
• Business ID: ID của business bạn đã đăng ký khi tạo tài khoản Nhanhvn
• Access token: bạn sẽ lấy được token này sau khi đã tạo 1 app

Thiếu 1 trong 3 thành phần này, requests của bạn sẽ bị coi là không hợp lệ và không thể sử dụng Nhanhvn API.

2. Sử dụng Nhanhvn API để lấy dữ liệu Danh Sách Đơn Hàng

2.1. Lấy App ID, Business ID, và Access Token

Như đã nói ở phần trước, để lấy được dữ liệu thông qua Nhanhvn API, 1 requests cần có đủ 3 thành phần. Sau đây mình sẽ hướng dẫn lần lượt các bước lấy 3 thành phần đó:

Lấy App ID:

Để lấy được App ID, bạn cần tạo 1 app trên trang https://open.nhanh.vn/ , mà để tạo đc 1 app, bạn cần có 1 tài khoản Nhanhvn developer, mà để có 1 tài khoản Nhanhvn developer, bạn lại cần 1 tài khoản Nhanh.vn

Chi tiết các bước lấy App ID như sau:

Bước 1: Tạo 1 tài khoản trên Nhanh.vn. Nếu bạn đã có sẵn tài khoản Nhanhvn rồi thì bỏ qua bước này.

Bước 2: Cấp quyền truy cập API cho tài khoản Nhanhvn của bạn:

• Nếu tài khoản vừa tạo có quyền “Giám đốc”: Trong tài khoản Nhanhvn vừa tạo, vào “Trang Quảng Trị” -> vào tab “Cài đặt” -> Tìm mục “Cài đặt Open API” -> Bật cho phép kết nối Open API.

• Nếu tài khoản vừa tạo không có quyền “Giám đốc”: bạn hãy yêu cầu tài khoản “Giám đốc” cấp quyền cho phép kết nối Open API cho tài khoản của bạn.

Bước 3: Tạo 1 app:

Đăng nhập tài khoản Nhanhvn của bạn vào trang https://open.nhanh.vn/ , giờ bạn đã có 1 tài khoản developer.

Vẫn trên trang developer này, hãy click vào nút +Thêm mới để tạo 1 app. Có 3 thông tin tối thiểu yêu cầu khi tạo 1 app (như ảnh dưới):

• Tên app: bạn tự đặt như nào cũng được.
• Trạng thái: chọn “đang hoạt động”.
• Redirect URL: đây là đường link nhận access code của app (access code là gì và nó có tác dụng như nào thì cứ đọc tiếp sẽ rõ nhé). Bạn có thể để 1 link bất kỳ chạy https, tuy nhiên bạn nên để đường link của chính trang Nhanhvn: https://nhanh.vn/

Lấy Business ID và Access Token:

Để lấy Business ID và Access Token, bạn cần gửi 1 POST request đến endpoint https://pos.open.nhanh.vn/v3.0/app/getaccesstoken. Response trả về sẽ chứa Business ID và Access Token.

Tuy nhiên request này yêu cầu 3 parameter là: App ID (đã có từ bước trước), Secret Key (vào app vừa tạo để lấy), và Access Code (chưa có cái này).

Tóm lại là, bây giờ cần phải có thêm Access Code thì bạn mới lấy được Business ID và Access Token.

Bước 1: Lấy Access Code:

Để lấy Access Code, bạn hãy truy cập link: https://nhanh.vn/oauth?version=API_VERSION&appId=YOUR_APPID&returnLink=YOUR_RETURN_LINK

Trong đó:

• API_VERSION: v3.0
• YOUR_APPID: là app ID bạn có sau khi tạo app
• YOUR_RETURN_LINK: là Redirect URL bạn điền vào mục Redirect URL khi tạo app

Sau khi truy cập link, 1 bảng như ảnh dưới sẽ hiện ra, bảng này xác định quyền và phạm vi mà API được phép sử dụng:

• Số 1: Chọn doanh nghiệp bạn muốn sử dụng API;
• Số 2: Chọn POS;
• Số 3: Chọn kho bạn muốn sử dụng API;
• Số 4: Chọn các quyền của API, bạn cứ chọn tất cả quyền cho tiện;
• Cuối cùng, ấn đồng ý ở số 5.

Sau khi ấn “Đồng ý”, bạn sẽ được chuyển hướng về trang Redirect URL, kèm theo 1 Access Code được đính kèm trên link Redirect URL. Ví dụ nếu bạn để Redirect URL là https://nhanh.vn/, thì bạn sẽ được chuyển hướng về trang:

https://nhanh.vn/auth?accessCode=ACCESS_CODE_RECEIVED

Lưu ý: Access Code này chỉ có hạn trong 10 phút và sẽ hết hạn ngay sau khi lấy được Access Token. Nếu Access Code đã hết hạn, bạn sẽ phải thực hiện lại Bước 1: Lấy Access Code để lấy được 1 Access Code mới.

Bước 2: Gửi POST requests để lấy Business ID và Access Token:

Bạn có thể sử dụng các công cụ hoặc ngôn ngữ lập trình khác để gửi requests này, mình sẽ sử dụng Python:

import requests
appId = "YOUR APP ID"
access_code = "YOUR ACCESS CODE"
secret_key = "YOUR APP SECRET KEY"
url = f"https://pos.open.nhanh.vn/v3.0/app/getaccesstoken?appId={appId}"
json = {"accessCode": access_code, "secretKey": secret_key}
response = requests.post(url=url, json=json)
print(response.json())

Kết quả chương trình này trả về 1 nested dictionary chứa 5 thông tin:

• Access Token: đây là thông tin bạn cần lấy;
• Business ID: đây là thông tin bạn cần lấy;
• Ngày hết hạn: mỗi Access Token chỉ có hạn sử dụng trong vòng 1 năm kể từ ngày tạo, khi hết hạn, bạn sẽ phải tạo lại Access Token mới cho app;
• Các quyền của app: là các quyền bạn đã chọn trong bước lấy Access Code;
• Phiên bản của Nhanhvn API.

Ta-da, vậy là bây giờ bạn đã có đủ 3 thông tin để tạo 1 requests Nhanhvn API hợp lệ! Giờ bạn có thể tha hồ sử dụng các endpoint của Nhanhvn API nhé 😁

Tất nhiên phần sau của bài viết này vẫn chỉ tập trung hướng dẫn bạn sử dụng 1 endpoint để lấy dữ liệu danh sách đơn hàng thôi!

2.2. Gửi request lấy danh sách đơn hàng

Tài liệu official Nhanhvn API của endpoint này: https://apidocs.nhanh.vn/v3/order/list

Endpoint lấy danh sách đơn hàng: https://pos.open.nhanh.vn/v3.0/order/list

Tác dụng: endpoint này cho phép lấy dữ liệu các đơn hàng mà doanh nghiệp đã tạo.

Dữ liệu lấy được từ endpoint này tương đương với 2 thao tác tải thủ công như sau:

• Dữ liệu đơn hàng từ kênh Admin: Vào tab “Đơn hàng” -> Mục “Đơn hàng” -> Chọn các điều kiện lọc đơn hàng -> Click nút “Thao tác” -> Mục “Xuất Excel” (2 ảnh minh họa dưới)

• Dữ liệu đơn hàng từ các kênh thương mại điện tử: Vào tab “Đơn hàng “ -> Mục “Sàn TMĐT” -> Chọn sàn cần tải dữ liệu -> Chọn các điều kiện lọc đơn hàng -> Click nút “Thao tác” -> Mục “Xuất Excel” (2 ảnh minh họa dưới)

Với endpoint lấy danh sách đơn hàng, có 2 loại thông số có thể truyền vào requests, gồm thông số bắt buộc và thông số tự chọn:

• Thông số bắt buộc (dùng để xác định 1 requests hợp lệ):

# 1. Thông số truyền vào params:
params = {'appId':appId, 'businessId':businessId}

# 2. Thông số truyền vào headers:
headers = {'Authorization':accessToken, 'Content-Type':'application/json'}

# Trong đó: appId, businessId, accessToken là 3 thông tin bạn đã lấy được từ phần 2.1

• Thông số tự chọn (dùng để lọc dữ liệu muốn trả về):

json = {
"filters": {...đây là 1 dictionary, dùng để lọc dữ liệu đơn hàng muốn lấy...},
"Paginator": {...đây là 1 dictionary, dùng để phân trang dữ liệu...},
"dataOptions": {...đây là 1 dictionary, dùng để lấy thêm 1 số dữ liệu phụ...}
}

Với thông số bắt buộc thì rất đơn giản, bạn chỉ cần là truyền các biến appId, businessId, accessToken vào params và headers là hoàn thành. Bạn hoàn toàn có thể gửi requests mà không kèm theo thông số tự chọn, tất nhiên dữ liệu mà response trả về chỉ chứa các đơn hàng theo mặc định của endpoint này.

Theo mặc định: response sẽ trả về các đơn hàng trong vòng 45 ngày tính đến ngày hiện tại, của tất cả các trạng thái, các nguồn đơn, các kênh bán; các đơn hàng trả về sắp xếp theo thứ tự từ mới nhất đến cũ nhất; giới hạn lấy được dữ liệu 100 đơn hàng mỗi lần request.

Bạn có thể sử dụng thông số tự chọn để xác định các đơn hàng mà response sẽ trả về theo ý muốn của bạn, tất nhiên thông số này cũng phức tạp hơn.

Thông số tự chọn gồm 3 phần: filters, Paginator, và dataOptions. Sau đây mình sẽ hướng dẫn sử dụng lần lượt 3 phần này nhé:

Phần filters:

Bạn có thể tạo nhiều điều kiện lọc đồng thời nhau: theo thời gian tạo đơn, theo trạng thái đơn, theo nền tảng, theo đơn vị vận chuyển,... Bằng cách sử dụng filter trong thông số json.

Theo kinh nghiệm cá nhân, có 4 field phổ biến trong filters (mỗi field là 1 cặp key:value):

• Ngày bắt đầu tính theo ngày tạo đơn hàng: có key là createdAtFrom, value là 1 integer thể hiện giá trị thời gian dạng Unix timestamp;
• Ngày kết thúc tính theo ngày tạo đơn hàng: có key là createdAtTo, value là 1 integer thể hiện giá trị thời gian dạng Unix timestamp;
• Trạng thái đơn hàng: có key là statuses, value là 1 list các integer. Mỗi integer là 1 mã trạng thái đơn hàng (xem danh sách mã trạng thái tại: https://apidocs.nhanh.vn/v3/modelconstant#order-status);
• Kênh bán hàng: có key là saleChannels, value là 1 list các integer. Mỗi integer là 1 mã kênh (xem danh sách mã trạng thái tại: https://apidocs.nhanh.vn/v3/modelconstant#order-sale-channel).

Đọc thì hơi khó hiểu nhỉ 😵‍💫 Để mình lấy ví dụ cho dễ tưởng tượng nhé. Giả sử bạn muốn dùng Nhanhvn API lấy danh sách các đơn hàng thỏa mãn cả 3 điều kiện sau: "Các đơn tạo từ ngày 01/10/2025 đến 24/10/2025, ở trạng thái mới hoặc thành công, và bán tại kênh admin".

filter sẽ có giá trị:

"filters": {"createdAtFrom":1759251600, "createdAtTo":1761238800, "statuses":[54, 60], "saleChannels":[1]}

Trong đó:

• 1759251600 là giá trị 01/10/2025 00:00:00 sau khi quy đổi ra dạng dữ liệu Unix timestamp, 1761238800 là giá trị 24/10/2025 23:59:59 sau khi quy đổi ra dạng dữ liệu Unix timestamp.
• 54 là mã của trạng thái mới, 60 là mã của trạng thái thành công.
• 1 là mã của kênh bán Admin.

Dưới đây là bảng liệt kê tất cả 14 tiêu chí có thể filter, bạn hãy truy cập tài liệu official Nhanhvn docs của endpoint này để biết thêm chi tiết (link mình đã gắn ở đầu phần 2.2):

Phần Paginator:

Trong response trả về, dữ liệu có phân trang. Bạn có thể sử dụng Paginator để xác định trang muốn lấy dữ liệu.

Paginator có 3 field, mỗi field là 1 cặp key:value

• Size: Số lượng bản ghi trên 1 trang, tối đa ko quá 100.
  • Size là 1 cặp key:value với key là size, value là 1 integer (integer này phải <=100).
• Next: Dùng để gọi dữ liệu cho trang tiếp theo.
  • Với endpoint danh sách đơn hàng, nếu số lượng đơn hàng response trả về lớn hơn 100 (theo mặc định của field Size), bạn sẽ chỉ nhận được danh sách 100 đơn đầu. Khi này, trong json trả về sẽ kèm theo 1 cặp giá trị có dạng {"next":{"id":123456789}}. Trong đó, 123456789 chính là ID của đơn cuối cùng trong danh sách đơn hàng mà response trả về (với trường hợp này là đơn thứ 100). Khi bạn truyền ID 123456789 vào field next trong lần request tiếp theo, response sẽ trả về danh sách các đơn từ thứ 101 đến 200.
  • Next là 1 cặp key:value với key là next, value là 1 dictionary dạng {"id":xxxxxxxxx} (x là 1 số nguyên dương).
• Sort: Tiêu chí sắp xếp của dữ liệu trong response trả về.
  • Sort là 1 cặp key:value với key là sort, value là 1 dictionary có key là tên trường muốn sắp xếp (VD: id, createdAtFrom,...) và value là kiểu sắp xếp (asc hoặc desc)

Mình lấy tiếp 1 ví dụ cho bạn dễ hình dung phần Paginator này nhé: Giả sử bạn muốn response trả về có 50 ID đơn hàng, lấy từ đơn có ID 123456789 trở đi và không bao gồm đơn 123456789, Paginator sẽ có giá trị:

"paginator":{'size':50, 'next':{'id':123456789}}

Phần dataOptions:

Mình chưa dùng đến cái này bao giờ nên chưa tìm hiểu 😅. Bạn có thể đọc thêm phần này trong official Nhanhvn API docs.

Tạo 1 requests hoàn chỉnh lấy dữ liệu danh sách đơn hàng:

Đến đây, bạn đã biết cách gửi requests để lấy danh sách đơn hàng theo ý muốn thông qua Nhanhvn API

Để tổng hợp các kiến thức trong phần 2.2, mình sẽ viết 1 chương trình để lấy danh sách đơn hàng thỏa mãn các điều kiện: "Các đơn tạo từ ngày 01/10/2025 đến 18/10/2025, ở trạng thái mới hoặc thành công, và bán tại kênh admin. Mình muốn response trả về 5 đơn hàng, lấy từ đơn có ID 123456789 trở đi và không bao gồm đơn 123456789"

import requests
import json
from datetime import datetime
# Set filter dates:
start_date = '2025-10-01 00:00:00'
end_date = '2025-10-18 23:59:59'
# Convert the datetimes into Unix timestamp datetimes:
start_date = datetime.strptime(start_date, "%Y-%m-%d %H:%M:%S")
start_date = int(start_date.timestamp())
end_date = datetime.strptime(end_date, "%Y-%m-%d %H:%M:%S")
end_date = int(end_date.timestamp())
# Send the request to retrieve needed data:
appId = 'your app ID'
businessId = 'your business ID'
accessToken = 'your access token'
url = "https://pos.open.nhanh.vn/v3.0/order/list"
params = {'appId':appId, 'businessId':businessId}
headers = {'Authorization':accessToken, 'Content-Type':'application/json'}
filter = {"filters": {"createdAtFrom":start_date, "createdAtTo":end_date, "statuses":[54, 60], "saleChannels":[1]}, "paginator":{"size":5, "next":{'id':123456789}}, "dataOptions":{}}
response = requests.post(url=url, params=params, headers=headers, json=filter)
print(response.json())

2.3. Đọc dữ liệu trong response trả về

Response của endpoint này sẽ có cấu trúc:

{
“code”:1,
“paginator”:{ “next”:{“id”:987654321}},
“data”:[{...}, {...}, {...}, {...}, {...}, {...}, {...},...]
}

Trong đó:

• code: mã trạng thái của requests. Requests thành công sẽ có mã 1, requests thất bại sẽ có mã 0.
• paginator: chứa dữ liệu phân trang. 987654321 là ID của đơn cuối cùng trong danh sách đơn hàng mà response trả về.
• data: chứa các dictionary, mỗi dictionary là thông tin của 1 đơn hàng. Bên dưới mình sẽ trình bày cấu trúc dữ liệu trong mỗi đơn hàng response trả về.

Cấu trúc của 1 đơn hàng trong response:

{
“info”:{“id”:246813579, “createdAt”:1760806450, “tags”:[...], “status”:74,...},
“channel”:{“saleChannel”:1, “affiliate”:{...}, “marketing”:[...], “trafficSource”:“Page Facebook số 1”,...},
“shippingAddress”:{},
“products”:[{...}, {...},...],
“carrier”:{},
“payment”:{}
}

Trong đó:

• info: chứa các thông tin cơ bản của đơn hàng như ID, ngày tạo đơn, ngày cập nhật, thẻ, ghi chú nội bộ, ghi chú của khách,...
• channel: chứa các thông tin về nguồn đơn hàng.
• shippingAddress: chứa các thông tin về địa chỉ giao hàng.
• products: chứa các thông tin về các sản phẩm trong đơn hàng. Với các đơn hàng có nhiều hơn 1 mã sản phẩm, thông tin của mỗi mã sản phẩm sẽ được chứa trong 1 list.
• carrier: chứa các thông tin về đơn vị vận chuyển.
• payment: chứa các thông tin về sự thanh toán của khách hàng cho đơn hàng đó.

Ta-da, đến đây bạn đã biết cách lấy dữ liệu đơn hàng thông qua Nhanhvn API rồi đó. Congratulation! 🥳

Phần cuối mình muốn chia sẻ 1 số chú ý rút ra được sau khi sử dụng endpoint trong API này 1 thời gian.

2.4. Một số chú ý

Có 3 lưu ý khi sử dụng endpoint lấy danh sách đơn hàng trong Nhanhvn API:

• Mặc dù có field createdAtFrom và createdAtTo để lọc theo thời gian tạo đơn hàng. Tuy nhiên requests sẽ không phân biệt được phần giờ:phút:giây của 2 thông số này, mà sẽ coi mặc định phần giờ:phút:giây trong createdAtFrom là 00:00:00 và phần giờ:phút:giây trong createdAtTo là 23:59:59.
  • Ví dụ: dù bạn đã xác định createdAtFrom là 2025-10-01 13:50:20 và createdAtTo là 2025-10-05 21:45:50. Thì requests vẫn coi bạn xác định createdAtFrom là 2025-10-01 00:00:00 và createdAtTo là 2025-10-05 23:59:59.
• createdAtFrom và createdAtTo chỉ có độ dài tối đa là 45 ngày, nếu độ dài vượt quá 45 ngày thì response sẽ trả về lỗi.
• Rate Limit của Nhanhvn API v3.0 mặc định là 150 requests/30 giây. 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

Lời kết

Trên đây là toàn bộ kiến thức mình tìm hiểu được về Nhanhvn API và endpoint lấy danh sách đơn hàng. Sau khi đọc xong, bạn đã lấy được dữ liệu cần thiết từ API chưa?

Nếu có thắc mắc hay góp ý, hãy bình luận xuống dưới hoặc liên hệ mình qua email: vithanhnam1408@gmail.com nhé!

Nếu thấy bài viết hay, đừng ngần ngại cho mình 1 like, 1 comment, và 1 share nha 😀

Bạn muốn lần tiếp theo mình làm hướng dẫn sử dụng API của nền tảng nào?