Giới thiệu v3.0

v3.0 Alpha ưu tiên mở API cho Vpage.nhanh.vn
Các API cho POS đang được cập nhật, dự kiến bản Beta sẽ ra mắt vào ngày 2025-08-20.

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. Pagiantor thường có 3 field chính:
- size (int): Số lượng bản ghi trên 1 trang. Tối đa không quá 100.
- sort (array): Các tiêu chí sắp xếp, xem mô tả tại tài liệu của từng API.
- next (int, string hoặc array): Dùng để gọi dữ liệu cho trang tiếp theo.
  - Khi bạn gọi API cho trang đầu tiên, thì bạn không cần truyền next, sau đó khi nhận được response, nếu response có trả về paginator.next, thì request tiếp theo bạn cần truyền next này lên để lấy dữ liệu cho trang tiếp theo.
  - 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.
Reponse:
- totalItems: Tổng số bản ghi. Giá trị này chỉ trả về ở trang đầu tiên. Các trang tiếp theo sẽ không có giá trị này.
- next: Giá trị phân trang cho trang tiếp theo.

Postman sample

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
  }
]'

Postman collection

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

Ở 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

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

Nhanh Open API sẽ phản hồi mã lỗ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ể có thêm data hoặc warning

{
    "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ư:
- erroCode: mã lỗi. Xem chi tiết mã lỗi chung, mã lỗi riêng của POS hoặc của 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_EXCEEDED_RATE_LIMIT",
  "messages": "Your app exceeded the API Rate Limit"
}

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_BUSINESS_ID

Invalid businessId

ERR_INVALID_ACCESS_TOKEN

Invalid access token

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_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_EXCEEDED_RATE_LIMIT

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

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

Mới: Trạng thái này dùng để bán hàng ở cửa hàng offline

Đ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

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 đó

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

Đã đóng gói

Đang đóng gói

Chờ thu gom

Đơn mới

Đang xác nhận

Đã xác nhận

Chờ khách xác nhận

Hãng vận chuyển hủy đơn

Đang chuyển

Thành công

Thất bại

Khách hủy

Hệ thống hủy

Hết hàng

Đang chuyển hoàn

Đã chuyển hoàn

Đổi kho xuất hàng

Xác nhận hoàn

Order Reason
Lý do theo trạng thái đơn hàng

Reason

Description

Đặt nhầm sản phẩm

Phí vận chuyển cao

Không muốn chuyển khoản

Đơn trùng

Không gọi được khách

Hết hàng

Chờ chuyển khoản

Khách không thích sản phẩm

Khách không hài lòng về nhân viên vận chuyển

Giao hàng chậm

Đã mua sản phẩm tại cửa hàng

Sai địa chỉ người nhận

Khách không muốn mua nữa

Lý do khác

Không liên hệ được với người gửi

Người gửi không bán hàng Online / Ngoại tỉnh

Người gửi không bàn giao hàng cho hãng vận chuyển

Hãng vận chuyển lấy hàng muộn

Sai địa chỉ kho lấy hàng

Hãng vận chuyển làm mất hàng

Người gửi tự vận chuyển

Người gửi không xử lý đơn hàng

Sai giá sản phẩm

Khách đi vắng (sẽ giao hàng vào hôm 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

Loại nhập kho

Loại xuất kho

Kiểu XNK:

Mode (int)

Description

Kiểu giao hàng

Kiểu bán lẻ

Kiểu chuyển kho

Kiểu quà tặng ở hóa đơn bán lẻ

Kiểu nhà cung cấp

Kiểu bán sỉ

Kiểu kiểm kho

Kiểu khác

Kiểu quà tặng ở đơn hàng

Accounting

Các thuật ngữ về kế toán

Loại bút toán

Type

Name

Báo nợ (Rút tiền)

Báo có (Nộp tiền)

Phiếu thu

Phiếu chi

Phiếu trả hàng

Phiếu bán hàng

Khác

Phiếu nhập

Phiếu xuất

Kết chuyển

Kiểu bút toán

Mode

Name

Nhập nhà cung cấp

Xuất trả nhà cung cấp

Bán hàng

Hàng trả lại

Bán sỉ

Trả lại bán sỉ

Nhập máy cũ

Bảo hành

Xuất linh kiện

Chuyển quỹ

Hạch toán trả góp

Công nợ đầu kì

Đơn hàng

Đơn hàng trả lại

Nhập nhà cung cấp VAT

Xuất nhà cung cấp VAT

XNK khác

Thu hộ trả góp

Nhập VAT

Xuất VAT

Xác nhận nhận tiền thanh toán

Xác nhận chi tiền thanh toán vận chuyển

Phiếu nhập quà tặng

Phiếu xuất quà tặng

NextChange log

Last updated 1 hour ago