数千社提携の政府系API連携で学んだ設計の教訓

ClassLab Engineering の Dev チームメンバーが執筆しました。

この記事は、外部API連携・SOAP/REST設計・SSL認証管理に興味があるバックエンド/インフラエンジニア向けです。

1. 背景

ClassLab は数千社超のパートナー企業と連携し、年間15万件超のライフライン（電気・ガス・水道）申込を処理しています。この処理の中核が、電力広域的運営推進機関（OCCTO）のスイッチング支援システムとのAPI連携です。

OCCTOのAPIはSOAP/WSDLベースで、SSL相互認証が必須です。RESTful APIが主流の現在において、SOAPベースの政府系APIと安定的に連携し続けるために得た教訓は、同様の外部API連携に取り組むエンジニアにとって参考になるはずです。

本記事では、前回の記事で紹介したシステム全体のアーキテクチャではなく、API連携を運用し続ける中で得た実践的な教訓にフォーカスします。

2. 課題

REST APIの経験だけでSOAP連携に臨むと、これらのギャップに一つずつ躓くことになります。

3. 設計（教訓として体系化）

教訓1: WSDLを信じすぎない

OCCTOのWSDLファイルは型定義とメソッド名を提供しますが、以下の点で仕様書（Excel）と照合する必要がありました。

• 任意項目の扱い: WSDLではminOccurs="0"でも、実際には送信しないとエラーになるフィールドがある
• 文字コード: WSDL上はUTF-8だが、一部フィールドでShift_JISエンコードが暗黙に期待される
• 日付フォーマット: XMLスキーマのdateTime型だが、実際はyyyyMMdd形式の文字列を期待

flowchart LR
    WSDL[WSDL定義] --> IMPL[自動生成コード]
    SPEC[Excel仕様書] --> VALIDATE[バリデーション層]
    IMPL --> |差異あり| FIX[手動補正]
    VALIDATE --> FIX
    FIX --> FINAL[最終実装]

教訓: WSDLの自動生成だけに頼らず、仕様書ベースのバリデーション層を別途構築する。この層がWSDLと現実のギャップを吸収する。

教訓2: SSL相互認証は「設定」ではなく「運用」

クライアント証明書のセットアップは初回だけの作業に見えますが、実際は以下の運用タスクが継続的に発生します。

// 証明書有効期限の自動チェック（日次バッチ）
$certPath = config('occto.client_cert_path');
// エラーハンドリングは省略（実装では証明書読み込み失敗時のアラートあり）
$certData = openssl_x509_parse(
    file_get_contents($certPath)
);
$expiresAt = Carbon::createFromTimestamp(
    $certData['validTo_time_t']
);
$daysLeft = now()->diffInDays($expiresAt, false);

if ($daysLeft <= 30) {
    // Slack通知: 証明書更新が必要
    $this->notifySlack(
        "OCCTO証明書の有効期限まで{$daysLeft}日です"
    );
}

教訓: 証明書管理を「初期設定」ではなく「運用プロセス」として設計し、有効期限監視と更新手順を自動化する。

教訓3: エラーの「原因」はAPIの外にある

OCCTO APIのエラーで最も厄介なのは、返却されたエラーコードだけでは原因が特定できないケースです。

たとえば再点申込（IF_10410）のエラーには以下の可能性があります。

• 供給地点特定番号が存在しない
• 既に別の小売事業者が申込済み
• 設備情報に問題がある（メーター交換中など）
• 前回の廃止手続きが完了していない

これらを切り分けるには、エラー発生時に追加で設備情報照会（IF_10110）と事業者一覧取得（IS_30110）を呼び出す必要があります。

flowchart TD
    ERR[申込エラー発生] --> INV[自動調査開始]
    INV --> EQ[設備情報照会]
    INV --> BIZ[IS_30110 事業者一覧取得]
    EQ --> |設備異常| R1[設備側の問題と判定]
    EQ --> |正常| BIZ
    BIZ --> |他社申込あり| R2[競合申込と判定]
    BIZ --> |なし| R3[OCCTO原文を返却]
    R1 --> SF[Salesforceに調査結果を自動記録]
    R2 --> SF
    R3 --> SF

教訓: 外部APIのエラーハンドリングは「エラーを捕捉する」だけでなく「エラーの原因を調査する」仕組みをセットで設計する。

教訓4: バッチの「部分失敗」は正常系

数百件の申込を一括処理するバッチでは、全件成功を前提にした設計は機能しません。部分的な失敗が日常的に発生するため、以下の設計が必要です。

• 個別レコード単位のtry-catch: 1件の失敗が残りの処理を止めない
• 失敗レコードの調査結果付きレスポンス: 失敗理由をレスポンスに含める
• 冪等性の確保: 同じバッチを再実行しても二重処理にならない

教訓: バッチ処理では「全件成功」を正常系、「部分失敗」を異常系と考えるのではなく、「部分失敗」を正常系として設計する。

4. 実装（モックテスト戦略）

OCCTO APIの実体はSSL相互認証付きSOAPエンドポイントであり、テスト環境でも本番同様の証明書設定が必要です。開発効率を維持するため、3層のテスト戦略を採用しました。

3層テスト

// L2: モックレスポンスを使ったテスト
public function test_relight_success(): void
{
    // OCCTO実APIのXMLレスポンスを保存したファイルから読み込み
    $mockXml = file_get_contents(
        base_path('occto_mock_responses/IF_10410/success.xml')
    );

    $this->mock(SoapHttpClient::class)
        ->shouldReceive('__soapCall')
        ->andReturn(
            simplexml_load_string($mockXml)
        );

    $response = $this->postJson('/api/occto/sf/relight', [
        // テスト用の架空値（実在しない供給地点特定番号）
        'supplyPointId' => '000000000000000000000',
        'retailerCode' => 'X9999',
    ]);

    $response->assertStatus(200)
        ->assertJson(['status' => 'success']);
}

教訓: 外部APIのテストは「モックで完結」ではなく、実際のAPIレスポンスXMLを保存してモックの材料にする。本番で遭遇した新しいエラーパターンは随時モックに追加する。

5. 結果（数値）

特に教訓3（エラー自動調査）の効果は大きく、オペレーターの手動調査時間が実質ゼロになりました。

6. 展望

次に取り組む課題

• SOAP–>REST移行のアダプタ設計: OCCTO側のAPI刷新に備え、プロトコル非依存のサービス層を一緒に設計してくれるエンジニアを探しています
• エラーパターンのナレッジベース化: 蓄積されたエラーパターンから自動分類・自動対処を構築する予定です

関連記事

• 15万件/年のライフライン基幹システムの信頼性設計 — 本記事のシステム全体のアーキテクチャ
• Claude CodeとGitHub Copilotを全員が使う開発チームの実態 — AI駆動開発で本システムも構築

採用情報

ClassLab では、政府系APIや大規模外部連携の設計・改善を一緒に進めてくれるバックエンドエンジニアを募集しています。SOAP/RESTを問わず、外部連携の実務経験を活かせるポジションです。

• Findyでカジュアル面談する
• 採用情報を見る