Lấy API token GHN và ShopId: từng bước, IP tin cậy và lỗi 401

Chào anh em! Cài plugin Giao Hàng Nhanh (GHN) xong, trang cài đặt hỏi ngay một ô Token Key. Lên Google tìm thì mỗi bài chỉ một chỗ: bài bảo vào mục tích hợp, bài bảo vào Developer Portal, bài còn nhắc trang 5sao cũ. Mình vừa vào lại tài khoản GHN thật ngày 11/10/2026 để kiểm từng bước. Đọc xong, anh em tự lấy được API token GHN với ShopId rồi dán vào WooCommerce cho chạy, gặp lỗi 401 cũng biết đường sửa.

Các bước lấy token bên dưới đi theo giao diện khachhang.ghn.vn (kiểm ngày 11/10/2026) và tài liệu chính thức tại developer.ghn.vn (đọc tháng 10/2026). Plugin ở phần dán token là sản phẩm mình viết và bảo trì. GHN đổi giao diện thì tên nút có thể lệch chút, anh em cứ theo ý các bước.

Token dùng để làm gì?

Có token, website hay phần mềm gọi được API của GHN thay mặt shop: lấy danh sách cửa hàng, tính phí, tạo đơn, in vận đơn, huỷ đơn. Mọi API của GHN đều cần header Token; API nào làm việc trên một cửa hàng cụ thể thì cần thêm header ShopId (số nguyên) để biết đang thao tác trên cửa hàng nào. Ô Token Key trong plugin cũng chính là chuỗi Token API trong tài khoản GHN.

Ai cầm token là gọi được API trên tài khoản của bạn, kể cả tạo và huỷ vận đơn. Tài liệu GHN dặn giữ token như mật khẩu; phần bảo mật mình tách riêng một mục bên dưới.

Cách lấy API token GHN trên khachhang.ghn.vn

Đoạn lấy token có trong video dưới, bắt đầu ở giây 0:13.

Đây là đường mình đi trên tài khoản thật ngày 11/10/2026:

Có thể bạn cần

Gửi Zalo ZNS bằng link API

Plugin GHN cho WooCommerce: kết nối Giao Hàng Nhanh, tính phí ship & in vận đơn

[Addon] Đăng đơn tự động/hàng loạt lên GHN

1. Đăng nhập khachhang.ghn.vn bằng tài khoản shop. Chưa có tài khoản thì đăng ký trước. Các bước đăng ký có ở bài đăng ký tài khoản GHN.
2. Bấm vào tên tài khoản ở góc trên bên trái. Trang Thông tin tài khoản mở ra với các tab Thông tin cá nhân, Hóa đơn cước phí giao hàng, Thông tin ngân hàng và Bảo mật.
3. Chọn tab Bảo mật, tìm mục Token API & IP tin cậy rồi bấm Quản lý.
4. Một tab mới mở trang sso.ghn.vn. Ô Token API đang hiện dạng dấu chấm. Bấm biểu tượng con mắt để xem token; theo tài liệu GHN, hệ thống sẽ hỏi mã OTP gửi về số điện thoại của tài khoản.
5. Token hiện ra thì sao chép và dán thẳng vào chỗ cần dùng. Đừng lưu tạm vào ghi chú điện thoại hay nhóm chat.

Cùng tab Bảo mật còn các mục Mật khẩu, Mã khóa (Passkey), Tài khoản liên kết, Xác nhận OTP khi cập nhật COD và Quản lý phiên đăng nhập. Lấy token thì không cần đụng tới chúng.

Cách thứ hai: Developer Portal (theo tài liệu GHN)

Trang Lấy Token trong tài liệu GHN mô tả thêm một đường qua Developer Portal, hợp với người làm API:

1. Vào developer.ghn.vn (môi trường thử là developer.ghn.dev), bấm Đăng nhập ở góc trên bên phải, đăng nhập bằng số điện thoại và bước xác thực; có thêm lựa chọn Google, Apple.
2. Mở menu tài khoản ở góc trên bên phải, chọn Quản lý token.
3. Ở thẻ Token API, bấm biểu tượng con mắt, nhập mã OTP 6 số gửi về số điện thoại tài khoản, rồi bấm biểu tượng sao chép.

Đường qua khachhang.ghn.vn mình đã kiểm trên tài khoản thật, đường qua Developer Portal mình viết theo tài liệu. Đi đường nào thì shop cũng tự lấy token, không cần nhờ GHN cấp. Vài trang API của GHN vẫn còn chữ token “do GHN cấp”, anh em đừng vì thế mà ngồi chờ.

Danh sách IP tin cậy: bật thì phải có IP máy chủ website

