Giới thiệu v3.0

NhanhAPI version 3.0 Beta

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. 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 (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.
  - 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 không thỏa mãn điều kiện filters), nhưng vẫn có next, nghĩa là vẫn còn dữ liệu ở trang tiếp theo, bạn vẫn cần lấy tiếp dữ liệu next.
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

NhanhAPI 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_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_PAGE_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.

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.

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

NextChange log

Last updated 4 days ago