Lấy access token Nhanh.vn: tạo app, App ID, Secret Key và gia hạn

Chào anh em! Cài plugin nối Nhanh.vn với WooCommerce, hay nhận việc tích hợp Open API cho khách, bước chặn ngay cửa là access token Nhanh.vn: không có nó thì website không đọc được sản phẩm, tồn kho, cũng không nhận được webhook nào. Token này không phải một dãy ký tự có sẵn để copy trong tài khoản. Nó sinh ra qua ba việc: tài khoản Giám đốc bật Open API, tài khoản developer tạo app trên open.nhanh.vn, rồi người có quyền đăng nhập cấp quyền cho app. Bài này đi từng bước cho cả chủ shop lẫn dev, từ bật Open API tới gia hạn token.

Plugin ở mục làm trong WooCommerce là sản phẩm mình viết và bảo trì, kết nối bằng Open API của Nhanh.vn nên cũng lấy token theo đúng luồng cấp quyền trong bài. Những gì về token phía Nhanh.vn (hạn 1 năm, accessCode sống 10 phút, các mã lỗi) mình lấy từ tài liệu chính thức tại developers.nhanh.group, đọc ngày 11/10/2026, còn form tạo app thì xem trên open.nhanh.vn cùng ngày. Nhanh đổi giao diện thì tên nút có thể lệch chút, anh em cứ theo thứ tự các bước.

Access token Nhanh.vn là gì, sống bao lâu?

accessToken là chuỗi 128–256 ký tự Nhanh tạo ra khi một tài khoản của doanh nghiệp đồng ý cấp quyền cho app. Nó gắn với ba thứ: app (appId), doanh nghiệp (businessId), và các quyền, kho được chọn lúc cấp. Mấy điều cần nhớ:

• ⚠️ Hạn 1 năm kể từ lúc tạo. Nhanh chưa hỗ trợ refresh token nên không có cách gia hạn ngầm: tới hạn là phải đăng nhập cấp quyền lại.
• Với API v3, mỗi cặp app + doanh nghiệp chỉ có một token. Cấp lại thì token cũ còn hiệu lực thêm 15 phút rồi thôi.
• Quyền và kho cố định lúc cấp. Sau này cần thêm quyền (ví dụ danh sách đơn hàng) hay thêm kho thì phải cấp quyền lại.
• Token đi theo phiên bản: lấy token v2 gọi API v3 sẽ bị từ chối.
• Token mở được dữ liệu của shop: chỉ để ở máy chủ, không dán vào nhóm chat, không gửi ảnh chụp chưa che.

Ai làm bước nào?

• Tài khoản Giám đốc trên Nhanh.vn bật Cho phép kết nối Open API, và thường cũng là người cấp quyền vì chọn được mọi quyền.
• Tài khoản developer trên open.nhanh.vn dùng để tạo, sửa app; tài liệu ghi tài khoản này chỉ để quản trị app, không cần quyền gì trên dữ liệu shop, nên người làm web giữ cũng được.
• Người cấp quyền phải đăng nhập được nhanh.vn và có quyền với dữ liệu website cần dùng; nếu là tài khoản nhân viên thì chỉ chọn được những quyền tài khoản đó đang có.

Shop nhỏ tự làm thì một người làm cả ba vai cũng được.

Bước 1: bật Cho phép kết nối Open API trên Nhanh.vn

1. Đăng nhập nhanh.vn bằng tài khoản Giám đốc.
2. Vào Cài đặt → Cài đặt chung, tìm mục Cài đặt Open API (đường dẫn tài liệu đưa: nhanh.vn/setting/store/index).
3. Bật “Cho phép kết nối Open API”.

Chưa bật thì mọi lời gọi API trả ERR_BUSINESS_NOT_ENABLE_API. Mục Cài đặt Open API cũng là nơi sau này xem app nào đang kết nối và token còn hạn tới ngày nào.

Bước 2: tạo app trên open.nhanh.vn

open.nhanh.vn là trang quản trị app. Đăng ký hoặc đăng nhập tài khoản developer, vào Danh sách app rồi bấm Thêm mới:

Kho plugin của tôi

DevVN Popup – Popup cho website WordPress

DevVN – Sộp pe Importer – Nhập sản phẩm, đánh giá từ Shopee sang WooCommerce chỉ với 1 click

DevVN Frame Designer – Cho khách tự thiết kế khung ảnh ngay trên trang sản phẩm WooCommerce

DevVN AI Room Visualizer – Cho khách xem sản phẩm ngay trong chính căn phòng của họ bằng AI