Ngay dưới ô Token API là mục Danh sách IP được phép sử dụng, có nút Thêm địa chỉ IP. Mặc định danh sách trống và giao diện ghi “Mọi IP đều có thể truy cập API”. Theo tài liệu GHN, danh sách trống thì mọi IP gọi được; khi danh sách đã có IP thì chỉ những IP đó gọi được, gọi từ IP khác GHN trả HTTP 401.

⚠️ Bẫy hay gặp: thêm IP máy tính ở nhà hay văn phòng vào danh sách. Website gọi API từ máy chủ hosting, không phải từ máy tính của bạn, nên ngay sau đó trang thanh toán mất phí ship, bấm tạo vận đơn báo lỗi. Muốn dùng danh sách IP thì:

• Hỏi nhà cung cấp hosting IP mà máy chủ dùng khi gọi ra ngoài (outgoing IP). Có hosting gọi ra bằng IP khác với IP trỏ tên miền, nên hỏi cho chắc.
• Thêm IP đó vào danh sách, lưu, rồi thử lại trên website theo cách kiểm tra ở phần dán token bên dưới.
• Đổi hosting, đổi VPS thì sửa danh sách trước khi chuyển tên miền sang máy mới.
• Có website chạy thử trên máy chủ khác mà dùng chung token thì thêm luôn IP máy chủ đó.

Danh sách IP là lớp bảo vệ đáng bật: lỡ token bị lộ, người khác gọi từ máy của họ cũng bị chặn. Có điều bật rồi thì phải nhớ là nó đang bật.

ShopId GHN lấy ở đâu?

Một tài khoản GHN có thể có nhiều cửa hàng (địa chỉ lấy hàng), mỗi cửa hàng một ShopId riêng. Các API như tính phí, tạo đơn, in, huỷ đều cần header ShopId để biết hàng lấy ở cửa hàng nào. Tài liệu GHN chỉ ghi ShopId “xem trong thông tin tài khoản”. Cách chắc chắn là hỏi thẳng API: gọi GET /shiip/public-api/v2/shop/all, API này chỉ cần Token.

curl -s 'https://online-gateway.ghn.vn/shiip/public-api/v2/shop/all' \
  -H 'Token: YOUR_TOKEN'

Kết quả nằm trong data.shops: mỗi phần tử có _id (đây là ShopId), tên cửa hàng, cùng district_id và ward_code của địa chỉ lấy hàng. Token môi trường thử thì đổi tên miền thành dev-online-gateway.ghn.vn.

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

Dự án website bán laptop surface

Mẫu website bán thiết bị nhà bếp, nhà tắm, thiết bị vệ sinh tuyệt đẹp

Mẫu website bán hàng giống shopee

Mẫu website bán đồ gỗ, đồ thờ, đồ phòng thủy

• ⚠️ ID khách hàng (theo ghn.vn, xem ở mục thông tin cá nhân khi bấm tên shop ở menu trái) là mã tài khoản, không dùng cho header ShopId được.
• Gửi ShopId không thuộc tài khoản của token, API trả lỗi CLIENT_NOT_OWNER_OF_SHOP.
• Dùng plugin GHN của mình thì không phải nhập ShopId, vì plugin tự lấy danh sách cửa hàng theo token khi bạn bấm “Đồng bộ kho hàng từ GHN” rồi gửi ShopId của kho đang dùng trong mỗi request.

Token Test (staging) khác token thật

GHN có hai môi trường API: Production (online-gateway.ghn.vn) tạo đơn thật, Staging (dev-online-gateway.ghn.vn) để chạy thử, trang chủ tài liệu GHN ghi gọi thử ở staging “không phát sinh đơn thật”. Hai môi trường là hai tài khoản riêng, hai token riêng:

• Tài khoản staging đăng ký ở 5sao.ghn.dev (trang này chuyển sang trang đăng nhập staging sso.ghn.dev). Token staging lấy ở developer.ghn.dev theo tài liệu GHN.
• Token staging không dùng được cho Production, và ngược lại.
• Đừng nhầm tên: 5sao.ghn.vn là tên cũ của web khách hàng (nay là khachhang.ghn.vn), còn 5sao.ghn.dev là môi trường thử.

Plugin có sẵn ô Môi trường cho chuyện này: Product dùng tài khoản khachhang.ghn.vn, Test dùng tài khoản 5sao.ghn.dev. Chọn môi trường nào thì dán token của đúng môi trường đó.

Dán token vào WooCommerce

Với plugin GHN cho WooCommerce, phần kết nối tài khoản chỉ có một ô token:

1. Vào WooCommerce → Cài đặt GHN, tab Cài đặt GHN.
2. Ô Môi trường: chọn Product – Tài khoản tại khachhang.ghn.vn để chạy thật, hoặc Test – Tài khoản tại 5sao.ghn.dev để thử.
3. Dán token vào ô Token Key, bấm Lưu thay đổi.
4. Sang tab Cửa hàng/Kho, bấm Đồng bộ kho hàng từ GHN để kéo danh sách cửa hàng về, rồi tích Đặt làm kho chính cho kho hay gửi hàng.

