🌐 言語: 🇻🇳 Tiếng Việt · 🇬🇧 English · 🇯🇵 日本語（現在）

GP247 / S-Cart 向け Giao Hàng Nhanh（GHN）

はじめに

GP247 / S-Cart のショップを Giao Hàng Nhanh（GHN） と連携する無料プラグインです。お客様は決済画面で GHN の実際の送料を確認でき、あなたは管理画面から直接、送り状の作成、ラベルの印刷、キャンセル、注文の追跡を行えます。本書はショップオーナーと管理者向けで、プログラミングの知識は不要です。読み終えると、GHN アカウントの登録、Token と ShopId の取得、プラグインの設定を自分で行い、最初の注文を発送できるようになります。

このプラグインは gp247/shop の標準配送レイヤー上で動作します（「業界標準の配送」を備えたバージョン以降）。

プラグインでできること

設定手順の全体像：

flowchart LR
    subgraph GHN["GHN のサイトで"]
        direction TB
        A["アカウント登録"] --> B["Token を取得"]
        B --> C["ShopId を確認"]
    end
    subgraph ADMIN["GP247 管理画面で"]
        direction TB
        D["プラグインをインストールして有効化"] --> E["Token と ShopId を入力"]
        E --> F["集荷倉庫とお客様住所を設定"]
        F --> G["Webhook URL を GHN に貼り付け"]
    end
    GHN --> ADMIN
    ADMIN --> H["1 件の注文で試してから本番環境に切り替え"]

パート 1 — GHN への登録と Token・ShopId の取得

GHN には完全に分離された 2 つの環境があります。一方の環境のアカウント、Token、ShopId、Webhook 設定は、もう一方の環境では使えません。

1.1. Token の取得

使用したい環境のサイトで、順番に操作します（まず staging で行うことをおすすめします）。

1. 開発者向けサイト（上の表）を開き、右上のログインをクリックします。

2. あなたの電話番号を入力し、認証手順を行います。Google または Apple でのログインも選べます。 本番環境では、ショップが発送に使っている GHN アカウントの電話番号を使用してください。

3. ログイン後、右側のアカウントメニューを開き、トークン管理を選びます。

4. Token API カードで目のアイコンをクリックします。GHN から 6 桁のワンタイムパスワード（OTP）が電話に送られるので、そのコードを入力すると Token が表示されます。

5. コピーアイコンをクリックして Token をコピーします。

   Token は xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx のような文字列です。パスワードと同じように扱ってください。管理画面の GHN 設定画面にのみ貼り付け、チャットやメールで送らないでください。

6. Web サーバーの IP がわからない場合は、使用を許可する IP リスト欄を空欄のままにしてください。この欄に IP が 1 つでも入ると、GHN は他の IP からのリクエストをすべてブロックします。入力漏れがあれば、あなたのサーバーも含めてブロックされます。

1.2. ShopId の確認

ShopId は GHN 上のショップの番号です（1 つの GHN アカウントに複数のショップを持てます）。GHN サイトのアカウント情報で確認できます。

• 登録したばかりの staging アカウントには、通常ショップが 1 つ用意されていますが、住所が未登録です。問題ありません。プラグインがあなたの集荷倉庫を GHN に送信します（パート 3 参照）。
• ShopId が見つからない場合は、設定画面（パート 2）に Token を入力し、ShopId 欄に仮の番号を入力して保存してください。*「ShopId はこのトークンのアカウントに属していません」*というメッセージが出れば、Token は正しく、ShopId だけが誤っているという意味です。

パート 2 — 管理画面でのプラグインのインストールと設定

2.1. インストール

1. 拡張機能 → プラグインを開きます。

2. Giao Hàng Nhanh（GHN）を探し、インストールをクリックしてから有効化します。

   成功すると、ショップ → 配送方法メニューに GHN 項目が追加されます。

2.2. GHN 設定画面

ショップ → 配送方法 → GHN を開きます（またはプラグイン画面でプラグインの横にある ⚙ をクリックします）。複数のストアを運用している場合は、入力前に画面上部でストアを選んでください。

保存をクリックします。システムが GHN との接続を自動確認し、次のいずれかの結果を表示します。

パート 3 — 配送のためのショップ設定

システム管理 → Web サイト設定 → ショップ設定を開きます。

3.1. 配送タブ

1. 注文時の配送を有効化をオンにします。