• Ô Tên App là tên hiện cho người cấp quyền thấy, đặt dễ nhận như “Website WooCommerce”.
• Để Trạng thái là Đang hoạt động, vì chuyển sang Ngừng hoạt động là app không gọi API, không nhận webhook nữa.
• Ô Redirect URL là đường dẫn trên website để Nhanh trả người dùng về kèm accessCode, bắt buộc https; dùng plugin của mình thì đây là đường dẫn plugin đưa ở bước 3 trong tab Nhanh.vn, dạng https://ten-mien-cua-ban/wp-json/nhanhvn/v1/return_url/.
• Nên chọn Bật webhooks và các ô đi kèm để website nhận tồn kho, sản phẩm, đơn hàng.
• Bấm Lưu.

Form có dòng đỏ nhắc: app phải được cấp quyền, lấy được accessToken thì mới có sự kiện webhook bắn về. Ý nghĩa từng sự kiện và cách điền phần webhook có ở bài webhook Nhanh.vn.

Bước 3: lấy App ID và Secret Key của app Nhanh.vn

• App ID hiện ngay trên thẻ của app ở trang Danh sách app.
• Theo tài liệu, Secret Key nằm ở trang chi tiết app, mở bằng cách bấm vào tên app trong Danh sách app.
• 🚨 Secret Key cộng với một accessCode là đủ để đổi ra token. Giữ như mật khẩu: không gửi qua nhóm chat, không để trong mã JavaScript, không commit lên Git.

Bước 4: cấp quyền, lấy accessCode rồi đổi accessToken

Đây là bước sinh ra token. Luồng theo tài liệu:

1. Website chuyển người dùng tới trang đăng nhập của Nhanh: https://nhanh.vn/oauth?appId=APP_ID&returnLink=REDIRECT_URL. returnLink phải chạy https và nằm trong Redirect URL của app.
2. Người dùng đăng nhập, chọn quyền và kho cho app, bấm Đồng ý. Nên chọn đủ quyền cho các việc website cần (sản phẩm, tồn kho, đơn hàng, khách hàng…) và đủ kho: thiếu kho thì số tồn lấy về cũng thiếu.
3. Nhanh trả về Redirect URL kèm ?accessCode=…. accessCode chỉ sống 10 phút và hết hiệu lực ngay khi đổi token thành công.
4. Máy chủ website đổi accessCode cùng Secret Key lấy accessToken. Với v3 là API getaccesstoken, mẫu curl theo tài liệu:

curl --location 'https://pos.open.nhanh.vn/v3.0/app/getaccesstoken?appId=YOUR_APP_ID' \
  --header 'Content-Type: application/json' \
  --data '{
    "accessCode": "ACCESS_CODE_VUA_NHAN",
    "secretKey": "YOUR_SECRET_KEY"
  }'

Phản hồi thành công có "code": 1 và data gồm accessToken, expiredAt (thời điểm hết hạn, Unix timestamp), businessId (ID doanh nghiệp), depotIds (kho được thao tác, rỗng là toàn bộ kho), pageIds, permissions. Lưu luôn expiredAt để nhắc gia hạn. Code WordPress cho trọn luồng này (nút kết nối, route nhận accessCode, lưu token) có ở bài tích hợp Nhanh.vn Open API.

Làm trong plugin WooCommerce: bước 9 Get accessCode

Dùng plugin kết nối Nhanh.vn với WooCommerce thì việc đổi token ở bước 4 do plugin lo, bạn chỉ bấm:

1. Vào WooCommerce → Nhanh.vn, tab Nhanh.vn. Trang liệt kê sẵn 9 bước, kèm Redirect URL và Webhooks callback URL của site để dán vào app.
2. Ở dòng “Bật webhooks > Chọn version”, chọn Version 3 (cài mới plugin để sẵn Version 2).
3. Nhập Business ID (ID doanh nghiệp trên Nhanh.vn), App ID, Secret Key rồi bấm Lưu thay đổi.
4. Lưu xong, bước 9 hiện link Get accessCode. Bấm vào, đăng nhập Nhanh.vn, chọn quyền và kho rồi đồng ý.
5. Nhanh trả về website, plugin tự đổi accessCode lấy accessToken. Thành công thì hiện khung “Kết nối thành công!” kèm ID doanh nghiệp trên Nhanh.vn, dòng “Token hết hiệu lực vào” và danh sách quyền truy cập.

Đoạn tạo app, nhập App ID và cấp quyền Open API có trong video dưới, bắt đầu ở giây 0:31.

• Các tab Kho hàng, Vận chuyển, Webhook, Đồng bộ, Tự động đăng đơn chỉ hiện sau khi đã có accessToken.
• Đối chiếu ID doanh nghiệp trong khung xanh với ô Business ID để chắc đã nối đúng doanh nghiệp.
• Lỡ bấm huỷ ở trang cấp quyền thì plugin báo “Bạn đã HUỶ cấp quyền truy cập”: bấm Get accessCode lại và chọn đồng ý.
• Token hết hạn thì khung chuyển sang dòng đỏ “Token HẾT HIỆU LỰC”, nhắc bấm Get accessCode tại bước 9. Plugin không tự gia hạn token.

