GHN: trạng thái hỗ trợ trong omniVN

Backend có, UI chưa mở

Form Connect tự phục vụ vẫn tạm hoãn. Token + Shop ID đã seal = Connected; book và track theo order_code bằng pull/poll đã có trên backend.

Backend có connector nhưng UI chưa mở

Backend có, UI chưa mở. Book + track bằng pull/poll theo order_code (shipping-order/detail + hydrate). Không list-all/day-range. DoD = Làm mới (poll/get) — webhook/Events PARK. Form Connect tự phục vụ còn deferred. Trang này được liệt kê trong workspace.

Giới hạn hiện tại

Những điểm này ảnh hưởng đến khả năng kết nối hoàn chỉnh.

Form Connect tự phục vụ trên hub vẫn deferred — chưa mở CTA dán credential trên UI.

Tổng quan

GHN Open API xác thực bằng header Token kèm Shop ID. Token, Client ID và Shop ID lấy trên cổng khách hàng (Production: khachhang.ghn.vn hoặc 5sao.ghn.vn; Staging: 5sao.ghn.dev). Backend đã có verify shop/all, bookShipment và hydrate/pull detail theo order_code. Form Connect tự phục vụ trên hub vẫn deferred — operator seal Token+Shop ID (đủ cả hai) = Connected. Theo dõi vận đơn = Làm mới (poll/get), không phải webhook live.

Điều kiện trước khi bắt đầu

Tài khoản GHN đang hoạt động.
Đã tạo cửa hàng trên GHN và có quyền xem thông tin chủ cửa hàng.

Các bước lấy credential

1. Đăng nhập cổng GHN

Production: https://khachhang.ghn.vn (hoặc 5sao.ghn.vn). Staging/test: https://5sao.ghn.dev. Đăng nhập bằng tài khoản của shop cần tích hợp.

2. Mở mục Chủ cửa hàng

Trên giao diện cổng khách hàng, chọn mục Chủ cửa hàng để xem thông tin API.

GHN — chọn Chủ cửa hàng (tài liệu api.ghn.vn) · GHN API Docs

3. Copy Token, Client ID và Shop ID

Chọn Xem và copy Token API, Client ID, Shop ID. Token và Shop ID (đủ cả hai) cần để Connected; dùng cho request tới https://online-gateway.ghn.vn/shiip/public-api/v2 (hoặc base URL theo môi trường).

GHN — Token API, Client ID, Shop ID · GHN API Docs

4. Cập nhật địa chỉ cửa hàng (nếu cần)

Một số API yêu cầu địa chỉ lấy hàng hợp lệ: Quản lý cửa hàng → chọn shop → Cập nhật địa chỉ.

5. Hiện trạng Omni0

Form Connect tự phục vụ trên hub vẫn deferred (coming soon). Khi Token + Shop ID đã được seal cho workspace: Connected. Book tạo vận đơn trên GHN; track/hydrate kéo trạng thái và sự kiện theo order_code bằng pull/poll (Làm mới). eventCount 0 → Làm mới lại, không chờ webhook. Events/Hookdeck GHN vẫn PARK.

Ánh xạ credential với omniVN

Cột "Lấy từ đâu" cho biết giá trị do người dùng nhập, do provider cấp, do omniVN quản lý, hay do OAuth sinh ra.

Field omniVN	Tên trong tài liệu official	Bắt buộc	Lấy từ đâu
Token	API Token	Bắt buộc	provider_generated Lấy từ cổng GHN. Verify qua POST /v2/shop/all.
Shop ID	Shop ID	Bắt buộc	user_entered
Client ID	ClientID	Tùy chọn	provider_generated Optional Client ID from GHN portal. Not required for Connected (Token + Shop ID). Webhook provisioning PARKED — track DoD is pull/poll by order_code.
Base URL	API base URL	Tùy chọn	user_entered

token → Token; shopId → Shop ID; baseUrl → Base URL.

Vòng đời token

Token do GHN cấp trên cổng khách hàng. Có thể vô hiệu hoá hoặc tạo lại theo quy trình GHN.

Nguồn chính thức

GHN API - API Tokens and Authentication

api.ghn.vn·Công khai·Đã kiểm chứng 2026-08-29