2. **集荷倉庫（差出人住所）**ブロックを入力します。GHN はここで集荷し、ここから送料を計算します。

   • 差出人名 / ショップ名と電話番号（配達員はこの番号に電話します）。
   • 都道府県（省・中央直轄市）、区・町域（坊・社）は新しい行政単位名（2025 年 7 月 1 日以降）で入力します。例：TP. Hồ Chí Minh と Phường Sài Gòn。
   • 詳細住所：番地、通り名。例：12 Lê Lợi。
   • 郡・県（区・県級）：その地域で県級が廃止されている場合は空欄にします。

   プラグインは、都道府県、区・町域、詳細住所がすべて揃っている場合にのみこの倉庫を使用します。1 つでも欠けていると、GHN は GHN 上で登録されたショップ住所を使います。GHN 上のショップにも住所がなければ、GHN は送料を提示しません。

3. 商品あたりの既定重量（グラム）：重量が入力されていない商品に使用されます。

4. 配送会社が照合済みと通知したら代金引換（COD）を注文に自動記録：GHN のレポートで COD の金額を照合している場合にのみオンにします。各送り状は 1 回だけ記録されます。

5. 保存をクリックします。タブ上部の警告欄に、集荷倉庫やお客様住所に関する行が残っていないことを確認します。

3.2. お客様タブ

お客様住所の都道府県と区・町域欄をオンにします（必須にすることをおすすめします）。この 2 つの欄がないと、GHN は配達先がわからず、決済画面で送料を提示しません。

3.3. 通貨

ショップの通貨リストに VND が必要です（GHN は VND で送料を計算します）。他の通貨での注文は、あなたが設定した為替レートで換算されます。

パート 4 — Webhook：ステータスを自動更新するために

Webhook がなくてもプラグインは動作します。注文を開いたときや同期をクリックしたときに、GHN にステータスを再問い合わせします。Webhook を使うと、GHN 側で変化があった時点ですぐにステータスが更新されます。

1. GHN 設定画面の**ステータスの自動更新（Webhook）**ブロックで、Webhook URL（https://<your-domain>/shipping/webhook/ShippingGHN?hash=... の形式）をコピーします。
2. GHN の開発者向けサイト（Token と同じ環境）で、アカウントメニュー → Webhook 設定 → 注文タブを開きます。
3. URL を貼り付け、Webhook を作成をクリックします。GHN での適用には約 15 分かかります。
4. 本番環境に切り替えるときは、developer.ghn.vn で手順 2〜3 をやり直してください — staging の設定は自動では引き継がれません。

⚠️ Webhook URL には秘密コードが含まれています。公開しないでください。漏えいした場合は、保存時に Webhook 秘密コードを再生成にチェックを入れて保存し、新しい URL を GHN に貼り付けてください。 GHN がインターネット経由であなたのサイトにアクセスできる必要があります。ローカルドメイン（localhost、*.local）では Webhook を受信できません。

パート 5 — 管理画面での日常の利用

5.1. お客様の注文

配送ステップで、お客様には GHN — 軽量貨物または GHN — 重量貨物が送料とお届け予定日とともに表示されます。この送料は、そのカートと住所に対して GHN が提示した送料であり、ショップが GHN に支払います。

5.2. 送り状の作成

1. 注文を開き、配送パネルで送り状を作成をクリックします。

2. 受取人、重量（グラム）、そして梱包済みであれば**荷物のサイズ（cm）**を確認します。正しい数値にすることで、GHN が請求する送料とお客様が支払った送料が一致します。

3. 代金引換（COD）金額を確認します。既定値はお客様がまだ支払うべき金額です。

4. 作成をクリックします。成功すると、パネルに GHN の追跡番号（例：L8RWHQ）、配送会社の送料、ステータス集荷待ちが表示されます。

   パネルに*「配送会社の送料が注文の送料と異なります」*と表示された場合は、お客様の注文時から重量またはサイズが変わっています — 配達員に荷物を渡す前に確認してください。

5.3. ラベルの印刷

ラベルをダウンロードをクリックすると、ブラウザが GHN の作成した .html ファイルをダウンロードします。そのファイルを開くと印刷ダイアログが自動的に表示されます。開く際はインターネット接続が必要です（バーコード画像は GHN から取得します）。ラベルのサイズは設定画面のラベルの印刷サイズ欄で変更します。

5.4. 追跡とキャンセル

• 同期：GHN に最新のステータスを問い合わせます。履歴は配送履歴に表示されます。
• 送り状をキャンセル：GHN がまだキャンセルを許可している場合のみ可能です（通常は集荷前）。キャンセル後に、同じ注文で新しい送り状を作成できます。
• 配達済み、返品済み、キャンセル済みのステータスと代引金は、記録する前に必ず GHN に直接問い合わせて確認するため、偽の通知で注文の金銭ステータスが変更されることはありません。

条件と制約（操作する前に理解してください）

決済画面で送料を提示するとき

