Cách lấy API token GHTK theo giao diện mới: tạo token, chọn quyền, ngày hết hạn

Chào anh em! Nhiều hướng dẫn lấy API token của Giao Hàng Tiết Kiệm (GHTK) trên mạng vẫn chỉ vào trang Tài khoản trong mục Thông tin shop. Theo tài liệu API hiện tại của GHTK, token giờ được tạo và quản lý ở mục Cấu hình API: mỗi token có tên riêng, ngày hết hạn và danh sách quyền. Chọn thiếu quyền là website có tính năng chạy, có tính năng không; quên ngày hết hạn là một sáng đẹp trời trang thanh toán mất phí ship.

Làm theo bài này, anh em có một token đủ quyền đang chạy trên website và biết cách thay nó trước ngày hết hạn. Ảnh minh hoạ giao diện GHTK trong bài lấy từ tài liệu API chính thức của GHTK.

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

Có token, website hay phần mềm bên ngoài mới gọi được API của GHTK thay mặt shop: tính phí ship, đăng đơn, tra trạng thái, huỷ đơn, in nhãn. Nó luôn đi cùng mã shop trong mỗi request. Ai cầm token là làm được mọi việc trong phạm vi quyền của token đó, nên giữ nó như giữ mật khẩu.

Các bước lấy API token GHTK

1. Đăng nhập trang khách hàng GHTK tại khachhang.giaohangtietkiem.vn bằng tài khoản shop.
2. Vào Thông tin shop → Cấu hình API (đường dẫn thẳng: khachhang.giaohangtietkiem.vn/web/thong-tin-shop/cau-hinh-api). Màn hình Quản lý API Token liệt kê các token đã tạo.
3. Bấm nút + Tạo token ở góc trên bên phải.
4. Điền Tên token (đặt theo nơi dùng, ví dụ “Website WooCommerce”), chọn Ngày hết hạn, rồi tick các quyền ở mục Quyền truy cập. Chọn quyền nào thì xem mục ngay bên dưới. Mục Thiết lập nâng cao ở cuối hộp thoại thì tài liệu GHTK không mô tả, mình để mặc định.
5. Bấm Tạo token. Token hiện ra trong khung báo tạo mới thành công, đang bị che bằng dấu sao: bấm biểu tượng con mắt để hiện, biểu tượng bên cạnh để sao chép.

Nên tick những quyền nào?

Hộp thoại có 10 quyền. Mỗi quyền mở một nhóm API, tick thiếu thì GHTK từ chối các request cần quyền đó:

• Quyền Tính phí dùng để lấy phí ship của đơn hàng, bắt buộc phải có nếu website muốn hiện phí GHTK ở trang thanh toán, và dễ bị bỏ sót vì ví dụ trong chính tài liệu GHTK không tick nó.
• Quyền Tạo đơn hàng cho phép đăng đơn sang GHTK để lấy mã vận đơn.
• Quyền Trạng thái đơn hàng cho phép tra trạng thái hiện tại của vận đơn.
• Quyền Huỷ đơn hàng cho phép huỷ vận đơn khi shipper chưa lấy hàng.
• Quyền In nhãn đơn hàng dùng để lấy nhãn PDF dán lên gói hàng.
• Quyền Địa chỉ lấy hàng dùng để lấy danh sách kho đã khai trên GHTK.
• Bốn quyền còn lại (Sản phẩm, Lấy danh sách ca lấy dự kiến, Lấy danh sách ca giao dự kiến, Lấy danh sách địa chỉ cấp 4) chỉ cần khi phần mềm của anh em dùng tới các API tương ứng.

Dùng plugin GHTK cho WooCommerce thì tick 5 quyền: Tính phí, Tạo đơn hàng, Trạng thái đơn hàng, Huỷ đơn hàng, In nhãn đơn hàng. Đó là 5 nhóm API plugin gọi khi tính phí, đăng, tra, huỷ và in. Riêng giao nhanh xFast mình chưa đối chiếu được nó cần quyền nào trong danh sách; anh em có dùng xFast mà bị từ chối thì tick thêm hai quyền lấy danh sách ca lấy và ca giao dự kiến.

Một mẹo nhỏ: mỗi nơi dùng một token riêng. Website một token, phần mềm chốt đơn một token. Tên token cho biết cái nào dùng ở đâu, lỡ lộ một cái thì xoá đúng cái đó, chỗ khác vẫn chạy.

