EC-CUBEにCSV一括注文を追加｜品番・数量の取り込みとエラー対応

CSV一括注文は、発注明細をカートへ取り込む仕組み

取引先が発注明細をExcelや基幹システムで作っている場合、ECサイトでも同じ品番と数量を入力し直す作業が発生します。CSV一括注文は、その明細をファイルで読み込み、入力の手間を減らすための仕組みです。

この記事で扱うのは、購入者が商品コードと数量をアップロードしてカートへ反映する機能です。運営者が管理画面から受注データを登録・更新するCSV取り込みとは、利用者も処理内容も異なります。また、カートへの反映と注文確定は別の段階です。

サンクユーでは、EC-CUBEにCSV一括注文機能をカスタマイズで追加しました。以下の画像は過去の導入例であり、EC-CUBEの標準画面や、すべての環境に共通する仕様を示すものではありません。

発注書を見ながら画面へ入力する方法は、品番・数量を入力する一括注文フォームの記事で紹介しています。明細数だけでなく、取引先がどのように発注データを作っているかで使い分けます。

過去の導入例：CSVを作成し、カートの内容を確認する

1．商品コードと数量をCSVにする

この事例では、「商品コード」と「数量」の2項目をカンマで区切り、1行ごとに商品を指定します。画像の1行目は項目名で、その下に発注明細が並んでいます。新しく導入する場合も、配布するひな形と取り込み側の仕様をそろえることが出発点です。

2．ファイルを選び、一括登録を実行する

専用画面でCSVファイルを選び、「一括登録を実行」を押します。画面にはひな形のダウンロードと、商品コード・数量の説明が用意されています。

この画面の仕様は、既存カートに同じ商品があればCSVの数量で上書きし、数量0を指定するとその商品を削除するものです。一般的なCSV注文すべてに当てはまる動作ではありません。加算・上書き・削除のどれが起きるかは、利用者がアップロード前に分かるように案内します。

3．完了表示の後、カートを確認する

処理が正常に終わると、カートへの追加を知らせるメッセージが表示されます。ここで完了したのはカートへの反映であり、注文そのものではありません。

商品・規格・数量・適用価格を確認し、配送先や支払方法などの購入手続きへ進みます。取引先の社内承認が必要な場合は、承認申請と正式な注文確定のタイミングも分けて設計します。

CSVの形式と、品番を変換しない作り方を決める

ひな形と取り込み条件を一致させる

同じ「商品コード・数量」のCSVでも、列の順番や文字コードが違うと正しく読み込めない場合があります。利用者に毎回判断させず、ひな形、画面の説明、エラーメッセージを同じ仕様にそろえます。

文字コードやBOMの扱いは、元の画面だけでは判断できません。実装の仕様を確認して明示します。CSVは単純にカンマで分割するだけでは、引用符で囲まれた値などを正しく扱えないため、定めた形式に対応した読み込み処理が必要です。

Excelでは商品コードを文字列として扱う

商品コード「00123」が「123」に変わると、別の商品として判定されたり、該当なしになったりします。長い数字や一部の英数字も、数値・指数・日付などへ自動変換される場合があります。

Excelで作成・読み込みを行う際は、商品コードを入力・取り込みする段階で文字列として扱います。CSVを開く際のデータ型の指定については、Microsoft公式のテキスト・CSVファイルのインポート／エクスポート資料も参考になります。

先頭の0が消えた後に表示形式を文字列へ変えても、元のコードを復元できるとは限りません。CSV内の値を引用符で囲むだけでも、自動変換を確実には防げません。保存後のCSVに正しいコードが残っているか、取り込み結果の商品名・規格と合わせて確認します。

商品・規格・数量を照合し、現在の取引条件を適用する

CSVの商品コードから、注文する色・サイズなどの規格まで特定できるようにします。取引先独自のコードやメーカー品番を使う場合は、EC-CUBE側の商品・規格との対応関係も必要です。対応が曖昧なコードを、似た商品へ自動で置き換えないようにします。

