保証請求 SOAP API

  • リリースバージョン: Australia
  • 更新日 2026年06月17日
  • 所要時間:24分
  • 保証請求SOAP APIは、ディーラ・システムからの受信修理オーダーを処理し、Oracle Enterprise Manager (OEM)のプラットフォーム内で保証請求に変換します。

    この API は SOAP 1.1 規則 に従い、自動車サービスシステム間の相互運用性のために Standards for Technology in Automotive Retail (STAR) XML スキーマ を使用します。

    この API を使用すると、 ServiceNow Manufacturing Commercial Operations (MCO) とディーラー管理システム (DMS) の間で保証および修理請求情報を交換できます。具体的には、ユーザーは次のことができます。
    • ServiceNow MCO から直接 DMS で保証請求を作成して検証します。
    • 裁定や承認の結果など、送信された請求のステータスを照会し、その結果を ServiceNowに戻します。
    • 次の 3 つのコア MCO テーブルにわたる修理請求データを管理します。
      • 修理請求ケース [sn_repair_claim_mgmt_case]
      • 修理請求ケースライン [sn_repair_claim_mgmt_case_line]
      • 修理請求ケースライン費用 [sn_repair_claim_mgmt_case_line_charge]
    • 構成駆動型アダプターで STAR XML メッセージ形式をサポートし、カスタムコードなしで標準ベースの統合を可能にします。

    このドキュメントは、標準ベースの SOAP 統合を実装する開発者、システムインテグレーター、およびパートナーを対象としています。

    標準と規則

    API は、広く使用され、公開文書化された標準に準拠しています。

    アイテム 標準
    SOAP バージョン SOAP 1.1 (デフォルト);1.2 一部のパートナーでサポート
    WSDL WSDL 1.1
    XML スキーマ XSD 1.0 (スター XML)
    STAR スキーマバージョン 5.13.4
    文字エンコード UTF-8
    メッセージ形式 text/xml
    プロトコル HTTPS over TLS 1.2+;STAR パートナー向けのオプションの相互 TLS

    アクセスと認証

    • 基本認証 (ユーザー名/パスワード)
    • 構成可能 すべての DMS のエンドポイントごと

    詳細なロールとエンティティ

    この SOAP API には、特定の MCO 機能と責任にアクセスし、カスタム ACL なしで CRU 権限を提供し、サポートされているエンティティに直接マップするための詳細なロールが必要です。サポートされている詳細なロールの詳細については、「 詳細なロールとエンティティ 」を参照してください。

    エンドポイントの詳細

    保証請求 SOAP API は、 ServiceNow MCO でスクリプト化された SOAP Web サービスとして公開されます。

    https://<instance_name>.service-now.com/sn_mco_integ_RepairClaimSOAPHandler.do?SOAP

    WSDL:

    https://<instance_name>.service-now.com/sn_mco_integ_RepairClaimSOAPHandler.do?WSDL

    インスタンス名は、OEM 環境 (サンドボックス、テスト、本番) ごとに固定されています。

    URL 部分 説明
    <インスタンス名> MCO をホストする ServiceNow インスタンス (OEM 固有、OEM ごとに固定)。
    sn_mco_integ_ MCO 統合の名前空間。
    RepairClaimSOAPHandler.do スクリプト化された SOAP Web サービスエントリーポイント。
    ?SOAP SOAP 呼び出し。
    ?WSDL クライアント生成の WSDL 契約。

    API 操作

    操作名: ProcessRepairOrder

    修復オーダーのペイロードを処理します。この操作では、一致するビジネス識別子が既に存在するかどうかに応じて、作成アクションまたは更新アクションが実行されます。

    この操作では、次のことを実行します。
    • STAR スキーマに対して要求を検証します。
    • XML の値が MCO で有効であることを検証します。
    • 修理請求 (ドキュメント ID) が既に存在するかどうかを判定します。
    • 一致するものが見つからない場合は、新しいレコードを作成します。
    • 一致が見つかった場合は、既存のレコードを更新します。
    • 処理ステータスと参照識別子を返します。

    要求の構造

    要求本文に、SOAP エンベロープでラップされた STAR 準拠の ProcessRepairOrder メッセージが含まれています。主要な論理要素は次のとおりです。
    • アプリケーションメタデータ (送信者、作成時刻、宛先)。
    • 要求されたアクションを示すプロセス動作。
    • 修復オーダーヘッダー情報。
    • 車両の詳細。
    • ジョブ、労務、部品、および価格設定の詳細。
    • 保証請求情報。

    すべての要素は、ペイロードに示されている STAR XML スキーマバージョンに準拠している必要があります。

    要求パラメーター

    表 : 1. 受信要求パラメーター
    名前 ラベル 説明
    アクティビティステータス activity_status 必須。修理請求ケースラインの現在のライフサイクルステータスを示し、プレイブックの実行を推進します。

    テーブル:修理請求ケースライン [sn_repair_claim_mgmt_case_line]

    有効な値:
    • 請求の詳細が完了しました [claim_details_completed]
    • 完了した請求ジョブ [claim_jobs_completed]
    • レビュー中の請求が完了しました [claim_under_review_completed]
    • 請求ジョブの編集が完了しました [claim_job_edit_completed]
    • 請求サマリーが完了しました [claim_summary_completed]
    • 完了したケースを閉じる [close_case_completed]

    データタイプ:選択肢 (文字列)

    作業終了日時 actual_end オプション。修理アクティビティが完了した日時。

    形式:YYYY-MM-DDThh:mm:ss

    データタイプ:DateTime (文字列)

    実開始日 actual_start オプション。修理アクティビティを開始した日時。

    形式:YYYY-MM-DDThh:mm:ss

    データタイプ:DateTime (文字列)

    資産 asset 必須。請求のシリアル番号または資産タグ。

    テーブル:資産 [alm_asset]

    データタイプ:参照 (文字列)

    原因部品 product_model 必須。問題の根本原因として特定された部品のモデル番号。

    テーブル:製品モデル [cmdb_model]

    データタイプ:参照 (文字列)

    請求額 claimed_amount オプション。この特定の修理請求ケースラインに対して請求されたコスト額。

    データタイプ:通貨 (文字列)

    コンシューマー consumer オプション。コンシューマーまたは車両所有者。コンシューマー ID が利用できない場合は、電話番号またはメールが提供される場合があります。

    テーブル:コンシューマー [csm_consumer]

    データタイプ:参照 (文字列)

    相関 ID correlation_id オプション。この要求を上流または下流システムとリンクするために使用される外部相関識別子。

    データタイプ:文字列

    ディーラー requesting_service_organization 必須。要求を送信するサービス組織 (ディーラー) への参照。

    内部的には、番号で照合されたサービス組織 [sn_customer_service_organization] レコードに解決されます。

    データタイプ:参照 (文字列)

    控除額 deductible_amount オプション。修理請求に適用される控除額。

    データタイプ:通貨 (文字列)

    外部修復注文番号 external_ro_number 必須。外部ディーラーまたはサービスシステムからの修理注文番号。

    データタイプ:文字列

    障害コード fault_code オプション。報告された問題に関連する障害コードまたは診断コード。

    データタイプ:文字列

    インストールベース install_base オプション。サービス対象の製品または資産を識別し、指定された値を ServiceNow 内の既存のインストールベースアイテムと照合することで解決されます。

    テーブル:インストールベース [sn_install_base_item]

    有効な値:
    • 資産番号
    • serial number
    • 名前

    データタイプ:参照 (文字列)

    保証に含まれる部品 in_warranty 必須。影響を受ける部品が保証対象かどうかを示すフラグ。
    有効な値:
    • true:影響を受ける部品は保証対象です。
    • false:影響を受ける部品は保証対象外です。

    データタイプ:ブール

    保証期間内の車両 vehicle_in_warranty 必須。車両が保証期間内かどうかを示すフラグ。
    有効な値:
    • true:車両は保証期間内です。
    • false:車両は保証対象外です。

    データタイプ:ブール

    問題の説明 short_description 必須。問題の簡単な要約。

    データタイプ:文字列

    親タスク parent_task 必須。要求に関連付けられた既存の親修理請求ケースまたは親タスクの識別子。

    テーブル:タスク [task]

    データタイプ:参照 (文字列)

    事前認証ケース明細行 pre_auth_case_line オプション。対応する事前認証修理要求 (該当する場合)。

    テーブル:認証前の修理要求ジョブ [sn_pre_auth_repair_request_job]、フィールド:番号

    データタイプ:参照 (文字列)

    製品使用率 product_usage 必須。修理時の車両の使用状況の読み取り値 (たとえば、走行距離やマイル数)。

    データタイプ:数値 (10 進数)

    数量 数量 必須。影響を受ける部品または交換された部品の数。

    データタイプ:数値 (10 進数)

    修理アクション repair_action 必須。問題を解決するために実行されたアクション。
    有効な値:
    • 修理 [REPAIR]
    • 交換 [REPLACEMENT]
    • ソフトウェア更新 [SOFTWARE_UPDATE]

    データタイプ:選択肢 (文字列)

    修理請求ケース parent_case 必須。このケースラインに関連付けられた修理請求ケース。

    テーブル:顧客ケース [sn_customerservice_case]

    修理の詳細 details 必須。実行された問題、診断、および修復の詳細な説明。

    データタイプ:翻訳された HTML

    交換部品 replacement_part 条件付き。repair_action = 交換の場合、交換部品の名前またはモデル番号を指定します。

    テーブル:製品モデル [cmdb_model]/名前/モデル番号

    データタイプ:参照 (文字列)

    報告日 reported_date 必須。車両がディーラーまたはサービスセンターに到着した日時。

    形式:YYYY-MM-DDThh:mm:ss

    データタイプ:日時

    ソース ソース オプション。修理請求要求を送信した元のシステムまたはチャネル。

    データタイプ:文字列

    送信済み submitted_at 必須。請求が提出された日時。

    形式:YYYY-MM-DDThh:mm:ss

    データタイプ:日時

    合計請求額 total_claimed_amount 必須。修理請求ケース全体の合計請求額。

    データタイプ:通貨 (文字列)

    タイプ type 必須。送信される請求のタイプ。
    有効な値:
    • 保証 [warranty]
    • のれん [のれん]
    • サービス契約 [Servicecontract]

    データタイプ:選択肢 (文字列)

    測定単位 unit_of_measure 必須。製品使用量の測定単位。たとえば、km やマイルなどです。

    テーブル:測定単位 [sn_prd_pm_uom]

    データタイプ:参照 (文字列)

    作業メモ work_notes オプション。請求処理に関連する内部メモまたはコメント。

    データタイプ:文字列

    SOAP 要求の例

    注:
    例で使用されている名前空間は、標準の SOAP および STAR 規則に従います。
    <?xml version="1.0" encoding="UTF-8"?>
    <soap:Envelope
        xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:oagis="http://www.openapplications.org/oagis/9"
        xmlns:star="http://www.starstandard.org/STAR/5"
        xmlns:tran="http://www.starstandards.org/webservices/2009/transport"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    
        <soap:Header>
            <!-- Optional header -->
            <tran:payloadManifest>
                <tran:manifest
                    contentID="A0"
                    element="ProcessRepairOrder"
                    namespaceURI="http://www.starstandard.org/STAR/5"
                    version="5.13.4.0.0" />
            </tran:payloadManifest>
        </soap:Header>
    
        <soap:Body>
            <ProcessRepairOrder xmlns="http://www.service-now.com/ProcessRepairOrder">
                <payload>
                    <![CDATA[
    <star:ProcessRepairOrder
        xmlns:star="http://www.starstandard.org/STAR/5"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        releaseID="5.13.4.0.0"
        systemEnvironmentCode="Production">
    
        <!-- APPLICATION AREA -->
        <star:ApplicationArea>
            <star:Sender>
                <star:CreatorNameCode>DealerManagementSystem</star:CreatorNameCode>
                <star:SenderNameCode>DEALER001</star:SenderNameCode>
                <star:URI>https://dealer-system.example.com</star:URI>
                <star:DealerNumberID>98765</star:DealerNumberID>
                <star:StoreNumber>ST-001</star:StoreNumber>
                <star:AreaNumber>REGION-01</star:AreaNumber>
                <star:DealerCountryCode>US</star:DealerCountryCode>
                <star:LanguageCode>en-US</star:LanguageCode>
                <star:SystemVersion>DMS_v6.1.0</star:SystemVersion>
            </star:Sender>
    
            <star:CreationDateTime>2026-01-09T14:30:45</star:CreationDateTime>
            <star:BODID>a1b2c3d4-e5f6-7890-abcd-ef1234567890</star:BODID>
    
            <star:Destination>
                <star:DestinationNameCode>OEM_MANUFACTURER</star:DestinationNameCode>
            </star:Destination>
        </star:ApplicationArea>
    
        <!-- DATA AREA -->
        <star:ProcessRepairOrderDataArea>
            <star:Process>
                <star:ActionCode>ADD</star:ActionCode>
            </star:Process>
    
            <star:RepairOrder>
                <star:RepairOrderHeader>
                    <star:DocumentIdentificationGroup>
                        <star:DocumentIdentification>
                            <star:DocumentID>RO-2026-987654qwert</star:DocumentID>
                        </star:DocumentIdentification>
                    </star:DocumentIdentificationGroup>
    
    SOAP 応答の例 (成功)
    <?xml version="1.0" encoding="UTF-8"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
      <SOAP-ENV:Body>
        <ProcessRepairOrderResponse>
          <status>success</status>
          <message>Repair order processed successfully</message>
          <data>{"reference":"RPC0001005"}</data>
        </ProcessRepairOrderResponse>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>
    
    SOAP 応答の例 (検証エラー)
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
      <SOAP-ENV:Body>
        <ProcessRepairOrderResponse>
          <status>error</status>
          <message>
            VALIDATION ERRORS
            payload="[{\"field\":\"asset\",\"message\":\"Reference value not found\"}]"
          </message>
        </ProcessRepairOrderResponse>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>
    

    エラー処理

    API は、標準の SOAP および HTTP メカニズムを使用して、SOAP フォールト、カスタムビジネスエラー、HTTP ステータスコードなどのエラーを報告します。

    SOAP フォルトは、次のような場合に、要求をプロトコルレベルで解析または処理できない場合に返されます。
    • XML の形式が正しくありません
    • 名前空間が正しくありません
    • 必須の SOAP エンベロープ構造がありません
    • 認証失敗
    • システムレベルの処理エラー
    SOAP フォールトの例:
    <soap:Fault>
      <faultcode>soap:Client</faultcode>
      <faultstring>Invalid SOAP message</faultstring>
    </soap:Fault>
    

    カスタムビジネスエラー

    ビジネス検証エラーは、SOAP 解析が成功した後に発生し、次のような要求データの問題を示します。
    • 参照が欠落しているか無効です
    • 重複する修復オーダー
    • 無効なコード値
    • スキーマまたはバージョンの不一致
    これらは、SOAP 解析が成功した後、ビジネス検証中に発生します。エラーは、 エラー のステータスと説明的なメッセージとともに操作応答で返されます。考えられるエラー:
    • MANDATORY_FIELD_MISSING
    • MIN_VALUE MAX_VALUE INVALID_REFERENCE
    • UNSUPPORTED_VALIDATION_TYPE
    • SOAP_ENVELOPE_EMPTY
    • IN_WARRANTY_TRANSFORM_FAILED
    • VALIDATION_ERRORS
    • INVOKE_PROCESSOR_FAILED
    • INVALID_DATE_FORMAT
    • INVALID_DATE_VALUE
    • INVALID_DATETIME_FORMAT
    • XML_TO_JSON_FAILED
    • INVALID_DATETIME_VALUE
    • PAYLOAD_PARSING_FAILED
    • EMPTY_PARSED_PAYLOAD
    • INVALID_TRANSLATED_HTML_TYPE
    • MAX_LENGTH_EXCEEDED
    • MAIN_PART_MISSING
    • MULTIPLE_MAIN_PARTS
    エラーコードの例:
    <ProcessRepairOrderResponse> 
    <status>error</status> 
    <message>VALIDATION ERRORS | payload="[{\"field\":\"asset\",\"message\":\"Reference value not found\"}]"</message> 
    </ProcessRepairOrderResponse> 
    </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

    HTTP ステータスコード

    HTTP コード 説明
    200 OK:要求が正常に処理されました。
    400 要求が正しくありません:要求が無効であるか、形式が正しくありません。
    401 権限なし:認証に失敗しました。
    403 禁止:アクセスが許可されていません。
    500 内部サーバーエラー:予期しない処理エラー。

    送信 STAR 統合

    このアウトバウンド統合は、STAR 準拠の XML メッセージを使用して、OEM Now ServiceNow インスタンスからディーラー管理システム (DMS) に請求裁定と支払い結果を送信します。

    統合は、次の場合に修理請求ケーステーブル (sn_repair_claim_mgmt_case) の ServiceNow ビジネスルールによってトリガーされます。
    • 要求ソースは DMS です
    • 請求ステータスは次のいずれかです。
      • 承認済み
      • 部分的に承認されました
      • 却下
      • 情報を待機中
    表 : 2. 送信パラメーター
    名前 ラベル 説明
    承認済み金額 approved_amount 必須。裁定後のこの特定の修理請求ケースラインの承認金額。

    データタイプ:通貨

    相関 ID correlation_id 必須。送信応答を元の受信修理請求要求と関連付けるために使用される一意の識別子。

    データタイプ:文字列

    外部修復注文番号 external_ro_number 必須。ディーラーシステムによって提供された、修理請求ケースに関連付けられた外部修理注文番号。

    データタイプ:文字列

    ディーラー ID dealer_number 必須。修理請求を送信したディーラーまたはサービス組織の一意の識別子。

    データタイプ:文字列

    レビューアクション review_action 必須。請求レビュー中に請求エージェントが実行するアクション。
    可能な値:
    • すべて [approve_all] を承認
    • すべて却下 [reject_all]
    • 部分的に承認されました [partially_approved]
    • 返送 [send_back]

    データタイプ:選択肢 (文字列)

    レビューコメント review_comments オプション。レビューおよび裁定プロセス中に請求エージェントによって入力されたコメント。

    データタイプ:翻訳されたテキスト

    サービス組織 service_organization 必須。修理請求に関連付けられたディーラーまたはサービス組織の名前。

    データタイプ:文字列

    状況 state 必須。応答時の修理請求ケースの全体的な裁定ステータス。
    可能な値:
    • 0:ドラフト
    • 1:新規
    • 2:オープン
    • 5:レビュー待ち
    • 6:情報待ち
    • 8:承認済み
    • 9 - 部分的に承認済み
    • 10 - 却下
    • 3:完了してクローズ
    • 7:未完了でクローズ
    • 4:キャンセルしてクローズ

    データタイプ:選択肢 (文字列)

    承認済み合計金額 total_approved_amount 必須。すべてのケースラインにわたって集計された、修理請求ケース全体の承認済み合計金額。

    データタイプ:通貨

    表 : 3. 要求ステータスマッピング
    ステータス STAR ステータスコード 意思決定インジケーター
    AWAITING_INFO 6 R (却下)
    承認済み 8 A (承認済み)
    PARTIALLY_APROVED 9 A (承認済み)
    却下 10 D (拒否)
    これらの条件が満たされると、 ServiceNow は STAR ProcessServiceProcessingAdvisory メッセージを生成して DMS に送信します。送信 STAR メッセージは、請求提出データではなく、請求裁定結果を伝えます。メッセージには次のものが含まれます。
    • 修理注文または請求参照
    • 全体的な請求ステータス
    • 支払可能または承認済みの合計金額
    • 個々のジョブまたは運用レベルでの承認済み金額

    このメッセージは STAR ProcessServiceProcessingAdvisory 構造に準拠しており、DMS が請求ステータスと財務調整データを同期できるようにします。

    送信サンプルペイロード:
    <ns:ProcessServiceProcessingAdvisory
        xmlns:ns="http://www.starstandard.org/STAR/5"
        xmlns:ns1="http://www.openapplications.org/oagis/9"
        languageCode="en-US"
        releaseID="1.0"
        systemEnvironmentCode="Production"
        versionID="1.0">
        <ns:ApplicationArea>
            <ns:Sender>
                <ns:CreatorNameCode>Beta Consulting Group Orlando</ns:CreatorNameCode>
                <ns:SenderNameCode>DLR0001001</ns:SenderNameCode>
            </ns:Sender>
            <ns:CreationDateTime>2026-02-26T11:54:25</ns:CreationDateTime>
            <ns:Destination />
        </ns:ApplicationArea>
        <ns:ProcessServiceProcessingAdvisoryDataArea>
            <ns:Process />
            <ns:ServiceProcessingAdvisory>
                <ns:ServiceProcessingAdvisoryHeader>
                    <ns:DocumentIdentificationGroup>
                        <ns:DocumentIdentification>
                            <ns:DocumentID>RO-2026-987654qwe1111</ns:DocumentID>
                        </ns:DocumentIdentification>
                    </ns:DocumentIdentificationGroup>
                    <ns:Payments>
                        <ns:RepairOrderReconciliation>
                            <ns:WarrantyClaimReconciliation>
                                <ns:ToBePaidAmount currencyID="INR">342744.29</ns:ToBePaidAmount>
                                <ns:ClaimStatusCode>Pending review</ns:ClaimStatusCode>
                                <ns:WarrantyNotes />
                                <ns:DispositionReason>
                                    <ns:DispositionReasonCode />
                                </ns:DispositionReason>
                            </ns:WarrantyClaimReconciliation>
                            <ns:JobReconciliation>
                                <ns:ApprovedAmount currencyID="INR">342744.29</ns:ApprovedAmount>
                                <ns:ClaimStatusCode>Pending review</ns:ClaimStatusCode>
                                <ns:OperationID>DIAG-ENG-01A1A1</ns:OperationID>
                            </ns:JobReconciliation>
                            <ns:JobReconciliation>
                                <ns:ApprovedAmount currencyID="INR">0.00</ns:ApprovedAmount>
                                <ns:ClaimStatusCode>Pending review</ns:ClaimStatusCode>
                                <ns:OperationID>DIAG-ENG-011</ns:OperationID>
                            </ns:JobReconciliation>
                        </ns:RepairOrderReconciliation>
                    </ns:Payments>
                </ns:ServiceProcessingAdvisoryHeader>
            </ns:ServiceProcessingAdvisory>
        </ns:ProcessServiceProcessingAdvisoryDataArea>
    </ns:ProcessServiceProcessingAdvisory>

    ログ記録と診断

    要求と応答は、標準 ServiceNow 運用プラクティスに従って診断とトラブルシューティングの目的でサービスによってログに記録されます。

    関連仕様

    • STAR XML 仕様
    • SOAP 1.1 仕様
    • WSDL 1.1 仕様

    詳細なスキーマとプロトコルの定義については、公式の STAR および W3C ドキュメントを参照してください。