VibeFox ShipStation for OpenCart — ヘルプ

動作要件

OpenCart：3.0.x（3.0.5.0 で検証済み）または 4.0.2 以降（4.1.0.3 で検証済み）。

PHP：8.0 以降。

ShipStation アカウント：ShipStation で運送会社を接続し（Settings > Shipping > Carriers）、ShipStation > Settings > Account > API Settings から API Key と API Secret をコピーしてください。API アクセスは ShipStation のプランによって異なります。この拡張機能は ShipStation API V1（API Key と API Secret）を使用します。キーがない場合は予備料金のみが使用されます。

VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。

インストール

ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。お使いのコンピューターで解凍してください。README.txt、OpenCart 3 用パッケージ vfd_shipstation-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ vfd_shipstation.ocmod.zip が含まれています。お使いの OpenCart バージョンのパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_shipstation-oc3-(version).ocmod.zip を選択します。この拡張機能は OCMOD の変更を追加しないため、Extensions > Modifications を更新する必要はありません。Installer を使用する代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。

2. Extensions > Extensions に移動し、拡張機能の種類として Shipping を選択します。VibeFox ShipStation を見つけて、Install（緑色の + ボタン）をクリックします。

3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。

4. Edit ページ上部の License key 欄に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。

5. API Key と API Secret を貼り付け、発送元の郵便番号を入力して、Save をクリックします。ページにアカウントの運送会社コードが表示されます。必要なコードを Carrier codes に入力し、もう一度保存します。

6. ストアの基準通貨が ShipStation アカウントの通貨と異なる場合は、Exchange rate を設定してください。必要に応じて予備料金も入力できます。

7. Enable ShipStation shipping をオンにして、Save をクリックします。

OpenCart 4

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル vfd_shipstation.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 はファイル名から拡張機能のコードを取得するため、名前を変更したパッケージは動作しません。

2. パッケージは同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。

3. Extensions > Extensions に移動し、拡張機能の種類として Shipping を選択します。VibeFox ShipStation を見つけて、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。

4. ライセンスキーと設定は、OpenCart 3 の手順 4 から 7 と同じように入力します。設定ページとそのフィールドは両方のバージョンで同じです。

インストール後は、オンにして保存するまでこの方法は無効のままです。アンインストール後に拡張機能を再インストールした場合は、保持されていた ShipStation の設定が再び使用されます。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox ShipStation > Edit。セクションは左側に一覧表示されます。Save ボタンを 1 回押すと、ページを再読み込みせずにページ全体が保存されます。保存するたびに、キャッシュされた ShipStation の料金が消去され、API Key と API Secret が確認されます。その後、ページにはアカウントに接続された運送会社とそのコードが表示されます（例："stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)"）。この拡張機能を変更する権限を持つ管理者ユーザーのみが設定を保存できます。

ページ上部の警告は、リアルタイム料金が機能しない場合を知らせます。キーがない、運送会社コードがない、発送元の郵便番号がない、為替レートがない、接続確認に失敗した、または運送会社コードがアカウントに接続されていない、といった場合です。ストアの重量単位または長さ単位が拡張機能で換算できないものである場合にも警告が表示されます。kg、g、lb、oz、および cm、mm、m、in を使用してください（System > Settings > Option）。無効な名前、数値フィールド、負の値や数値以外のテキストが入った価格セル、Maximum weight より大きい Minimum weight、整数ではない並び順は、エラーとして報告され、何も保存されません。

一般

Enable ShipStation shipping：チェックアウト時にこの方法を表示するか非表示にするかを切り替えます。これは Extensions > Extensions > Shipping における拡張機能のステータスです。

Name：チェックアウト時にお客様に表示される配送方法の名前。デフォルト：ShipStation Shipping。必須。最大 64 文字で、文字 < > ; = # { } は使用できません。

Tax class：送料の税クラス、または No tax。ShipStation の料金には販売税が含まれていません。No tax を選ぶと提示された料金がそのまま表示されます。税クラスを選ぶと、税務ルールに従って送料に税金が加算されます。

Sort order：チェックアウト時の配送方法の中でのこの方法の位置。整数です。

ShipStation アカウント

API Key：ShipStation > Settings > Account > API Settings にある API Key です。ShipStation にのみ送信され、ログに記録されることはありません。保存後、このフィールドは空になり、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

