Giới thiệu v3.0

Chú ý: Từ ngày 23/09/2026, API docs chuyển sang tên miền mới: https://developers.nhanh.group

Khởi tạo ứng dụng

Xem cách khởi tạo ứng dụng tại đây.
Xem cách đăng nhập cấp quyền và lấy accessToken tại đây.

Request params

Sau khi lấy được accessToken, bạn có thể bắt đầu gọi các API. Mỗi service của Nhanh sẽ có các tên miền riêng:
- POS: https://pos.open.nhanh.vn
- Vpage: https://vpage.open.nhanh.vn
Version 3.0 sẽ dùng POST method, headers, body raw và các params bắt buộc như sau:
Chú ý: Nếu param type có dấu $^{{\color{red}*}}$ là bắt buộc (required), nếu không có là không bắt buộc (optional).

Param

Type

Description

appId

int $^{{\color{red}*}}$

ID app của bạn (Truyền lên link API)

businessId

int $^{{\color{red}*}}$

ID doanh nghiệp trên Nhanh.vn. Lúc bạn lấy accessToken có trả về businessId (Truyền lên link API)

Authorization

string $^{{\color{red}*}}$

Access token của bạn (Truyền lên Headers)

Paginator

Request: Khi gọi API, bạn có thể truyền thêm paginator để lấy các dữ liệu phân trang. Paginator thường có 3 field chính:
- size (int): Số lượng bản ghi trên 1 trang. Mặc định tối đa không quá 100, nếu API hỗ trợ số lớn hơn, sẽ được mô tả rõ ở từng API.
- sort (array | object): Các tiêu chí sắp xếp, xem mô tả ở tài liệu của từng API.
- next (array | object): Dùng để gọi dữ liệu cho trang tiếp theo.
  - Khi gọi API cho trang đầu tiên, thì không cần truyền next, khi nhận được response có paginator.next, thì request tiếp theo bạn cần truyền next để lấy dữ liệu cho trang sau. Tùy từng API, hoặc cùng 1 API nhưng 1 số page cũng có thể có cấu trúc next trả về khác nhau.
- Lỗi thường hay gặp phải:
  - Response trả về "paginator":{"next":{"id":"xxx"}}, thì request lấy trang tiếp theo cần truyền đúng "paginator":{"next":{"id":"xxx"}} chứ không phải "paginator":{"next":"xxx"}
  - Response trả về "paginator":{"next":{"totalRevenue":"xxx", "productId":"yyy"}}, thì request lấy trang tiếp theo cần truyền đúng "paginator":{"next":{"totalRevenue":"xxx", "productId":"yyy"}} chứ không phải "paginator":{"next": {"xxx", "yyy"}}.
  - Nếu response không trả về next, hoặc next bị NULL, nghĩa là đã hết dữ liệu, bạn không cần gọi API lấy trang tiếp theo.
  - Nếu response trả về dữ liệu ít hơn số lượng size (VD có 1 số tình huống dữ liệu bị xóa hoặc đã bị filter ẩn đi), nhưng vẫn có next, nghĩa là vẫn còn dữ liệu ở trang tiếp theo.
Response:
- next (array | object): Giá trị phân trang cho trang tiếp theo.

Postman sample

Tài liệu mô tả cho từng API hoặc webhooks do Nhanh bắn sang đều có mẫu curl đi kèm, bạn có thể mở Postman > File > Import và copy paste các mẫu curl, thay các tham số appId, businessId, accessToken để test thử.
Bạn có thể dùng Postman Collection v3.0 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
- Khuyến cáo: Bạn nên tải Postman về, cài đặt và dùng ở localhost, Bản Postman chạy online trên web, có 1 số tình huống ghi nhận Response time bị sai.
Tài liệu Nhanh Open API

Ở 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

Lấy danh sách sản phẩm

curl --location --globoff 'https://pos.open.nhanh.vn/v3.0/product/list?appId={{appId}}&businessId={{businessId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
    "filters": {
        "name": "Áo sơ mi"
    },
    "paginator": {
        "size": 50,
        "sort": {"id": "desc"},
        "next": ""
    }
}'

