# 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 . * **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. | Khái niệm | Giải thích | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Tên App | Do bạn tự đặt, dùng để hiển thị cho user khi đăng nhập cấp quyền cho app của bạn | | Trạng thái | Dùng để bật tắt ứng dụng. Khi bạn đổi trạng thái sang Ngừng hoạt động, thì app sẽ không thể gọi API và không nhận được webhooks nữa | | Redirect URL | Là link trên hệ thống của bạn, sau khi user đăng nhập cấp quyền, Nhanh sẽ redirect về URL này, kèm accessCode, bạn dùng accessCode để đổi lấy accessToken (Đọc thêm các bước lấy accessCode và accessToken bên dưới) | | Bật webhooks | Dùng để bật tắt việc nhận webhooks, đọc thêm về webhooks [tại đây](https://github.com/nvndocs/docs-pos-openapi/blob/main/docs/webhooks/README.md) | | Webhooks callback URL | Là link trên hệ thống của bạn dùng để nhận webhooks Nhanh bắn sang | | Webhooks verify token |

Là 1 chuỗi kí tự do bạn tự định nghĩa, có độ dài từ 16 -> 128 kí tự, bao gồm cả số và chữ. Khi Nhanh.vn gửi webhooks data cho bạn, sẽ bao gồm cả webhooksVerifyToken giúp bạn xác minh request đến từ Nhanh.vn.
Chú ý: verify token sẽ được gửi kèm trong request body, không phải gửi theo header Authentication, đọc thêm về việc nhận webhooks tại đây

| ![Tạo ứng dụng](https://3587219317-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa2XHwSWeqjW0SgOYISkz%2Fuploads%2Fgit-blob-0114c4f607b6885d71f0e31231a93554735c41e9%2Fcreated_app2.png?alt=media) ## Lấy access token * Để lấy được accessToken, bạn cần thực hiện 3 bước sau: ![Sơ đồ 3 bước để lấy access token](https://3587219317-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa2XHwSWeqjW0SgOYISkz%2Fuploads%2Fgit-blob-0a02c0fdab0e4fda8ba3cf081e9abd5f7f13ccae%2FopenApi2.jpg?alt=media) ### 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

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.

| Param | Type | Description | | ---------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | version | string $$^{{\color{red}\*}}$$ | Phiên bản API (phiên bản hiện tại: 2.0). | | appId | int $$^{{\color{red}\*}}$$ | ID app. | | returnLink | string $$^{{\color{red}\*}}$$ | Sau khi người dùng đăng nhập và cấp quyền, Nhanh.vn sẽ redirect về URL này, kèm GET param accessCode. Chú ý returnLink bắt buộc chạy https, và phải được đăng ký trên [app của bạn](https://pos.open.nhanh.vn/apps). | ### Đă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.** {% hint style="info" %} **Chú ý:** Chú ý doanh nghiệp cần mở cài đặt cho phép kết nối Open API: Dùng tài khoản Giám đốc, đăng nhập vào trang quản trị, mục cài đặt chung > [Cài đặt Open API](https://nhanh.vn/setting/store/index#openAPIConfigArea) và bật "Cho phép kết nối Open API". Bật cài đặt mở Open API {% endhint %} * Giao diện khi user đăng nhập cấp quyền: ![Chọn quyền](https://3587219317-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa2XHwSWeqjW0SgOYISkz%2Fuploads%2Fgit-blob-a19221849eb1a1b642748bc96cb3a13df3b6e572%2Fpermissions2.png?alt=media) * 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 = thì Nhanh API sẽ redirect ngược lại về link ### Đổ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](https://open.nhanh.vn/apps), 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 + version 3.0) 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 curl --location --globoff 'https://pos.open.nhanh.vn/v3.0/app/getaccesstoken?appId={{appId}}' \ --header 'Content-Type: application/json' \ --data '{ "accessCode": "ACCESS CODE", "secretKey": "APP SECRET KEY" }' ``` **Response** ```json { "code": 1, "data": { "accessToken": "ACCESS TOKEN", "version": "3.0", "expiredAt": 1785603599, "businessId": 110668, "depotIds": [], "pageIds": [], "permissions": [] } } ``` | Key | Type | Description | | ----------- | --------- | -------------------------------------------------------------------------------------------------------------- | | code | int | 1 = success or 0 = failed | | messages | array | is an array of error messages if code = 0 | | accessToken | string | Access token (random from 128 to 256 characters) | | expiredAt | timestamp | Hạn sử dụng accessToken, VD: 1785603599 | | businessId | int | ID doanh nghiệp trên Nhanh.vn | | depotIds | array | Các kho hàng được phép thao tác. Nếu mảng rỗng hoặc bằng **All** thì sẽ được thao tác với toàn bộ các kho hàng | | pageIds | array | Các page được phép thao tác. Nếu mảng rỗng hoặc bằng **All** thì sẽ được thao tác với toàn bộ các page | | permissions | string | Các quyền được phép thao tác: Sản phẩm, đơn hàng... Do user chọn ở bước cấp quyền | #### Get access token v2 * App của bạn dùng accessCode này POST sang để lấy được accessToken và các permissions được cấp cho accessToken này. * Request params: | Param | Type | Description | | ---------- | ----------------------------- | -------------- | | version | string $$^{{\color{red}\*}}$$ | 2.0 | | appId | int $$^{{\color{red}\*}}$$ | Your appId | | accessCode | string $$^{{\color{red}\*}}$$ | Access code | | secretKey | string $$^{{\color{red}\*}}$$ | App secret key | ![Dùng accessCode lấy accessToken](https://3587219317-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa2XHwSWeqjW0SgOYISkz%2Fuploads%2Fgit-blob-9744ded2d6eeea98d595a5f11efb41a6f128353e%2Fpostman_get_access_token8_2.png?alt=media) * Response: | Key | Type | Description | | --------------- | --------- | -------------------------------------------------------------------------------------------------------- | | code | int | 1 = success or 0 = failed | | messages | array | is an array of error messages if code = 0 | | accessToken | string | Access token (random from 128 to 256 characters) | | expiredDateTime | string | Hạn sử dụng accessToken, VD: 2022-09-25 15:30:00, nên dùng key mới là expiredAt | | expiredAt | timestamp | Hạn sử dụng accessToken, VD: 1785603599 | | businessId | int | ID doanh nghiệp trên Nhanh.vn | | depotIds | array | Các kho hàng được phép thao tác theo token. Nếu mảng rỗng thì sẽ được thao tác với toàn bộ các kho hàng. | | permissions | array | Các quyền được phép thao tác: Sản phẩm, đơn hàng... Do user chọn ở bước cấp quyền | ## Kiểm tra access token * API này dùng để kiểm tra thông tin của accessToken: thời hạn, các quyền đã được cấp, các kho được thao tác, các page được thao tác. ```curl curl --location --globoff 'https://pos.open.nhanh.vn/v3.0/app/checkaccesstoken?appId={{appId}}&businessId={{businessId}}' \ --header 'Authorization: {{accessToken}}' \ --header 'Content-Type: application/json' \ --data '{ "secretKey": "APP SECRET KEY" }' ``` * Response sẽ giống với việc dùng accessCode đổi lấy accessToken. Xem mô tả tại [Get access token v3](#get-access-token-v3), mục Response. * **Chú ý**: API này chỉ hoạt động với các accessToken v3.0, nếu bạn dùng accessToken v2.0 gọi API này sẽ bị báo lỗi: ```json { "code": 0, "errorCode": "ERR_INVALID_DATA", "messages": [ "Invalid accessToken" ] } ```