• 合計重量は最大 50 kg — GHN はそれより重い荷物を受け付けないため、決済画面に GHN は表示されません。
• お客様住所には GHN のマスタと一致する都道府県と区・町域が必要です（声調記号の有無や「TP.」「Phường」などの接頭辞は区別しません）。郡・県を含む旧形式の住所は、旧形式のまま原文どおり送信されます。名称が大きく異なる場合 ⇒ その住所には GHN の送料が表示されません。
• 登録した集荷倉庫の都道府県・区・町域名を GHN が認識できない場合 ⇒ GHN は送料を提示しません — 新しい行政単位名に修正してください。

送り状を作成するとき

• 受取人の氏名と電話番号は必須です — 配達員が連絡するために必要です。
• 代金引換の金額は 1 注文あたり最大 50,000,000 VND — GHN の上限です。
• 保険価額は最大 5,000,000 VND — これを超えても、GHN の補償は 5,000,000 VND までです。
• ネットワークエラー後に再作成しても重複した注文は作られません — GHN はすでに作成済みの送り状をそのまま返します。

キャンセルするとき

• GHN が許可している場合のみキャンセルできます。GHN が拒否した場合、管理画面には GHN の理由がそのまま表示されます。

環境

• staging の Token、ShopId、Webhook は本番環境では使えません。逆も同様です。

API ドキュメント

GHN の公開ドキュメント（developer.ghn.vn）に基づき、2026-10-18 に staging で照合・実地テストを行いました。

ライセンス

GP247 のライセンスに基づく、無料のオープンソースです。

よくある質問（Q&A）

質問 1：決済画面に GHN が表示されません。

→ 順番に確認してください。GHN 設定画面に接続に成功しましたと表示されている、お客様タブで都道府県・区・町域がオンになっている、集荷倉庫に都道府県・区・町域・詳細住所が揃っている、VND 通貨がある、カートが 50 kg を超えていない、販売中のストアでプラグインが有効になっている。

質問 2：Token は正しいのに GHN が送料を提示しない、または送り状の作成時に「Address convert from fail」と表示されます。

→ GHN がどこで集荷すればよいかわかっていません。ショップ設定 → 配送（パート 3.1）で集荷倉庫をすべて入力するか、GHN 上でショップの住所を登録してください。

質問 3：staging から本番に切り替えるには何をすればよいですか？

→ developer.ghn.vn で Token と ShopId を取得し、**環境 = 本番（production）**を選び、新しい Token を貼り付け、ShopId を修正して保存します。その後、本番の GHN サイトで Webhook を設定し直してください（パート 4）。

質問 4：GHN が請求する送料が、お客様が支払った送料と異なります。

→ 多くの場合、商品の重量が未入力または誤っていることが原因です。商品に重量（およびサイズ）を入力し、送り状の作成時には梱包済みの箱に合わせて重量とサイズを修正してください。

質問 5：お客様の住所がまだ旧形式（郡・県あり）で書かれている場合は？

→ プラグインは旧形式のまま原文どおり送信し、GHN 側で検索させます。それでも GHN が認識しない場合は、送り状を作成する前に新しい行政単位名で住所を修正してください。

質問 6：注文ステータスが自動で更新されません。

→ Webhook の URL と環境が正しく貼り付けられているか、また約 15 分が経過しているかを確認してください。ローカルドメインで動作しているサイトには GHN からアクセスできません — 同期ボタンを使ってください。

質問 7：ラベルファイルを開くと真っ白、またはバーコードが表示されません。

→ ファイルを開くパソコンにはインターネット接続が必要です（バーコード画像は GHN からダウンロードされます）。それでも解決しない場合は、もう一度ラベルをダウンロードをクリックして新しいファイルを取得してください。

質問 8：1 つの GHN アカウントを複数のストアで使えますか？

→ 使えます。Token と ShopId を共通の範囲で入力し、各ストアはショップ設定でそれぞれの集荷倉庫を登録します。GHN はその倉庫に集荷に来ます。個別の GHN アカウントが必要なストアは、設定画面でそのストアを選び、個別の Token を入力してください。

質問 9：エラーが発生した場合、どこでメッセージを確認できますか？

→ 送り状の作成、キャンセル、ラベルのダウンロード時に、管理画面に何を修正すべきかを明示した文が表示されます（例：主な住所欄に選択した区・町域とは異なる坊名が書かれている、電話番号が誤っている、その配送ルートにサービスがない）。括弧内には GHN の原文が添えられます。GHN に拒否された Token はシステムログに記録されるため、新しい Token を取得する必要があることがわかります。

質問 10：プラグインをアンインストールすると、作成済みの送り状は失われますか？

→ いいえ。送り状と履歴はショップ内に保存されています。プラグインをアンインストールしても、削除されるのは GHN の設定だけです。

_{📅 最終更新: 2026-10-22 · ✍️ 作成者 (Author): GP247}