Kiểm tra nhanh: thêm một sản phẩm có cân nặng vào giỏ, ra trang thanh toán chọn Tỉnh/Thành và Phường/Xã. Hiện phí GHN là token, môi trường và kho đều đúng. Không thấy phí GHN, hoặc chỉ thấy dòng “Phí vận chuyển sẽ báo sau.”, nghĩa là GHN chưa trả được giá: xem lại token, danh sách IP, cân nặng sản phẩm và license plugin đã kích hoạt chưa.

⚠️ Plugin lưu danh sách kho theo token và chỉ làm mới khi bạn bấm Đồng bộ. Đổi token hay đổi môi trường thì bấm lại Đồng bộ kho hàng từ GHN. Chi tiết từng ô có ở trang kết nối API GHN và kho hàng trong tài liệu plugin.

Tự code thì token đi trong header Token, ShopId trong header ShopId, gửi tới đúng tên miền của môi trường. Hàm gọi API, tính phí và tạo đơn bằng PHP có ở bài tích hợp API GHN.

Giữ token GHN an toàn

• Token không được nằm trong JavaScript chạy ở trình duyệt, vì ai mở mã nguồn trang cũng đọc được; mọi lời gọi API GHN phải đi từ máy chủ (PHP), trình duyệt chỉ gọi về website của bạn.
• Đừng commit token lên Git, hãy để nó trong wp-config.php, biến môi trường hoặc tuỳ chọn trong database thay vì viết thẳng vào file code rồi đẩy lên kho mã.
• Đừng ghi token vào log hay URL vì cả hai đều dễ lọt ra ngoài; riêng plugin của mình, ô Debug ghi cả header Token vào file log nên chỉ bật khi đang dò lỗi; dò xong bỏ tích Debug rồi bấm Lưu, file log thì đừng gửi nguyên cho ai.
• Che token trong ảnh chụp khi nhờ hỗ trợ.
• Bật danh sách IP tin cậy chỉ cho IP máy chủ website, như mục ở trên.

Lỡ lộ token: bật ngay danh sách IP tin cậy để chặn nơi khác gọi vào, rồi liên hệ GHN (tổng đài 1900 636677, email cskh@ghn.vn) để được hướng dẫn đổi token.

Lỗi 401 và các lỗi hay gặp với token GHN

• Lỗi HTTP 401 “Authorization header is required!” nghĩa là request thiếu header Token; hay gặp khi gõ sai tên header hoặc khi ô token trống vì chưa bấm Lưu.
• HTTP 401 dù token đúng thường do danh sách IP tin cậy đã có IP nhưng không có IP máy chủ website.
• Token đúng mà vẫn bị từ chối thường do dùng token staging gọi Production hoặc ngược lại, nên trong plugin hãy kiểm lại ô Môi trường.
• Dán thừa khoảng trắng hay dấu xuống dòng khi sao chép thì xoá ô, dán lại.
• Lỗi CLIENT_NOT_OWNER_OF_SHOP nghĩa là ShopId không thuộc tài khoản của token; gọi lại v2/shop/all để lấy đúng ShopId, còn dùng plugin thì bấm Đồng bộ kho.

Hết các nguyên nhân trên mà website vẫn chưa có phí GHN thì xem trang hỏi đáp plugin GHN.

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

API token GHN có hết hạn không?

Tài liệu GHN (tháng 10/2026) không ghi thời hạn cho token. Website đang chạy tự dưng báo lỗi xác thực thì vào lại mục Token API & IP tin cậy, kiểm tra token và danh sách IP trước.

Có phải nhờ GHN cấp token không?

Không. Theo trang Lấy Token của GHN, shop tự xem và sao chép token trong tài khoản, xác nhận bằng OTP gửi về số điện thoại.

Hai website dùng chung một tài khoản GHN được không?

Token đi theo tài khoản, nên website nào dùng token đó đều gọi API trên cùng tài khoản GHN. Nếu bật danh sách IP tin cậy thì thêm IP máy chủ của cả hai website.

Plugin GHN có cần nhập ShopId không?

Không. Plugin chỉ có ô Token Key và ô Môi trường; danh sách cửa hàng được lấy tự động qua API v2/shop/all khi bạn bấm Đồng bộ kho hàng từ GHN.

Lấy token xong là tới bước nối GHN vào website. Chưa chọn nên tự code hay dùng plugin thì đọc bài kết nối GHN với website.

Vướng chỗ nào cứ để lại bình luận, nhớ che token và ShopId trước khi dán ảnh nhé. 😄