WMSオープンAPI: 避けるべき5つの統合の落とし穴

結論から先に言うと、WMSと社内システム(ERP、OMS、財務)の統合が破綻するとき、その原因はほぼ間違いなく「WMSのオープンAPIが難しい」ことではない。破綻するのは、チームが「APIコールが動いた」を「統合が完了した」と勘違いするからだ。1つのエンドポイントは半日でできる。本番対応の統合には最低2週間かかる。その差が下の5つの落とし穴であり、私が見てきた統合失敗の大半はこれが原因だ。各落とし穴:症状→根本原因→対策→チェックリスト。チェックリストは本番前夜のリストにコピーしよう。

落とし穴1: マスタデータのマッピングなし——ゴミ注文が入ってくる

症状: ERPからWMSに販売注文を送ると、WMSは大半を「品目が見つからない」として却下する。さらに悪いことに、品目は存在するのに間違ったものだったりして、間違った商品が出荷される。在庫同期も壊れる:WMSの利用可能数量がERPの帳簿と一生一致しない。

根本原因: 2つのシステムがマスタデータを共有していなかった。ERPの品目コードは10年前に仕入先プレフィックスを埋め込んだ形で定義された。WMSは新しい社内SKUを使っている。ロケーション、運送会社、顧客——あらゆるコード表が二重に存在する。APIはフィールドを運ぶだけ。意味が合っているかはチェックしない。

私はこの失敗を3回見てきた。最悪だったのは、2024年11月のピーク前に本番稼働したカリフォルニアの自動車部品3PLだ。ERPは仕入先バーコードで品目をキーにし、WMSは社内SKUでキーにしていた。そして初週、全注文ダウンロードのほば3分の1が例外キューで死んだ——ピッカーにはタスクが見えず、スーパーバイザーには「出庫済み」と見えていた。対策は地味だった:一夜で作ったマッピング表、ダウンロード前のバリデーション、手作業の例外プール、滞留が解消するまでのダウンロード凍結。ピーク初週の4日間は火消しだった。

対策:

4つのコード体系——品目、ロケーション、運送会社、顧客——のマッピング表を作り、ITだけでなく事業オーナーに承認してもらう。
送出側のインターフェースはすべて事前バリデーションする。マッピング表にないコードは却下してログに残す——「送ってから後で対応」は絶対にしない。
新規コードと無効化コードを両システム間で日次照合し、差分をデータオーナーにメールする。例外プールにはオーナーとSLA(たとえば4時間)を置く。ゴミ箱ではない。

チェックリスト: マッピング承認済み、事前バリデーション稼働中、照合テスト済み、例外オーナー割当て済み。

落とし穴2: APIをリアルタイムのパイプ扱い——ピーク初日にレート制限

症状: 通常週は問題なし。ところがプロモーションや月末が来ると、WMSのAPIコールが一斉にタイムアウトし始め、注文ダウンロードの遅延が数秒から数十分に伸び、ベンダーのレートリミッターが統合全体を冷たく停止させることもある。

根本原因: 近道をした——社内システムがWMSのAPIを直接ポーリングするか、リアルタイムにプッシュする:在庫確認を数秒ごとに、1注文1コール。すべてのオープンAPIにはコール頻度の上限がある(契約前に書面でもらうこと)。少ないボリュームでは触らないが、ピークのボリュームは真正面からぶつかる。バックオフなしのリトライは、すでに過負荷のエンドポイントをさらに叩く。

対策:

統合層とWMSの間にメッセージキューを置く。社内システムはメッセージを投げるだけ。コンシューマが持続可能なレートでWMSを呼ぶ。ピークはバックログを作るだけで、破壊しない——遅い方が死よりマシだ。
在庫や注文ステータスは、ポーリングよりWMSからのプッシュコールバックを優先する。どうしてもポーリングするなら、5分と5秒では運用上ほぼ変わらない——負荷は1桁違う。
すべてのコールに冪等キー——同じトランザクション2回プッシュしても実行は1回。リトライはバックオフし、3回失敗したらメッセージはデッドレターキューへ。

チェックリスト: キュー配備済み、レート制限を書面で取得、冪等性をエンドツーエンドで、リトライ上限あり。

システム統合のデータフロー

落とし穴3: ハッピーパスしか実装していない——タイムアウトが注文を静かに落とす

症状: 最もたちが悪い落とし穴。コールがタイムアウトする。社内システムは失敗と判断して再送する——でもWMSは受信済みで、失われたのは応答だけだった。同じ注文が2回ダウンロードされ、2回ピッキングされる。あるいは100件のバッチを送り、97件が処理され、インターフェースは全体として成功を報告し、3件の注文が照合の日まで消える。

