Khởi tạo app

Register app

• Để bắt đầu sử dụng Nhanh API, bạn cần đăng kí tài khoản developer và tạo ứng dụng tại https://open.nhanh.vn.

• Chú ý: tài khoản developer chỉ dùng để quản trị ứng dụng trên open.nhanh.vn, không yêu cầu phải có quyền quản trị trên Nhanh.vn, tài khoản cấp quyền cho ứng dụng mới cần có quyền trên Nhanh.vn.

• Một ứng dụng có thể được dùng cho nhiều doanh nghiệp trên Nhanh.vn. Một doanh nghiệp trên Nhanh.vn cũng có thể dùng nhiều ứng dụng khác nhau. VD bạn có thể dùng 1 app thiết kế landing page, 1 app affiliate, cả 2 app đều đồng bộ đơn hàng về Nhanh.vn để xử lý tập trung.

• Khi người dùng (VD tài khoản giám đốc doanh nghiệp trên Nhanh.vn) cấp quyền cho ứng dụng của bạn, Nhanh API sẽ tạo ra 1 access token gắn với doanh nghiệp (businessId) và appId của bạn, kèm theo các permissions (quyền được thao tác với dữ liệu nào) do người dùng chọn ở bước đăng nhập cấp quyền cho app.

Lấy access token

• Để lấy được accessToken, bạn cần thực hiện 3 bước sau:

Lấy access code

• Bước 1: Ứng dụng của bạn cần chuyển tới trang đăng nhập của Nhanh.vn https://nhanh.vn/oauth?version=API_VERSION&appId=YOUR_APPID&returnLink=YOUR_RETURN_LINK

  Chú ý: returnLink phải là 1 tên miền chạy https và nằm trong danh sách Redirect URL của ứng dụng.

Đăng nhập cấp quyền

• Bước 2: Người dùng sẽ đăng nhập và chọn các quyền được cấp cho ứng dụng.

• Giao diện khi user đăng nhập cấp quyền:

• Các quyền của token sẽ tương ứng với các quyền được thao tác trên Nhanh.vn của tài khoản đang lấy token. VD bạn dùng tài khoản Giám đốc sẽ có thể chọn toàn bộ quyền, bạn dùng tài khoản nhân viên chỉ đang được thao tác với "Danh sách sản phẩm", thì ở bước cấp quyền, tài khoản này cũng chỉ chọn được "Danh sách sản phẩm" và accessToken do tài khoản này tạo ra cũng sẽ chỉ gọi được "/api/product/search" mà không dùng được với các API khác.

• Khi người dùng chọn "Đồng ý", Nhanh.vn sẽ redirect ngược lại về YOUR_RETURN_LINK kèm theo mã accessCode. VD bên trên nếu YOUR_RETURN_LINK = https://example.org/nhanh/auth thì Nhanh API sẽ redirect ngược lại về link https://example.org/nhanh/auth?accessCode=

Đổi access token

• Bước 3: Gọi API để đổi accessCode lấy accessToken. Chú ý có sự khác biệt giữa v2.0 và v3.0, bạn cần dùng đúng phiên bản bên dưới:

  • accessCode: chỉ có hạn 10 phút, và sẽ hết hạn ngay sau khi lấy accessToken thành công.

  • secretKey: Vào Danh sách app, click vào tên app, vào trang chi tiết để lấy secretKey.

  • accessToken: có hạn sử dụng 1 năm từ thời điểm được tạo. Hiện Nhanh chưa hỗ trợ refresh token. Hệ thống của bạn cần có cơ chế cảnh báo người dùng để đăng nhập cấp quyền và lấy token mới khi gần hết hạn token cũ.

Get access token v3

• Chú ý: v3.0 chỉ duy trì 1 accessToken cho 1 appId + businessId. Khi bạn tạo ra 1 accessToken mới, thì accessToken cũ (cùng appId + businessId) sẽ chỉ còn hiệu lực thêm 15 phút, sau đó sẽ không thể dùng accessToken cũ nữa.

• Request

curl --location --globoff 'https://pos.open.nhanh.vn/v3.0/app/getaccesstoken?appId={{appId}}&businessId={{businessId}}' \
--header 'Content-Type: application/json' \
--data '{
    "accessCode": "ACCESS CODE",
    "secretKey": "APP SECRET KEY"
}'

• Response

{
  "code": 1,
  "data": {
    "accessToken": "ACCESS TOKEN",
    "expiredAt": 1785603599,
    "businessId": 110668,
    "depotIds": [],
    "pageIds": [],
    "permissions": []
  }
}

Get access token v2

• App của bạn dùng accessCode này POST sang https://pos.open.nhanh.vn/api/oauth/access_token để lấy được accessToken và các permissions được cấp cho accessToken này.

• Request params:

• Response: