Tích hợp GHN vào WooCommerce — tự động tính phí ship + tạo vận đơn

GHN (Giao Hàng Nhanh) là vendor shipping nội địa lớn nhất Việt Nam — cover 63/63 tỉnh thành với 5 service và settlement T+2 cho phí thu hộ 0,5-1,0%. Tích hợp GHN vào WooCommerce mất 1 ngày bao gồm đăng ký business account, cài plugin official và cấu hình shipping zones.

Bài này hướng dẫn end-to-end 5 bước, snippet PHP auto-select service theo giá trị đơn và 5 lỗi phổ biến khi go-live.

GHN là gì và phù hợp shop nào

GHN là vendor shipping nội địa lớn nhất Việt Nam tính theo volume đơn năm 2025, cover 63/63 tỉnh thành với mạng lưới hơn 1.000 điểm giao nhận. Có 3 service chính: Tiêu chuẩn (3-5 ngày), Nhanh (1-2 ngày), Tiết kiệm (4-7 ngày).

Phí ship 22.000-100.000đ tuỳ vùng và weight.

GHN phù hợp shop bán nội địa cần tốc độ giao và COD support tốt. Free tier API 60 request/phút đủ cho shop dưới 50 đơn/ngày.

Paid tier 200-500 request/phút khoảng 50-200 USD/tháng cho shop scale lớn.

3 lý do shop chọn GHN làm primary vendor

• Cover rộng nhất 63/63 tỉnh: GHTK cover khoảng 85% xã, Viettel Post 95%, GHN gần 100%. Cho shop bán toàn quốc, GHN ít phải fallback sang vendor khác cho vùng sâu vùng xa.
• Settlement nhanh T+2: tiền COD về tài khoản sau 2-3 ngày làm việc — nhanh nhất trong các vendor lớn. GHTK T+2-4, Viettel Post T+3-5.
• Quan trọng cho shop SME cần cash flow xoay vốn nhanh.
• Plugin official maintain stable: GHN có plugin official trên repo WordPress.org, update thường xuyên, support ticket trong 24-48 giờ. Plugin community của vendor khác đôi khi bỏ maintain sau 1-2 năm.

Khi nào KHÔNG nên chọn GHN làm primary

GHN không phải vendor tốt nhất cho mọi case. Có 3 trường hợp shop nên chọn GHTK hoặc Viettel Post làm primary và để GHN làm backup.

• Shop có volume đơn nhỏ giá trị thấp: GHN phí cao hơn GHTK khoảng 5-10%. Shop bán phụ kiện nhỏ giá 50.000-150.000đ với volume cao, GHTK tiết kiệm hơn.
• Shop bán nông thôn nhiều: GHTK có deeper coverage ở xã nông thôn miền Tây, miền Trung. GHN tập trung thị xã và quận hơn.
• Shop dùng dịch vụ giao tận nơi: Viettel Post có dịch vụ giao tận tay người nhận, GHN chỉ giao tới địa chỉ. Phù hợp shop bán hàng giá trị cao cần ký nhận trực tiếp.

Bước 1 — Đăng ký tài khoản GHN Business

Đăng ký tại trang chính thức của GHN qua mục “Đăng ký doanh nghiệp”. Process online ngắn (1-2 ngày), chỉ cần giấy phép kinh doanh và STK ngân hàng.

Sau approve, đăng nhập dashboard merchant để lấy API credential.

4 thông tin cần lưu sau khi tài khoản được duyệt

1. Token API: string 36 ký tự dạng UUID, dùng cho mọi request API. Quan trọng nhất, lưu vào password manager.
2. Shop ID: số định danh shop trong hệ thống GHN (5-7 chữ số), dùng khi tạo vận đơn.
3. Client ID: dùng cho real-time tracking webhook, khác Shop ID.
4. API Endpoint: sandbox https://dev-online-gateway.ghn.vn/ và production https://online-gateway.ghn.vn/.

3 setting dashboard cần config sau khi nhận credential

• Pickup address: địa chỉ kho lấy hàng — nếu có nhiều kho thì add cả 3-5 địa chỉ để plugin tự pick nearest warehouse.
• Pickup schedule: “Lấy hàng định kỳ” (shipper đến mỗi sáng 9h-11h) hoặc “Lấy hàng theo yêu cầu” (gọi qua API). Định kỳ tiết kiệm thời gian shop nhưng chậm hơn 4-6 giờ.
• COD bank account: STK nhận tiền COD settlement — đặt riêng STK COD không gộp với STK chính của shop để tracking thuận tiện.

Bước 2 — Cài plugin GHN cho WooCommerce

GHN có plugin official miễn phí trên repo WordPress.org, do team GHN Express trực tiếp maintain. Cài qua wp-admin UI trong 5 phút.

Plugin tự calc phí ship realtime và tạo vận đơn từ admin order screen 1 click.

5 bước cài plugin qua wp-admin