Chưa rõ ID doanh nghiệp hay vướng ở bước nào thì cứ nhắn mình: plugin có hỗ trợ cài đặt miễn phí. Hướng dẫn kèm ảnh có ở trang kết nối API Nhanh.vn trong tài liệu plugin.

Kiểm tra token còn hạn, có quyền gì

• Chủ shop vào Nhanh.vn → Cài đặt → Cài đặt chung → Cài đặt Open API; theo tài liệu, ở đây xem được app còn kết nối không và hạn token tới ngày nào.
• Dùng plugin thì xem dòng “Token hết hiệu lực vào” trong tab Nhanh.vn.
• Dev gọi API checkaccesstoken, kết quả trả về giống lúc đổi token: hạn, quyền, kho, page được thao tác.

curl --location 'https://pos.open.nhanh.vn/v3.0/app/checkaccesstoken?appId=YOUR_APP_ID&businessId=YOUR_BUSINESS_ID' \
  --header 'Authorization: YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "secretKey": "YOUR_SECRET_KEY" }'

Gia hạn token trước khi hết hạn

Không có refresh token nên “gia hạn” chính là cấp quyền lại để lấy token mới: làm lại bước 4, hoặc bấm Get accessCode trong plugin. Vài kinh nghiệm:

• Ghi ngày hết hạn vào lịch, đặt nhắc trước khoảng một tháng. Token hết hạn thì website không gọi được API nữa, và theo tài liệu, webhook của doanh nghiệp đó cũng ngừng về.
• Dùng tài khoản đủ quyền, chọn lại đủ quyền và kho như lần trước: token mới chỉ có những gì bạn chọn ở lần cấp này.
• Với v3, token cũ còn chạy thêm 15 phút sau khi có token mới, nên đổi token không làm gián đoạn, miễn website lưu token mới ngay (plugin tự làm việc này).
• Cấp lại cũng là cách thêm quyền, thêm kho khi shop mở chi nhánh mới.

Dev tự viết thì nên để máy nhắc thay người. Đoạn dưới chạy mỗi ngày bằng WP-Cron, gọi checkaccesstoken lấy hạn rồi email admin ở các mốc 30, 14, 7, 3, 1 ngày trước hạn; token không còn dùng được thì email báo cấp quyền lại. Cấu hình trong wp-config.php:

Mẫu website nổi bật của tôi

Mẫu website bán trái cây, thực phẩm tươi

Mẫu website cửa hàng kính mắt

Mẫu website bán vật tư kim khí

Mẫu website bánh kem mới nhất

define( 'DEVVN_NHANH_APP_ID', 'YOUR_APP_ID' );
define( 'DEVVN_NHANH_BUSINESS_ID', 'YOUR_BUSINESS_ID' );
define( 'DEVVN_NHANH_SECRET_KEY', 'YOUR_SECRET_KEY' );
define( 'DEVVN_NHANH_ACCESS_TOKEN', 'YOUR_ACCESS_TOKEN' );

define( 'DEVVN_NHANH_TOKEN_HOOK', 'devvn_nhanh_check_token' );
define( 'DEVVN_NHANH_REMIND_DAYS', array( 30, 14, 7, 3, 1 ) );
define( 'DEVVN_NHANH_TIMEOUT', 15 );

/**
 * accessToken đang dùng; lưu token ở chỗ khác (option, bảng riêng) thì sửa hàm này.
 *
 * @return string
 */
function devvn_nhanh_access_token() {
	return (string) DEVVN_NHANH_ACCESS_TOKEN;
}

/**
 * Hẹn lịch kiểm hạn token mỗi ngày; chỉ kiểm ở trang quản trị cho nhẹ trang khách.
 *
 * @return void
 */
function devvn_nhanh_schedule_token_check() {
	if ( ! wp_next_scheduled( DEVVN_NHANH_TOKEN_HOOK ) ) {
		wp_schedule_event( time() + HOUR_IN_SECONDS, 'daily', DEVVN_NHANH_TOKEN_HOOK );
	}
}
add_action( 'admin_init', 'devvn_nhanh_schedule_token_check' );

/**
 * Gọi checkaccesstoken, trả số ngày còn lại của token.
 *
 * @return int|WP_Error Số ngày còn lại, hoặc lỗi mang mã errorCode của Nhanh.vn.
 */
