VibeFox EasyPost for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で動作確認）または 4.0.2 以降（4.1.0.3 で動作確認）。

PHP: cURL を有効にした 8.0 以降。

EasyPost アカウント（リアルタイムの運賃のみに必要）: EasyPost の Web サイトでアカウントを作成し、EasyPost ダッシュボードで運送会社アカウント（USPS、UPS、FedEx など）を接続して、EasyPost Dashboard > Account Settings > API Keys から API キーをコピーします。EasyPost が課金するのは購入したラベルであり、運賃の問い合わせではありません。代替料金だけを使う場合は、EasyPost アカウントは不要です。

商品: 商品には重量が必要で、できれば寸法も必要です。

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

インストール

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

OpenCart 3

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

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

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

4. Edit ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックしてください（ライセンスキーを参照）。

5. EasyPost の API キーを貼り付け、Ship from の住所を入力します。リアルタイムの運賃には郵便番号が必要です。

6. 既定の通貨が USD でない場合は、USD exchange rate を入力します。必要に応じて代替料金を入力します（設定を参照）。Enable EasyPost shipping を有効にして Save をクリックします。

OpenCart 4

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

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

3. Extensions > Extensions に移動し、拡張機能の種類で Shipping を選びます。VibeFox EasyPost を見つけて Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆ボタン）をクリックしてください。

4. ライセンスキーと設定は、OpenCart 3 の手順 4 から 6 と同じように入力してください。設定ページとその項目は、両方のバージョンで同じです。

インストール後は、Enable EasyPost shipping を有効にして保存するまで、この方法は無効のままです。アンインストール後に拡張機能を再インストールすると、保持されていた設定が再び使われます。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Shipping > VibeFox EasyPost > Edit。セクションは左側に表示されます。1 つの Save ボタンで、ページを再読み込みせずにページ全体を保存します。保存のたびに、キャッシュされた EasyPost の運賃も消去されます。この拡張機能の変更権限を持つ管理者ユーザーのみが、設定の保存またはログの消去を行えます。

ページ上部には、リアルタイムの運賃を使用できない場合に警告が表示されます。API キーがない（代替料金の有無にかかわらず）、発送元の郵便番号または国がない、または既定の通貨が USD 以外で為替レートがない、といった場合です。テスト用の API キーが設定されている場合は注意書きが表示され、ストアの重量単位または長さの単位（System > Settings > Option）が拡張機能で認識される単位（kg、g、lb、oz、cm、mm、m、in）でない場合は警告が表示されます。

保存時、64 文字を超える名称、整数ではない Sort order、または不明な税クラスやジオゾーンがあると保存が止まり、何も保存されません。数値ではない値（または負の値）は保存されません。警告でその欄が示され、前の値が保持されます。他の設定は保存されます。USD exchange rate が 0 の場合、または Minimum weight が Maximum weight より大きい場合も、同様になります。

一般

Enable EasyPost shipping: チェックアウトでこの方法を提供します。これは Extensions > Extensions > Shipping における拡張機能の状態です。既定値: オフ。

Name: チェックアウトで購入者に表示される配送方法の名称。64 文字以内。既定値: EasyPost Shipping。名称が空の場合は既定の名称が使われます。文字 < > ; = # { } を含む名称は、警告とともに既定の名称に置き換えられます。

Sort order: チェックアウトの配送方法の中での、この方法の表示順。整数。

EasyPost アカウント

API key: EasyPost Dashboard > Account Settings > API Keys にある EasyPost の API キー。本番キー（EZAK で始まる）は実際の運賃を返します。テストキー（EZTK で始まる）は EasyPost のテスト運賃を返します。テスト目的でのみ使用してください。保存後、この欄は空になり、保存済みのキーがマスクされた形で表示されます。例: Saved key: EZAK******abcd. Leave the field empty to keep it. 変更する場合にのみ新しい値を入力してください。キーがない場合は、代替料金のみが使われます。

Remove the saved API key: 有効にして Save をクリックすると、保存済みのキーが削除されます。

Allowed carriers / services: 任意。カンマ区切りで入力します。EasyPost の名称どおりに、運送会社（USPS）、または運送会社とサービス（USPS:Priority、UPS:Ground）を入力します。許可された中で最も安い運賃が表示されます。空欄の場合は、どの運送会社の中でも最も安い運賃が表示されます。

発送元

荷物を発送する住所です。Country がストアの国である場合、空欄の Sender name / company はストア名から、空欄の State はストアの地域（System > Settings）から取得されます。OpenCart にはストアの郵便番号がないため、郵便番号はここで入力する必要があります。

Sender name / company: 差出人の名前または会社名。空欄の場合はストア名が使われます（同じ国の場合のみ）。

Street address: 発送元住所の番地。

City: 発送元住所の市区町村。