根本原因: 開発が正常系だけテストした。タイムアウトの意味——成功か失敗か——を誰も定義していない。バッチが部分成功したとき、誰が各行のステータスを解析するのか。書かれていないし、テストもされていない。本番前に皆が聞くのは「つながるか」。「壊れたらどうなるか」を聞く人は誰もいない。

対策:

タイムアウトのセマンティクスをインターフェースごとに定義して文書化する。読み取りは安全にリトライできる。書き込みは、タイムアウト後の再送前にステータスを確認する。盲目再送はしない。
バッチ応答は行ごとに解析する——すべてのドキュメントの結果をログに残す。全体の「成功」は各行の成功を意味しない。
日次照合(自社システムのステータス対WMS)を回し、差分は自動アラート。重要なインターフェースは障害下でリハーサルする——ケーブルを抜く、プロセスを殺す、タイムアウトを模擬する——システムが単独で回復することを証明するために。

チェックリスト: タイムアウトのセマンティクス文書化済み、バッチを行単位で解析、照合稼働中、障害訓練済み。

落とし穴4: セキュリティは最後に付け足し——1つのキーですべてを支配

症状: 本番1週間前に誰かが認証を思い出す。キーを1つ生成し、統合プログラムの設定にハードコードし、ERPもOMSも財務も共有する。半年後、作った開発者が退職し、キーは彼と一緒に去り、誰もローテーションに踏み切れない。

根本原因: セキュリティが機能より後回し。「まず動かす」。キーの問題は本番まで先送りされ——その後は怖くて触れない。

対策:

呼び出し元ごとにキーを分ける——ERP、OMS、財務にそれぞれ専用のキー。1つのシステムに問題があっても、そのキーだけ失効させれば他には触らない。
キーごとに最小権限:在庫読み取り専用キーでは注文をダウンロードできない。すべてのキーはシークレットマネージャーに置き、平文では絶対に置かない。
周期的にローテーションする(たとえば6か月)。最初のローテーションは本番1か月後に回す。まだ全員が手順を覚えているうちに。

チェックリスト: キー分離済み、最小権限、シークレットマネージャー、ローテーション訓練済み。

落とし穴5: サンドボックスで動いたから出す——その夜本番が爆発

症状: サンドボックスでは200注文が飛ぶ。本番の夜は2,000注文が統合プログラムを押しつぶす。あるいはサンドボックスのWMSが本番より1マイナーリリース遅れ、1つのフィールドの挙動が違い、本番が一晩中バッチエラーを吐く。

根本原因: サンドボックスと本番は別の世界だ。データ量は10倍、データはずっと汚い、ネットワークも違う。サンドボックスだけでテストするのは、教習所の構内で練習してそのまま高速に合流するようなものだ。

対策:

本番前にピークの1.5倍で負荷テストする——ストレステストするのはWMSではなく自社コードとキューだ。自分のボトルネックを先に見つけろ。
マスクした本番データでサンドボックスでフル回帰テストをリプレイする。汚いデータを探す:欠けたコード、特殊文字、長すぎるフィールド——いつも想像よりひどい。
サンドボックスと本番のバージョン一致を確認し、ベンダーの変更ノートをもらう。ロールバックをリハーサルする。統合が死んだら、1つのアクションで手動に戻せるか。バックフィルはどうやるか。全員が両方の答えを暗記していなければならない。

チェックリスト: ピーク1.5倍の負荷テスト、マスクデータ回帰済み、バージョン一致確認済み、ロールバック訓練済み。

直感に反する見方

APIドキュメントが最も充実し、エンドポイントが最も多いWMSこそ、統合で最も痛い目に逢う。

逆に聞こえるが、30以上のプロジェクトで成り立っている。ドキュメントが充実したベンダーは細粒度のエンドポイントを公開する——「注文ダウンロード」1つが5つか6つのインターフェースに分かれ、それぞれに任意フィールドがある。実装者は「全部」統合し、サーフェスが広いほど落とし穴は増える。すべてのフィールドの意味を合わせ、すべてのエラーブランチを処理する。ドキュメントが薄くコアなエンドポイント20個のWMSは、生死を分けるフロー——ダウンロード、コールバック、在庫確認——だけに絞らざるを得ない。サーフェスが小さければ、失敗の仕方も少ない。

だから「200+のオープンAPI」に目を奪われるな。3つの質問をしよう。コアフローに必要な最小エンドポイントは?レート制限は——契約に入っているか?サンドボックスと本番の一致は——書面にあるか?答えがなければ、エンドポイント数は飾りだ。トレードオフを一言で言うと:統合の深さと統合コストは必ず一緒にスケールする。コアなエンドポイント5つで済むなら、50個を「きちんと」統合するな。統合サーフェスは継続的な保守であり、ターンキー納品ではない。