API Secret：同じページにある API Secret です。キーと同じように扱われます。

Remove the saved API key and secret：キーが保存されると表示されます。チェックを入れて保存すると、両方が削除されます。

Carrier codes：1 つ以上の ShipStation 運送会社コードを、カンマで区切って入力します（例：stamps_com、ups_walleted）。最大 5 つのコードが使用され、運送会社ごとに 1 回の API リクエストが送られます。それ以上入力すると、最初の 5 つだけが保持され、ページに通知されます。これらの運送会社のうち最も安い料金が表示されます。コードは保存後に表示される一覧から取得してください。

Allowed services：任意。カンマで区切った ShipStation サービスコード（例：usps_priority_mail、ups_ground）。空欄のままにすると、上記の運送会社のうち最も安いサービスが表示されます。

Package code："package"（デフォルト）は、独自の箱の料金を計算し、運送会社の封筒や定額料金の箱は除外します。空欄のままにすると、運送会社が提供するすべてのパッケージの種類の料金が計算されます。

発送元

Ship-from postal code：リアルタイム料金に必要です（例：78703）。ShipStation は郵便番号のみに基づいて料金を計算し、その郵便番号は ShipStation アカウントの国に含まれている必要があります。OpenCart にはストアの郵便番号がないため、ストアの住所から取得されることはありません。

料金

Parcels：カートが ShipStation にどのように送信されるか。

ShipStation account currency：ShipStation が料金を返す通貨：USD、CAD、GBP、AUD、NZD、EUR。デフォルト：USD（米国のアカウント）。

Exchange rate：アカウント通貨 1 単位のストアの基準通貨での価格（例：0.92）。基準通貨がアカウント通貨と異なる場合にのみ必要です。設定しないと、リアルタイム料金は使用されず、予備料金が適用されます。為替レートは自動的には更新されません。

予備料金（リアルタイム料金がない場合に使用されます：API キーがない、ShipStation に接続できない、住所の運送会社料金がない場合。料金はストアの基準通貨で設定します。その場合に方法を非表示にするには、表と Other countries を空欄のままにします）

Prices by country：国ごとの Base 料金と、荷物の重量によるサイズ列を持つ表です。XS は 1 kg まで、S は 2 kg まで、M は 3 kg まで、L は 5 kg まで、XL は 5 kg を超える場合です。Add country をクリックすると行を追加できます。サイズが空欄の場合は基本料金が使用されます。基本料金が 0 の場合は送料無料を意味します。* Default (all other countries) の行は、独自の行がない国に適用されます。料金が 1 つもない行は保存されません。

Other countries：表にその国の料金がない場合に使用される料金。その場合に方法を非表示にするには空欄のままにします。

条件

Free shipping from：配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額に達すると送料が無料になります。その場合、ShipStation へのリクエストは行われません。無効にするには空欄のままにします。

Minimum subtotal：配送が必要な商品の小計（クーポン適用後、税抜き）がこの金額以上の場合にのみ、この方法を表示します。常に表示するには空欄のままにします。

Minimum weight：この方法を表示するためのカートの最低重量。ストアの重量単位（フィールド名に表示されます）で指定します。0 は制限なし（デフォルト）を意味します。

Maximum weight：カートの重量がこの値を超えると、この方法は非表示になります。単位はストアの重量単位です。0 は制限なし（デフォルト）を意味します。

提供条件

Geo zone：この地域の住所に対してのみこの方法を提供します。All zones（デフォルト）は制限なしを意味します。Ignore shipping zones がオンの間は確認されません。ジオゾーンは System > Localisation > Geo Zones で管理します。

Ignore shipping zones：ジオゾーンに関係なく、下記の国に対してこの方法を提供します。

Countries：このモードの配送先の国。空欄のままにすると、ストアで有効になっているすべての国が使用されます。このフィールドは Ignore shipping zones がオンの場合にのみ使用されます。

詳細設定

Debug log：ShipStation へのリクエストを storage/logs/vfd_shst_debug.log.php（OpenCart 4 では system/storage/logs/vfd_shst_debug.log.php）に記録します。このファイルはウェブから読み取ることはできません。このオプションがオフでも、API エラーは常に記録されます。API Key、API Secret、お客様の住所は決して記録されません。郵便番号はマスクされます。ファイルが 5 MB に達すると、vfd_shst_debug.old.log.php に移動され、新しいログが開始されます。

Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると空にできます。