数量は、何を数えているかを明示します。1ケース10個の商品で数量2を指定した場合、2個なのか2ケースなのかによって納品数が変わります。最低注文数と注文単位も分けて確認し、例えば最低10個・5個単位の商品なら、12個は条件を満たさないと案内します。

取引先別価格、数量別価格、公開範囲、販売可否、在庫は、現在の取引条件に基づいて確認します。CSVに価格列を追加する場合も、その値を無条件に販売価格として採用せず、適用する単価をサーバー側で判定します。

取引先に公開していない商品は、コードを直接指定されても商品名や価格を返さない設計が必要です。また、カート反映時に在庫があっても注文確定までに変わるため、購入手続きでも在庫と販売条件を確認します。

EC-CUBE 4系では、既存のカート・購入手続きの検証や集計処理との整合を確認します。公式の購入フローのカスタマイズ資料を参照し、CSVからの操作にも必要な価格計算や販売条件の判定を適用します。

エラー行と反映結果を示し、修正後の再取り込みにつなげる

100行のCSVのうち1行に問題があった場合、全件を止めるのか、正常な行だけ反映するのかで、利用者の修正手順は変わります。まずファイル全体を検証し、実際にカートを変更する前に処理方針を決めておくことが大切です。

例えば「CSVの12行目：数量が注文単位に合いません」のように、元ファイルの行番号と原因を示します。商品コードの不一致、数量不足、在庫不足、形式違反を区別し、修正可能な内容が分かる表示にします。

項目名の行や空行を含めた行番号の数え方も、元ファイルと対応させます。エラー行を別ファイルで返す場合は、どの列を直せばよいかを示し、そのファイルを再取り込みできる形式にするかも決めます。

「処理完了」だけでは、全件反映されたのか判断できません。確認した明細数、反映した件数、未反映の件数を示し、商品ごとの最終数量をカートで確認できるようにします。

CSV内の重複・既存カート・再アップロードを分けて扱う

同じ商品が複数回登場する場面は、一つではありません。CSV内の重複行、既存カートとの重複、通信後の再送を区別して仕様を決めます。

• CSV内に同じ商品が複数行ある場合は、合算するか、重複として修正を求めるかを決める。
• 既存カートに同じ商品がある場合は、加算するか、CSVの数量へ上書きするかを明示する。
• 数量0を削除指示として使う場合は、削除対象を事前に示し、空欄を0と解釈しないようにする。
• CSVに含まれない既存の商品を残すのかも説明し、カート全体の置き換えと区別する。

例えばカートに3個ある商品を数量5のCSVで取り込むと、加算なら8個、上書きなら5個になります。同じファイルをもう一度取り込むと、加算方式ではさらに増えるおそれがあります。上書き方式でも、利用者が後から直した数量を戻してしまう可能性があります。

二重クリックを防ぐ画面制御に加え、サーバー側で同じ取り込み処理が完了済みかを確認します。通信が途切れて結果が分からない場合は、すぐ再送させず、処理状況やカートの反映内容を確認できるようにします。

実際の発注データで、件数の上限と運用を確認する

一度に処理できる件数や時間は、サーバー環境、価格・在庫の連携、既存カスタマイズなどによって変わります。数百行・数千行でも必ず短時間で完了するとは限りません。通常の発注明細と上限付近のデータで検証して、容量・件数の上限を決めます。

先頭に0がある品番、長いコード、規格違い、ロット違反、欠品、重複行、数量0、形式違反を含むデータも確認対象にします。大量のエラーがあるときの表示や、ログイン期限切れ、通信切断後の案内まで試すと、運用時の問い合わせを想定できます。

導入後は、取り込みにかかる時間、エラーの多い項目、再取り込みの回数などを確認し、ひな形や説明を見直します。件数を増やせることに加え、取引先が誤りを見つけて直し、意図した注文内容へ進めることが重要です。

まとめ：CSVの作成から、修正・注文確認までを整える

CSV一括注文は、Excelや基幹システムで作った発注明細を活用できる仕組みです。品番と数量を正しく読み込むことに加え、現在の取引条件、エラー時の修正、既存カートへの反映、再送時の動作をそろえて設計します。