State: 2 文字の州コード（例: CA、NY）。

ZIP code: 発送元住所の郵便番号（例: 94105）。リアルタイムの運賃には必須です。

Country: 発送元の国。既定値: United States。

運賃

Parcels: カートを EasyPost にどのように送信するか。

重量はストアの重量単位からオンス（最小 1 oz）に、寸法はストアの長さの単位からインチに換算されます。寸法のない商品が 1 つでもある場合は、荷物は重量のみで計算されます。

USD exchange rate: EasyPost の運賃は USD で表示されます。ストアの既定通貨での 1 USD の価格を入力します（例: 0.92）。これがない場合、リアルタイムの運賃は使われず、代替料金のみが使われます。既定の通貨が USD の場合は不要です。USD および CAD のストアは、EasyPost に自国の通貨で見積もりを出すよう求めます。小数点区切りとして、ピリオドとカンマのどちらも使用できます。

Tax class: 配送料に適用される税クラス、または No tax。EasyPost の運賃には売上税は含まれません。

代替料金

リアルタイムの運賃がないときに使われます。API キーがない、EasyPost に接続できない、キーが拒否された、またはどの運送会社もその住所の運賃を持っていない場合です。料金はストアの既定通貨で、税抜きです。その場合に方法を非表示にするには、両方の欄を空欄にします。

Country prices: 国ごとに 1 行、2 文字の国コード、コロン、料金の形式で入力します（例: US:9.99）。別の形式の行は無視され、保存時に警告で一覧表示されます。

Other countries: 上の一覧にない国の料金。空欄にすると、それらの国では方法を非表示にします。

条件

Free shipping from: カートの小計（配送対象の商品、クーポン適用後、税抜き、既定の通貨）がこの金額以上の場合、配送料は無料になります。この場合は EasyPost へのリクエストは行われません。空欄にすると無効になります。

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

Minimum weight: カートの重量がこれより軽い場合は、この方法を非表示にします。単位はストアの重量単位（欄のラベルに表示されます）です。0 は制限なし（既定）を意味します。

Maximum weight: カートの重量がこれより重い場合は、この方法を非表示にします。単位はストアの重量単位です。0 は制限なし（既定）を意味します。

利用可否

通常は、ジオゾーンによってこの方法を提供する地域が決まります。代わりに、ジオゾーンとは無関係に国ごとに提供することもできます。

Geo zone: このジオゾーン内の住所に対してのみ、この方法を提供します。All zones（既定）は制限なしを意味します。ジオゾーンは System > Localisation > Geo Zones で管理します。Ignore shipping zones と併用しません。

Ignore shipping zones: ジオゾーンに含まれるかどうかにかかわらず、以下の国でこの方法を提供します。

Countries: このモードで対象となる配送先の国。空欄の場合は、ストアで有効になっているすべての国を使用します。この欄は Ignore shipping zones がオンのときにのみ使われます。

詳細設定

Debug log: EasyPost へのリクエストを storage/logs/vfd_ep.log.php（OpenCart 4 では system/storage/logs/vfd_ep.log.php）に書き込みます。このファイルは Web から読み取ることはできません。5 MB に達すると、vfd_ep.old.log.php に移動され、新しいログが始まります。このオプションがオフでも、API のエラーと警告は常に記録されます。API キーと購入者の住所は、決してログに記録されません。

Log: ログのサイズと最新の 100 行を表示します。Clear log をクリックすると内容を消去します。

Remove data on uninstall: オンにすると、拡張機能をアンインストールしたときに、その設定とログが削除されます。注文済みの注文の EasyPost データは保持されます。この方法を無効にしても、設定は削除されません。

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

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

Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定を復元します（例: 別のストアへの移行）。値は通常の保存時と同じように検証されます。保存済みの API キーは変更されません。

チェックアウトでの動作

OpenCart が配送方法を表示するとき、拡張機能に EasyPost の料金を問い合わせます。Geo zone が設定されていて（かつ Ignore shipping zones がオフ）、住所がそのゾーン外である場合、この方法は提供されません。Requires Shipping が Yes に設定された商品だけが計算に含まれます。それ以外の商品は重量を加算せず、小計にも含まれません。拡張機能は最初に条件を確認します。届け先の国（Ignore shipping zones の場合）、カートの重量、最低小計です。小計は、クーポン割引後、税抜きの、配送が必要な商品の価格です。ギフトカード、ポイント、ストアクレジットは計算に含まれません。送料無料が適用される場合、料金は 0 になり、EasyPost へのリクエストは送信されません。