1. Vào Plugins → Add New trên wp-admin, search “GHN for WooCommerce”.
2. Chọn plugin của GHN Express (publisher official, dấu xanh verify).
3. Click Install Now rồi Activate.
4. Vào WooCommerce → Settings → Shipping, click tab “GHN” mới xuất hiện.
5. Click “Get started” để mở config wizard 4 step.

Mẫu config plugin với credential thật

# Plugin Settings → GHN config

Enable: ✓ tick bật cổng
Token API: a1b2c3d4-e5f6-7890-abcd-ef1234567890     # Từ dashboard GHN
Shop ID: 198765                                     # Số shop ID

Mode: Sandbox  # Switch Production sau test pass đủ checklist
Default Service: 53320
  # 53320 = Tiêu chuẩn
  # 53321 = Nhanh
  # 53322 = Tiết kiệm

Pickup address:
  Province: Hà Nội (ID: 201)
  District: Thanh Xuân (ID: 1542)
  Ward: Nhân Chính (ID: 21001)
  Address: "Số 25 Nguyễn Trãi"

Default weight: 500              # gram, fallback cho product chưa set weight
Default dimension: 20×15×10 cm   # fallback cho product chưa set dimension

Auto-create order: ✓ Tự động tạo vận đơn khi order status = Processing

Bước 3 — Config shipping zones tích hợp GHN

Setup shipping zones VN sao cho GHN tự calc phí cho mỗi zone, không hardcode flat rate. Đây là phần tiết kiệm thời gian admin nhất — phí ship realtime, không phải update tay khi GHN đổi giá hằng quý.

Tạo 3 zone với method GHN Shipping

1. Vào WooCommerce → Settings → Shipping → Add zone.
2. Zone 1 “Hà Nội nội thành”: region Vietnam, postcode 10*-13*. Method: GHN Shipping (plugin auto-add option này).
3. Service: Tiêu chuẩn hoặc Nhanh.
4. Zone 2 “TP.HCM nội thành”: region Vietnam, postcode 70*-73*. Method: GHN Shipping.
5. Service: Tiêu chuẩn.
6. Zone 3 “Tỉnh khác”: region Vietnam (không postcode filter). Method: GHN Shipping.
7. Service: Tiết kiệm.
8. Save zones. Test bằng địa chỉ HN/HCM/Đà Nẵng — mỗi zone phải hiện phí GHN realtime ở trang checkout.

Test calc phí ship realtime

Tạo product test giá 200.000đ, weight 500g, add cart. Đến trang checkout.

Nhập địa chỉ HN nội thành: phí hiện khoảng 25.000đ (Tiêu chuẩn). Đổi sang HCM: phí khoảng 35.000đ.

Đổi sang Hà Giang: phí 45.000-60.000đ (vùng xa).

Nếu không hiện hoặc lỗi “calc failed”, check log file /wc-logs/ghn-{date}.log để debug. Lỗi phổ biến nhất là pickup address chưa fill đủ District và Ward, hoặc product thiếu weight.

Bước 4 — Auto-create vận đơn và tracking

Khi đơn confirm + paid, plugin tự gọi GHN API tạo vận đơn background không cần admin click. Shipper GHN đến lấy hàng theo lịch shop đã set ở dashboard.

Customer nhận email + SMS với tracking code, có thể track realtime tại app GHN hoặc website.

Snippet PHP auto-select service theo giá trị đơn

// Tự switch service theo giá trị đơn để tối ưu phí ship
add_filter('ghn_create_order_args', 'auto_select_ghn_service');

function auto_select_ghn_service($args) {
    $total = $args['cod_amount'] ?? 0;

    if ($total > 1000000) {
        $args['service_id'] = 53321; // Nhanh cho đơn trên 1tr (giá trị cao)
    } elseif ($total < 200000) {
        $args['service_id'] = 53322; // Tiết kiệm cho đơn nhỏ
    } else {
        $args['service_id'] = 53320; // Tiêu chuẩn mặc định
    }
    return $args;
}

Email customer notification template

Sau khi vận đơn tạo thành công, plugin trigger event ghn_order_created. Hook vào event này để gửi email custom cho customer với tracking link và estimate delivery time.

Email default của WooCommerce không có tracking info.

Template email nên include: order number, GHN tracking code, link track tại app GHN, estimate delivery 2-5 ngày tuỳ vùng. Phone support shop để khách liên hệ nếu cần đổi địa chỉ giao.

5 lỗi phổ biến khi tích hợp GHN và cách fix

Tổng hợp từ 25 dự án Web22 deploy GHN 2023-2025, đây là 5 lỗi gặp nhiều nhất khi go-live. Pattern fix đã được verify trên production thực tế.