Remove data on uninstall：オンにすると、拡張機能をアンインストールした際に ShipStation の設定とログが削除されます。オフ（デフォルト）の場合は、再インストール用に保持されます。キャッシュされた料金は常に削除されます。注文済みの注文の ShipStation サービスは常に保持されます。

インポート / エクスポート

Export：Download JSON をクリックすると、設定を JSON ファイルとして保存します。API Key と API Secret はエクスポートされません。

Import：以前にエクスポートした JSON を貼り付け、Import をクリックすると、設定が復元されます（例：別のストアで）。値は通常の保存と同じように確認されます。保存済みの API Key と API Secret は保持されます。

チェックアウト時の動作

OpenCart が配送方法を表示するとき、拡張機能に ShipStation の料金を問い合わせます。Geo zone が設定されていて（かつ Ignore shipping zones がオフの）、住所がその範囲外の場合、この方法は提供されません。Requires Shipping が Yes に設定された商品のみが対象になります。それ以外の商品は重量に加算されず、小計にも含まれません。その後、拡張機能は条件を確認します。許可された国（Ignore shipping zones の場合）、カートの重量、最低小計です。ギフト券、ポイント、ストアクレジットは考慮されません。送料無料が適用される場合は、料金 0 でこの方法が表示され、ShipStation へのリクエストは送信されません。

その後、拡張機能は ShipStation に、発送元の郵便番号、配送先の国、州コード、市区町村と郵便番号、荷物の重量、箱のサイズを送信します。お客様が郵便番号を入力するまでは、リクエストは行われません。郵便番号のない国には予備料金が適用されます。商品は 1 つの箱にまとめられます。商品に寸法がない場合、荷物は重量のみで計算されます。

ShipStation は運送会社コードごとに 1 回ずつ問い合わせられます。拡張機能は、許可された中で最も安い料金を使用し、それをストアの基準通貨に換算して小数点以下の桁数に丸めます。その後、料金は選択された Tax class の税金を加えて、お客様の通貨で表示されます。

各応答は 1 時間キャッシュされます。ShipStation が使用可能な料金なしで応答した場合、その応答は 10 分間記憶されます。ShipStation がキーを拒否した場合、または接続できない場合、リクエストは 5 分間一時停止されます。レート制限の後は、一時停止の時間は ShipStation が示すリセット時間に従います。リクエストのタイムアウトは 12 秒です。

リアルタイム料金がない場合、料金は予備料金の表から、次に Other countries から取得されます。どちらも適用されない場合は、この方法は非表示になります。お客様が ShipStation のエラーメッセージを見ることはありません。詳細はデバッグログに記録されます。

この拡張機能は料金の計算のみを行います。送り状の購入、ShipStation での注文や出荷の作成、荷物の追跡、返品の処理は行いません。受け取り場所、チェックアウトでの複数サービスの選択、住所検証、保険、署名確認、複数の荷物への梱包、料金の上乗せはありません。

OpenCart 4 では、お客様はチェックアウトページの配送方法ブロックで Choose をクリックし、Shipping method options ウィンドウで ShipStation を選択します。この方法は OpenCart 3 と同じように動作します。

注文

リアルタイムの ShipStation 料金で注文が行われると、選択されたサービスが注文と一緒に保存されます。Sales > Orders で注文を開くと、注文履歴の上にある ShipStation パネルに Service として表示されます（例："USPS Ground Advantage - Package"）。これにより、ShipStation で対応する送り状を作成できます。商品ごとのモードでは、サービスはカンマ区切りで一覧表示されます。その後にカートを変更しても影響はなく、この方法をオフにした後もパネルは表示されます。予備料金または送料無料で注文された注文には、ShipStation パネルはありません。

OpenCart 4 では、チェックアウト用の注文は 1 つだけ保持され、お客様が再度確定するたびに更新されます。保存された ShipStation サービスも一緒に更新されます。お客様が別の配送方法に変更した場合、または予備料金が適用される場合は、保存されたサービスは注文から削除されます。

ライセンスキー

