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)

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"}
    }
}'
  • 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

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

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ả

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 [email protected] để đượ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

Last updated