Thêm sản phẩm

curl --location --globoff 'https://pos.open.nhanh.vn/v3.0/product/add?appId={{appId}}&businessId={{businessId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '[
  {
    "appProductId": "string",
    "code": "Product Code 1",
    "barcode": "2000214262896",
    "name": "Product name 1",
    "price": 120000
  },
  {
    "appProductId": "string",
    "code": "Product Code 2",
    "barcode": "2000214262889",
    "name": "Product name 2",
    "price": 175000
  }
]'

Code sample

Chú ý: 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...):

Response

NhanhAPI sẽ phản hồi cho 2 tình huống Successful "code": 1 và Failed "code": 0 như bên dưới.

Successful response

Tùy API sẽ có thể chỉ trả về {"code": 1}, có thể thêm data (object, array), warning (string, object, array).

{
    "code": 1,
    "data": [
        {
            "appProductId": "X1aoCM",
            "id": 421509,
            "barcode": "2000214262919"
        }
    ]
}

{
  "code": 1,
  "warning": ["orderPrivateId is deprected, you should use appOrderId"]
}

Failed response

Khi gọi API bị lỗi, bạn sẽ nhận được phản hồi "code": 0, và có thể kèm theo các field khác như:
- errorCode: mã lỗi. Xem chi tiết mã lỗi chung, mã lỗi riêng của POS hoặc Vpage.
- messages: có thể là 1 string (VD: "messages": "content") hoặc array (VD: "messages" : ["field_1": "message_1", "field_2": "message_2"].
- data: Dữ liệu lỗi kèm theo.

{
  "code": 0,
  "errorCode": "ERR_INVALID_FORM_FIELDS",
  "messages": {
    "customer.mobile": "customer.mobile is required",
    "customer.email": "invalid customer.email"
  }
}

Common error codes

Bảng bên dưới mô tả mã lỗi chung cho cả POS và Vpage.

errorCode

Description

ERR_INVALID_APP_ID

Invalid appId

ERR_INVALID_ACCESS_TOKEN

Invalid access token

ERR_INVALID_VERSION

Invalid version. VD bạn lấy accessToken v2.0 gọi API v3.0

ERR_INVALID_BUSINESS_ID

Invalid businessId

ERR_INVALID_DEPOT_ID

Invalid depotId. Lỗi này là do khi user đăng nhập cấp quyền, không chọn kho hàng này, nên accessToken không thể thao tác với dữ liệu ở kho đó. Tình huống lỗi phổ biến: User được quản lý kho A, user đăng nhập cấp quyền chọn kho A, lúc này accessToken chỉ có quyền với kho A. Nếu trên giao diện, quyền giám đốc có phân thêm cho user được quản lý kho B, thì accessToken cũ vẫn chưa được quản lý kho B, bạn cần thực hiện lại việc đăng nhập cấp quyền, chọn cả 2 kho A và B, thì lúc này accessToken mới có quyền với cả 2 kho. Khuyến cáo dùng tính năng Kiểm tra accessToken để biết đang được thao tác với kho nào.

ERR_EXCEEDED_RATE_LIMIT

App của bạn đã vượt quá API Rate Limit

ERR_BUSINESS_NOT_ENABLE_API

Doanh nghiệp chưa mở cài đặt cho phép dùng API.

ERR_INVALID_FORM_FIELDS

Trường dữ liệu không hợp lệ, khi gặp mã lỗi này thì thường messages sẽ trả về mảng ["field": "error" ], VD ["id": "id must be integer" ]

ERR_INVALID_DATA

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.

ERR_403

Access token không có quyền thao tác với dữ liệu, thường do user khi đăng nhập cấp quyền không chọn quyền này. VD để API lấy được danh sách đơn hàng, thì user phải có quyền truy cập trang danh sách đơn hàng trên Nhanh.vn, và phải chọn danh sách đơn hàng ở bước cấp quyền cho app. Bạn có thể gọi API để Kiểm tra access token đang được gắn những kho nào, và có quyền gì.

ERR_429

App của bạn đã vượt quá API Rate Limit

Common accessToken errors

https://open.nhanh.vn là trang quản trị app. Tài khoản tạo ra app, có thể chỉ là nhân viên kỹ thuật, không có quyền gì với dữ liệu trên https://nhanh.vn/
Để đăng nhập cấp quyền cho app (lấy được accessToken), thì tài khoản đăng nhập cấp quyền, phải là tài khoản đăng nhập vào được https://nhanh.vn/, và có quyền thao tác với dữ liệu doanh nghiệp.
Tại tất cả các trang tài liệu API, đều có mô tả rõ API này dùng để lấy dữ liệu nào ở trên Nhanh.vn, bạn có thể bấm vào link để xem dữ liệu tương ứng.
Khi gọi API, nếu nhận được errorCode ERR_403: Nguyên nhân do access token không có quyền thao tác với dữ liệu.
- VD: Tài khoản nhân viên A, chỉ vào được trang Danh sách sản phẩm, không được vào được trang Danh sách đơn hàng, thì lúc nhân viên A đăng nhập cấp quyền cho app, cũng sẽ chỉ được phép chọn Danh sách sản phẩm => accessToken sẽ chỉ gọi được dữ liệu của Danh sách sản phẩm, không lấy được dữ liệu của Danh sách đơn hàng.
- Hoặc nhân viên A có quyền thao tác với dữ liệu Danh sách đơn hàng, nhưng tại bước đăng nhập cấp quyền, lại không chọn quyền này.
Các quyền gắn cho accessToken là cố định tại thời điểm user cấp quyền, không thay đổi theo quyền của tài khoản nhân viên. VD:
- Ban đầu nhân viên A được phân quyền vào danh sách sản phẩm, chưa được phân quyền vào danh sách đơn hàng => Nhân viên A đăng nhập cấp quyền tạo ra accessToken_1 => Chỉ lấy được danh sách sản phẩm.
- Sau đó nhân viên A được phân thêm quyền vào danh sách đơn hàng trên Nhanh.vn => nhưng accessToken_1 vẫn chỉ được phép thao tác với danh sách sản phẩm.
- Để lấy được danh sách đơn hàng, nhân viên A cần đăng nhập lại và cấp quyền cho app, chọn cả danh sách sản phẩm và danh sách đơn hàng => tạo ra accessToken_2, có quyền thao tác với cả danh sách sản phẩm và danh sách đơn hàng.

POS common error codes

Bảng bên dưới là các mã lỗi chung của POS. Từng API có thể có thêm các mã lỗi riêng, bạn xem tại mô tả Response của từng API.

Vpage common error codes

errorCode

Description

ERR_PAGE_EXPIRED

Page expired

ERR_INVALID_PAGE_ID

Invalid page id

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. Mức 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. Tùy theo lượng dữ liệu cần lấy, bạn cần tính toán cách xử lý để không bị lỗi Rate Limit. VD mỗi lần gọi API request bạn lấy về 100 bản ghi, thì tổng lượt gọi và số dữ liệu lấy được sẽ là:

Thời gian

Lượt gọi API

Tổng số bản ghi

30 giây

150

15.000

1 phút

300

30.000

1 giờ

18.000

1.800.000

1 ngày

432.000

43.200.000

Rate Limit được kết hợp từ appId + businessId + API URL, nên ứng dụng của bạn có thể 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ì 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 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, sẽ không thể gọi bất kì API nào nữa.
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 updatedAtFrom - updatedAtTo).
Nhanh Open API không hỗ trợ mở khóa Rate Limit.
Khi vượt quá Rate Limit, bạn sẽ nhận được errorCode = ERR_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,
  "errorCode": "ERR_429",
  "message": "Your app exceeded the API Rate Limit",
  "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

NextChange log

Last updated 19 days ago

Was this helpful?