function devvn_nhanh_token_days_left() {
	$url = add_query_arg(
		array(
			'appId'      => DEVVN_NHANH_APP_ID,
			'businessId' => DEVVN_NHANH_BUSINESS_ID,
		),
		'https://pos.open.nhanh.vn/v3.0/app/checkaccesstoken'
	);
	$res = wp_remote_post(
		$url,
		array(
			'timeout' => DEVVN_NHANH_TIMEOUT,
			'headers' => array(
				'Authorization' => devvn_nhanh_access_token(),
				'Content-Type'  => 'application/json',
			),
			'body'    => wp_json_encode( array( 'secretKey' => DEVVN_NHANH_SECRET_KEY ) ),
		)
	);
	if ( is_wp_error( $res ) ) {
		return $res;
	}
	$json = json_decode( wp_remote_retrieve_body( $res ), true );
	if ( ! isset( $json['code'], $json['data']['expiredAt'] ) || 1 !== (int) $json['code'] ) {
		$code = isset( $json['errorCode'] ) ? (string) $json['errorCode'] : 'nhanh_check_failed';
		return new WP_Error( $code, 'Không kiểm được accessToken Nhanh.vn.' );
	}
	return (int) floor( ( (int) $json['data']['expiredAt'] - time() ) / DAY_IN_SECONDS );
}

/**
 * Email admin khi token sắp hết hạn hoặc không còn dùng được.
 *
 * @return void
 */
function devvn_nhanh_check_token() {
	$days = devvn_nhanh_token_days_left();
	$to   = get_option( 'admin_email' );
	if ( is_wp_error( $days ) ) {
		if ( in_array( $days->get_error_code(), array( 'ERR_INVALID_ACCESS_TOKEN', 'ERR_INVALID_VERSION' ), true ) ) {
			wp_mail( $to, 'Token Nhanh.vn không còn dùng được', 'Mã lỗi ' . $days->get_error_code() . '. Cần đăng nhập Nhanh.vn cấp quyền lại cho app.' );
		}
		return;
	}
	if ( in_array( $days, DEVVN_NHANH_REMIND_DAYS, true ) ) {
		wp_mail( $to, sprintf( 'Token Nhanh.vn còn %d ngày', $days ), 'Đăng nhập Nhanh.vn cấp quyền lại cho app để lấy token mới trước khi hết hạn.' );
	}
}
add_action( DEVVN_NHANH_TOKEN_HOOK, 'devvn_nhanh_check_token' );

• Lịch hẹn ở admin_init nên không thêm truy vấn nào vào trang khách xem; cron chạy mỗi ngày một lần, không ảnh hưởng rate limit.
• Lỗi mạng thì bỏ qua, hôm sau kiểm lại. Token hỏng (ERR_INVALID_ACCESS_TOKEN, ERR_INVALID_VERSION) thì email mỗi ngày tới khi cấp quyền lại.
• Site tắt WP-Cron thì cần cron hệ thống gọi wp-cron.php, không thì email không bao giờ tới.
• Code khác đã khai các hằng số này thì đừng define lại; token đang lưu trong option thì sửa devvn_nhanh_access_token() đọc từ option đó.

Lỗi hay gặp khi lấy token

Rẽ nhánh theo errorCode, đừng so câu chữ trong thông báo. Khi nhờ người khác xem lỗi, che accessToken, Secret Key trước khi gửi ảnh hay log.

Câu hỏi thường gặp

Token có tự gia hạn không?

Không. Nhanh chưa hỗ trợ refresh token, và plugin của mình cũng không tự gia hạn. Hết 1 năm là phải cấp quyền lại để lấy token mới.

Hai website dùng chung một app được không?

Theo tài liệu, một app dùng được cho nhiều doanh nghiệp, một doanh nghiệp cũng dùng được nhiều app. Nhưng với v3, mỗi cặp app + doanh nghiệp chỉ có một token: hai website của cùng doanh nghiệp mà dùng chung một app thì lần cấp quyền sau làm token của website kia hết hiệu lực sau 15 phút. Mỗi website nên có app riêng.

Chuyển từ API v2 sang v3 có phải lấy token lại không?

Có. Token v2 gọi API v3 sẽ nhận ERR_INVALID_VERSION. Với plugin: chọn Version 3, Lưu thay đổi, bấm Get accessCode; nhớ đổi luôn Webhooks version trong app sang 3.0, vì form open.nhanh.vn ghi version 2.0 “Ngừng hỗ trợ sau 31-08-2026”.

Nhân viên cấp quyền thay Giám đốc được không?

Được, nhưng nhân viên chỉ chọn được những quyền mình đang có trên Nhanh. Sau này nhân viên được phân thêm quyền thì token cũ vẫn không có, phải cấp lại.

Lấy token xong là tới các bước còn lại: đồng bộ kho, bật webhook, đồng bộ sản phẩm. Thứ tự đầy đủ có ở bài kết nối Nhanh.vn với website.

Vướng ở bước nào cứ để lại bình luận, nhớ che App ID, Secret Key và token trước khi dán ảnh nhé. 😄