この拡張機能は、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox ShipStation は、Extensions > Extensions > Shipping > VibeFox ShipStation > Edit の最初のブロックで、設定の上にあります。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーがマスク表示され、ステータス（ライセンスの有効期限日、お使いのドメインなど）と、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には Product: opencart-shipping-shipstation の行と、お客様の vibefox.net アカウントを開く Manage licenses and domains in your account のリンクがあります。キーを変更できるのは、この拡張機能に対する Modify 権限を持つ管理者ユーザーのみです。ブロックのテキストは管理画面の言語に従います（英語とロシア語を含みます）。

キーが受け付けられない場合、ブロックに理由が表示されます（例：Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on）。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後に、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認された状態で動作を続けます。

1 つのキーは 1 つのドメインで使用できます。ドメインとは、OpenCart の設定にあるストアのアドレスです。ストアからキーを削除しても、ドメインの枠は解放されません。vibefox.net アカウントで枠を解放してください。

有効なキーがない場合、ShipStation はチェックアウト時にお客様に表示されず、料金も計算されません。同じブラウザで管理画面にログインしている管理者ユーザーには、(unlicensed — visible to admins only) と表示された状態で、ストアにこの方法が表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 では、このプレビューは利用できません。ストアは管理画面へのログインを認識しないため、有効なキーがない場合は全員に対してこの方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。

ライセンスの有効期限が切れた後も拡張機能は動作し続けますが、アップデートとサポートには更新が必要です。ステータスは、管理画面の Dashboard または Edit ページを開いたときに自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

チェックアウトに ShipStation が表示されない：ライセンスが有効であること、Enable ShipStation shipping がオンであることを確認してください。Geo zone（または Ignore shipping zones がオンの場合は Countries）、重量制限、Minimum subtotal を確認してください。リアルタイム料金がない場合は、その国、* Default、または Other countries に料金が設定されているか確認してください。商品の Requires Shipping が Yes に設定されているか確認してください。

チェックアウトで ShipStation の料金ではなく予備料金が表示される：拡張機能ページ上部の警告（キー、運送会社コード、発送元の郵便番号、為替レート）を確認してください。Debug log をオンにして、チェックアウトを再読み込みし、Log フィールドを確認してください。お客様の郵便番号が必要です。入力されるまでリクエストは行われません。

どの運送会社コードを入力すればよいか：キーと Secret を入力して設定を保存してください。ページにアカウントの運送会社コードが表示されます。そのうち 1 つ以上を使用してください。

ShipStation の接続確認に失敗した：メッセージに理由が表示されます。API Key と API Secret を確認し、もう一度保存して確認をやり直してください。

料金が ShipStation と異なる：荷物は商品の重量と寸法から、商品を 1 つの箱にまとめて作成されます。寸法のない商品は重量のみで計算されます。料金は 1 時間キャッシュされます。拡張機能ページで Save をクリックすると、キャッシュが消去されます。

ページに "Warning: You do not have permission to modify VibeFox ShipStation!" と表示される：管理者のユーザーグループが設定を閲覧のみできる可能性があります。System > Users > User Groups で、そのグループに extension/shipping/vfd_shipstation（OpenCart 3）または extension/vfd_shipstation/shipping/vfd_shipstation（OpenCart 4）の変更権限を付与してください。

開発者向け：ShipStation API のアドレスは、設定 vfd_shst_api_url（テスト用）で置き換えられます。設定ページにはこの項目のフィールドはありません。

アンインストール

Extensions > Extensions に移動し、種類 Shipping を選択して、VibeFox ShipStation の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は常に Enable ShipStation shipping、Sort order、Tax class、Geo zone をリセットします。キャッシュされた料金と接続確認の結果は常に削除されます。Remove data on uninstall がオンの場合は、ShipStation の設定とデバッグログも削除されます。オフの場合は、その他の設定が保持され、拡張機能を再インストールしたときに再び使用されます。既存の注文は、配送方法、料金、ShipStation サービスを保持します。

OpenCart 4 で拡張機能のファイルも削除する場合は、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox ShipStation の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、Delete（赤いゴミ箱ボタン）をクリックして、アップロードしたパッケージを削除してください。

ShipStation は、その所有者の商標です。この拡張機能は ShipStation と提携しておらず、ShipStation による推奨も受けていません。