それ以外の場合、拡張機能は発送元の住所、配送先の住所、荷物を EasyPost に送信し、すべての運送会社アカウントの運賃を受け取ります。許可された中で最も安い運賃を選び、ストアの既定通貨に換算して、選択された Tax class の税額を含めて、購入者の通貨で表示します。System > Localisation > Countries で Postcode Required とマークされた国の場合、配送先の住所に郵便番号がある場合にのみリクエストが行われます。OpenCart の標準データでは、アメリカ合衆国についてこのフラグは無効になっているため、郵便番号のないアメリカの住所も送信されます。その場合、EasyPost はエラーを返し、代替料金が使われます。

各応答は、同じ住所と同じ荷物について 1 時間キャッシュされます。使用可能な運賃がない住所は 10 分間記憶されます。タイムアウト、キーの拒否、レート制限、EasyPost のサーバーエラーの後は、5 分間リクエストは行われません。API のタイムアウトは 10 秒です。これらすべての場合、購入者にエラーは表示されません。代替料金が使われるか、代替料金がない場合は方法が非表示になります。理由はログに書き込まれます。

本拡張機能が行うのは運賃の計算のみです。ラベルの購入、荷物の追跡、住所の検証、受け取りや持ち込みの拠点の提供、保険や署名オプションの追加は行いません。表示されるのは 1 つのオプション（許可された中で最も安い運賃）であり、サービスの一覧ではありません。商品を 1 つの荷物にまとめる以外に、箱の最適化は行いません。運賃へのマークアップや手数料も加えません。

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

注文

EasyPost の方法で注文が行われると、チェックアウトに表示された運賃が注文とともに保存されます。管理画面の注文ページ（Sales > Orders）には、履歴の上に EasyPost shipping パネルが表示されます。

Carrier / service: 運賃の EasyPost の運送会社とサービス。例: USPS Priority。商品ごとに 1 つの荷物のモードでは、使用されたすべてのサービスが一覧表示されます。

Estimated delivery days: EasyPost が返した配達日数（注文ごとに 1 つの荷物のモードで、EasyPost が返した場合のみ）。

Price source: Live EasyPost rate、Fallback price (no live rate)、または Free shipping threshold。

Calculated price (excl. tax): ストアの既定通貨での料金。

拡張機能が後で無効にされても、このパネルは表示されます。その後に管理画面で注文を変更しても、これらの値は変わりません。これらを使って、EasyPost アカウントでラベルを購入してください。チェックアウトが確認の手順に進むたびに、OpenCart は注文レコードを作成します。そのような未完了の注文に保存された運賃は、30 日後に削除されます。

OpenCart 4 では、チェックアウトは 1 つの注文を保持し、購入者が再度確認するたびにその注文を更新します。保存された運賃もそれに合わせて更新されます。これは、購入者がチェックアウトで見た運賃です。購入者が別の配送方法に切り替えると、その注文についてはパネルが表示されなくなります。

ライセンスキー

本拡張機能は、vibefox.net で入手した VibeFox ライセンスキーで動作します。License — VibeFox EasyPost のライセンスブロックは、Extensions > Extensions > Shipping > VibeFox EasyPost > Edit の最初のブロックで、設定の上にあります。License key にキーを貼り付け、Activate をクリックしてください。その後、ブロックにはキーがマスクされた形で、ステータス（例: ライセンスの有効期限日とドメイン）、そして Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: opencart-shipping-easypost の行と、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 のアカウントで枠を解放してください。

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

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

トラブルシューティング

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

リアルタイムの運賃が表示されない: 拡張機能のページ上部の警告を読み、Debug log をオンにして、チェックアウトを再読み込みし、Log の欄を確認してください。よくある原因: API キーや発送元の郵便番号がない、USD 以外のストアで USD exchange rate がない、配送先の住所にまだ郵便番号がない、EasyPost アカウントのどの運送会社もその住所に対応していない、または Allowed carriers / services がすべての運賃を除外している。

運賃がテスト価格のように見える: テストキー（EZTK...）が設定されています。実際のストアでは本番キー（EZAK...）を使用してください。

運賃が数分間停止した: タイムアウト、キーの拒否、または EasyPost のサーバーエラーの後、拡張機能はリクエストを 5 分間停止し、代替料金を使います。API キーとログを確認してください。

税は含まれていますか？ EasyPost の運賃には売上税は含まれません。配送料に税を加える場合は、Tax class で税クラスを選んでください。

変更後に運賃が古いように見える: 拡張機能のページで Save をクリックしてください。これによりキャッシュされた EasyPost の運賃が消去されます。

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

開発者向け: 他の拡張機能は、OpenCart のイベント vfd_easypost/shipment_request、vfd_easypost/selected_rate、vfd_easypost/api_url により、リクエストの本文、選択された運賃、API のベース URL を調整できます。

アンインストール

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

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

EasyPost は、それぞれの所有者の商標です。本拡張機能は EasyPost と提携しておらず、EasyPost による承認もありません。