• Token expired sau 1 năm: API trả 401 Unauthorized đột ngột. Token GHN có hiệu lực 1 năm — generate token mới qua dashboard merchant, paste lại vào plugin settings.
• Set reminder Google Calendar 11 tháng để renew trước khi expire.
• Phí ship không hiện ở checkout: shop chưa fill địa chỉ pickup đầy đủ Province + District + Ward, hoặc product thiếu weight. Check WooCommerce → Settings → Shipping → GHN fill đủ pickup; check products đã set weight.
• Vận đơn tạo nhưng shipper không đến lấy hàng: chưa config “Pickup Schedule” trong GHN admin. Vào dashboard GHN → Cài đặt → Pickup, chọn “Định kỳ” hoặc “Theo yêu cầu”.
• Định kỳ cần xác nhận khung giờ shipper đến.
• Settlement COD chậm hơn 3 ngày: mặc định T+2, nhưng cuối tuần delay sang tuần sau. Check tab Settlement trong dashboard GHN, đối soát số dư cuối tháng.
• Nếu sai số, mở support ticket trong dashboard.
• Đơn ship Hà Giang hoặc Cao Bằng báo “vùng không phục vụ”: GHN có 1-2% xã không support tại vùng cao Tây Bắc và Tây Nguyên. Fallback sang Viettel Post hoặc bưu điện cho địa chỉ này.
• Config WooCommerce hide GHN cho postcode cụ thể.

Webhook sync status đơn realtime từ GHN sang WooCommerce

Sync status đơn từ GHN sang WooCommerce realtime giúp customer thấy update không cần check app GHN riêng. Plugin official có webhook support nhưng cần config bổ sung trên dashboard GHN để fire event đầy đủ.

4 event webhook quan trọng cần enable

• ready_to_pick: shipper sắp đến lấy hàng. Update WooCommerce order status “Ready to ship”, send email notification cho admin.
• picking: shipper đã đến lấy hàng. Update status “Shipped”, send email customer với tracking link.
• delivering: shipper đang giao hàng. Update status “Out for delivery”, send SMS customer (qua eSMS hoặc SpeedSMS) trước 30 phút.
• delivered: giao thành công. Update status “Completed”, trigger workflow request review qua email sau 3 ngày.

Config webhook URL trên dashboard GHN

Vào dashboard GHN mục Cài đặt → Webhook, paste URL endpoint https://yourdomain.vn/wc-api/ghn_webhook/. Tick các event cần subscribe.

Test bằng nút “Send test event” để verify endpoint nhận đúng JSON payload.

Verify webhook signature trong PHP để tránh spoofed event giả. GHN sign mỗi webhook bằng HMAC-SHA256 với secret từ dashboard.

Verify signature trước khi update order status — security best practice.

Strategy multi-vendor — pair GHN với GHTK hoặc Viettel Post

Shop scale 200+ đơn/ngày nên tích hợp tối thiểu 2 vendor để: khách có option chọn vendor theo giá, fallback khi 1 vendor lỗi system, cover 100% xã VN. Combo phổ biến nhất là GHN primary + GHTK backup hoặc GHN primary + Viettel Post backup.

3 cách chia traffic giữa 2 vendor

• Customer chọn vendor ở checkout: hiển thị cả 2 method “GHN Tiêu chuẩn 30k” và “GHTK Tiêu chuẩn 27k”. Khách tự decide theo giá hoặc preference.
• Đơn giản nhất, không cần custom code.
• Auto-assign theo geographic zone: GHN cho thành phố lớn (HN, HCM, ĐN), GHTK cho tỉnh nhỏ vì phí rẻ hơn. Custom rule trong shipping zones theo postcode.
• Auto-assign theo giá trị đơn: GHN Nhanh cho đơn trên 1 triệu (priority delivery), GHTK Tiết kiệm cho đơn dưới 200.000đ (tối ưu margin). Custom rule qua filter woocommerce_package_rates.

Câu hỏi thường gặp về tích hợp GHN

Bài liên quan trong cụm WooCommerce

GHN là shipping vendor pair với payment gateway để cover full ecommerce flow. Tham khảo các bài cùng cụm:

• Cấu hình COD WooCommerce — chống bom hàng — pair với GHN cho settlement COD T+2-3.
• So sánh 8 cổng thanh toán WooCommerce VN — decision matrix — chọn cổng pre-pay phù hợp combo với COD và GHN.
• Tích hợp VNPAY vào WooCommerce — cổng pre-pay phổ biến nhất, pair với GHN cho B2C VN.
• Tích hợp GHTK vào WooCommerce — vendor backup khi cần phí rẻ hơn GHN.
• Dịch vụ thiết kế website WooCommerce trọn gói tại Web22 — gói thi công shop turnkey kèm tích hợp shipping VN.

Cần đội Web22 tích hợp GHN turnkey kèm multi-zone, auto-tracking và COD settlement tự động? Thi công WooCommerce theo yêu cầu cho shop Việt — báo giá rõ ràng theo phạm vi, không phát sinh sau khi ký hợp đồng.