Shopifyのカスタムアプリを受託開発していると、「開発が終わった＝運用を始められる」という認識のズレに何度もぶつかる。とくに配送・決済・外部SaaSと連携するアプリでは、コードが完成してもすぐには本番が回らない。実際に稼働日を決めるのは、開発の進捗ではなく、外部サービスの契約手続きやAPIキー発行のリードタイムだ。当社では、この「システム納品日」と「実運用開始日」を最初から別物として扱うことにしている。この記事では、配送連携アプリを例に、本番稼働前につまずきやすいポイントと、当社が使っている本番投入チェックリストの考え方を共有する。受託開発を発注するEC事業者と、それを請け負う技術者の双方に役立つはずだ。
「システム納品」と「実運用開始」は別の日である
配送管理のアプリを開発し、本番ストアへインストールまで完了した。ここでよくある誤解が、「では明日から出荷できますね」というものだ。実際には、送り状発行サービス（配送SaaS）のAPIキーが未設定で、配送会社との連携も済んでいなければ、注文の取り込みや担当への振り分けは動いても、肝心の送り状発行はできない。
だから当社では、進捗を伝えるときに工程を正確に区切る。「送り状発行より前の工程（注文取込・振り分け・ポータルでの注文確認）までは動作します。ただし送り状の発行以降は、配送連携とAPIキーが揃うまで検証できません」といった具合だ。「アプリが動く／動かない」の二択ではなく、どこまで動いてどこで止まるのかを明示する。これをやらないと、「納品されたのに使えない」という不満が生まれる。納品はあくまでシステムの引き渡しであり、実運用の開始日は外部条件が揃った後にしか決まらない――この線引きを、契約と報告の両方で徹底する。
外部連携のリードタイムが、全体の日程を支配する
配送連携で最も長い待ち時間を生むのが、配送会社との契約とAPI利用手続きだ。ここは開発側では短縮できない。
すでに法人契約がある配送会社なら比較的速い。たとえば送り状発行サービス経由で連携する場合、既契約の会社は顧客コードを登録して連携をリクエストすれば、先方のシステム側で手続きが進み、案内が返ってくる。一方、未契約の配送会社を新たに使う場合は、法人契約の新規申請からアカウント取得、外部システム連携用の認証キー取得まで数週間かかることがある。しかも認証キーは発行した当日ではなく翌日以降に有効になる、といった細かな制約もある。こうしたリードタイムを見落として「納品日＝運用開始日」で握ってしまうと、物理的に間に合わない。
当社の進め方としては、最も時間のかかる新規契約の申請を「今日にでも着手してください」と最優先で依頼し、それと並行して開発側は連携待ちの間にストア側の準備とテストモードでの受入確認を消化する。全体のクリティカルパスを握っているのが自社の開発ではなく相手先の契約手続きである、という前提で段取りを組むわけだ。契約が間に合わない配送会社があれば、先に使える会社だけでリリースし、残りは契約開通後に有効化する段階リリースを提案する。
もうひとつ見落としがちなのが、契約運賃テーブルの登録だ。配送SaaSに契約運賃を登録しておかないと、料金取得APIが割引前の公開料金を返してしまい、精算に使う概算運賃が実態とずれる。連携できたつもりでも数字が合わない、という事故はここで起きる。
発注者側の設定と、外部サービスの仕様前提を確認する
外部連携アプリは、アプリのコードだけでは完結しない。ストア側の設定や外部サービスの仕様前提に、動作が依存している。
ストア側では、たとえば商品の販売元（vendor）の名義が、アプリ側で想定している発送元の名義と完全一致している必要がある。ここがずれると「どこから送るか割り当てられない注文」が生まれ、本番の動作確認ができない。冷蔵・冷凍のような区分を扱うなら、対応するメタフィールドの定義とデータ投入も要る。当社の経験では、メタフィールド定義の作成APIが将来削除されるといった変更もあり、その場合は管理画面から手動で作成するしかない。こうした「アプリの外側にある前提」を洗い出し、誰が・いつ設定するのかを分担表にしておかないと、テストの直前で足を取られる。
外部サービス側の仕様前提も要注意だ。配送会社の中には、出荷元住所や送り状のレイアウトが顧客コードに紐づいてマスタ登録されており、ひとつの顧客コードでは差出人を切り替えられない、という仕様のものがある。「発送元ごとに差出人名義を変えたい」という要件があるなら、それが契約している顧客コードの範囲で成立するかを、契約状況の確認と同じタイミングで先方に確認しておく必要がある。ここが崩れると設計の前提そのものが変わってしまうため、最優先で潰しておく論点だ。
本番投入は「設定」と「切り替え」の落とし穴が多い
コードが正しくても、本番環境の設定投入でつまずくことは多い。当社が本番投入前に必ず確認する項目には、たとえば次のようなものがある。テストモードのフラグを明示的に本番値へ切り替えること（未設定だと起動時エラー、テストのままだとテスト用ラベルが発行され続ける）。配送会社ごとのサービス区分を示す設定値を漏れなく入れること（欠落すると発行時にエラーが返る）。メール送信ドメインの認証とサンドボックス解除（招待・承認・パスワードリセットなどのメールが本番アドレスへ届く状態にする）。監視アラートの通知先設定と、その購読承認。旧データや旧環境変数のバックアップと除去。そしてアプリのスコープを本番へ正しく反映することだ。
加えて、異常系の復旧手順を用意しておく。処理が中間状態に入ったまま自動では戻せない経路が残っているなら、その復旧手順書を用意するか、実装で塞ぐかを判断しておく。発生確率が低くても、起きたときにデータベースを手作業で直すしかない状態は、運用開始直後の問い合わせ対応を苦しくする。発送後に追跡番号を確認する画面のような「運用が始まってから毎日使う機能」も、リリース前に抜けていないか点検する。
受入テストは、本番ストアでテストモードのままシナリオを一通り通し、配送会社ごとに実機で1件ずつ確認し、最後にテストモードを解除して1件だけ実物のラベルを発行して目視する、という順で段階的に進める。いきなり全部を本番モードにしない。
まとめ
外部連携を伴う受託アプリでは、本番稼働日を決めるのは開発の進捗ではなく、配送会社の契約やAPIキー発行といった外部のリードタイムだ。だから当社では「システム納品」と「実運用開始」を最初から別の日として定義し、最も時間のかかる外部手続きを先頭に置いて段取りを組む。ストア側の設定や外部サービスの仕様前提はアプリの動作を左右するので、誰がいつ設定するかまで分担を決めておく。本番投入では設定値の切り替えと異常系の復旧手順に落とし穴が多く、受入テストは段階的に進めるのが安全だ。「作れば動く」ではなく「動かすために外部条件をどう揃えるか」を工程として設計すること――これが、受託アプリを予定どおり本番稼働させるための実務の勘所である。