Có thể bạn cần

Gửi Zalo ZNS bằng link API

Plugin GHTK cho WooCommerce: kết nối Giao Hàng Tiết Kiệm, tính phí ship & đăng đơn

DevVN License Manager – Quản lý license phần mềm & tự động nhắc hết hạn cho WordPress

Ngày hết hạn: chuyện nhỏ làm website “đứng hình”

Ô Ngày hết hạn là bắt buộc. Ví dụ trong tài liệu GHTK chọn 30 ngày: token tạo ngày 06/11/2024 thì hết hạn 06/12/2024. Tới hạn, GHTK từ chối mọi request dùng token đó. Website không báo lỗi gì to tát: trang thanh toán đơn giản là không còn phí GHTK (với plugin của mình là dòng “Phí vận chuyển sẽ báo sau”), và bấm đăng đơn thì thất bại.

Cách đổi token mà phí ship trên website không bị ngắt quãng:

1. Ghi ngày hết hạn vào lịch, nhắc trước vài ngày.
2. Tới ngày nhắc, tạo token mới với đúng các quyền như cũ.
3. Dán token mới vào website, lưu lại, ra trang thanh toán kiểm tra phí ship còn hiện.
4. Chạy ổn rồi mới quay lại GHTK xoá token cũ (biểu tượng thùng rác trong bảng).

Mã shop lấy ở đâu?

Ngoài token, mỗi request còn gửi kèm mã shop trong header X-Client-Source. Mã này dạng chữ S kèm một dãy số (ví dụ S123456). Đăng nhập GHTK là thấy ngay cạnh dòng chào “Xin chào! …”. Sai mã shop thì request cũng hỏng như sai token.

Dán token vào website WordPress

Với plugin GHTK cho WooCommerce: vào WooCommerce → Cài đặt GHTK → tab Cài đặt GHTK, dán token vào ô Token Key, mã shop vào ô Mã SHOP, bấm Lưu thay đổi. Kiểm tra bằng cách thêm một sản phẩm có cân nặng vào giỏ, ra trang thanh toán chọn địa chỉ: hiện phí GHTK là token đã đúng. Chi tiết từng ô ở trang kết nối tài khoản GHTK.

Tự code thì token đi trong header Token, mã shop trong header X-Client-Source; gọi thử GET /services/authenticated để kiểm tra trước. Đoạn code đầy đủ có ở bài tích hợp GHTK API bằng PHP trong WordPress.

Muốn chạy thử mà không tạo vận đơn thật thì làm y hệt các bước trên ở trang khách hàng thử nghiệm khachhang-staging.ghtklab.com. Token sandbox và token thật là hai token khác nhau, không dùng lẫn được.

⚠️ Đừng dán token vào code rồi đẩy lên Git, đừng gửi nguyên ảnh chụp màn hình có token khi nhờ hỗ trợ. Lỡ lộ thì vào Cấu hình API xoá token đó và tạo token mới.

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

Token GHTK có hết hạn không?

Có. Ngày hết hạn là ô bắt buộc khi tạo token. Hết hạn thì website không tính được phí, không đăng được đơn cho tới khi anh em dán token mới.

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

Tạo token mới thì token cũ có mất không?

Theo giao diện quản lý, mỗi shop có một danh sách token, mỗi token có ngày hết hạn riêng, nên tạo token mới không xoá token cũ. Muốn chặn hẳn token cũ thì xoá nó trong bảng.

Website không hiện phí ship GHTK dù đã nhập token?

Kiểm lần lượt: token đã có quyền Tính phí chưa, còn hạn không, có đang dùng token thật trong chế độ Sandbox (hoặc ngược lại) không, mã shop đúng chưa. Hết các nguyên nhân về token mà vẫn chưa ra phí thì xem thêm mục lỗi hay gặp khi tích hợp GHTK vào WordPress.

Một token dùng cho nhiều website được không?

Nên tạo mỗi website một token. Lộ hay hết hạn ở một nơi thì chỉ xử lý đúng nơi đó, các website khác vẫn chạy bình thường.

Anh em chưa quyết nên tự code hay dùng plugin thì đọc bài tích hợp GHTK vào WordPress; vướng chỗ nào cứ để lại bình luận, nhớ che token nhé. 😄