保証請求 SOAP API
保証請求SOAP APIは、ディーラ・システムからの受信修理オーダーを処理し、Oracle Enterprise Manager (OEM)のプラットフォーム内で保証請求に変換します。
この API は SOAP 1.1 規則 に従い、自動車サービスシステム間の相互運用性のために Standards for Technology in Automotive Retail (STAR) XML スキーマ を使用します。
- 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) が既に存在するかどうかを判定します。
- 一致するものが見つからない場合は、新しいレコードを作成します。
- 一致が見つかった場合は、既存のレコードを更新します。
- 処理ステータスと参照識別子を返します。
要求の構造
ProcessRepairOrder メッセージが含まれています。主要な論理要素は次のとおりです。- アプリケーションメタデータ (送信者、作成時刻、宛先)。
- 要求されたアクションを示すプロセス動作。
- 修復オーダーヘッダー情報。
- 車両の詳細。
- ジョブ、労務、部品、および価格設定の詳細。
- 保証請求情報。
すべての要素は、ペイロードに示されている STAR XML スキーマバージョンに準拠している必要があります。
要求パラメーター
| 名前 | ラベル | 説明 |
|---|---|---|
| アクティビティステータス | activity_status | 必須。修理請求ケースラインの現在のライフサイクルステータスを示し、プレイブックの実行を推進します。 テーブル:修理請求ケースライン [sn_repair_claim_mgmt_case_line] 有効な値:
データタイプ:選択肢 (文字列) |
| 作業終了日時 | 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] 有効な値:
データタイプ:参照 (文字列) |
| 保証に含まれる部品 | in_warranty | 必須。影響を受ける部品が保証対象かどうかを示すフラグ。 有効な値:
データタイプ:ブール |
| 保証期間内の車両 | vehicle_in_warranty | 必須。車両が保証期間内かどうかを示すフラグ。 有効な値:
データタイプ:ブール |
| 問題の説明 | short_description | 必須。問題の簡単な要約。 データタイプ:文字列 |
| 親タスク | parent_task | 必須。要求に関連付けられた既存の親修理請求ケースまたは親タスクの識別子。 テーブル:タスク [task] データタイプ:参照 (文字列) |
| 事前認証ケース明細行 | pre_auth_case_line | オプション。対応する事前認証修理要求 (該当する場合)。 テーブル:認証前の修理要求ジョブ [sn_pre_auth_repair_request_job]、フィールド:番号 データタイプ:参照 (文字列) |
| 製品使用率 | product_usage | 必須。修理時の車両の使用状況の読み取り値 (たとえば、走行距離やマイル数)。 データタイプ:数値 (10 進数) |
| 数量 | 数量 | 必須。影響を受ける部品または交換された部品の数。 データタイプ:数値 (10 進数) |
| 修理アクション | repair_action | 必須。問題を解決するために実行されたアクション。 有効な値:
データタイプ:選択肢 (文字列) |
| 修理請求ケース | 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 | 必須。送信される請求のタイプ。 有効な値:
データタイプ:選択肢 (文字列) |
| 測定単位 | unit_of_measure | 必須。製品使用量の測定単位。たとえば、km やマイルなどです。 テーブル:測定単位 [sn_prd_pm_uom] データタイプ:参照 (文字列) |
| 作業メモ | work_notes | オプション。請求処理に関連する内部メモまたはコメント。 データタイプ:文字列 |
SOAP 要求の例
<?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>
<?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-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 ステータスコードなどのエラーを報告します。
- XML の形式が正しくありません
- 名前空間が正しくありません
- 必須の SOAP エンベロープ構造がありません
- 認証失敗
- システムレベルの処理エラー
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>Invalid SOAP message</faultstring>
</soap:Fault>
カスタムビジネスエラー
- 参照が欠落しているか無効です
- 重複する修復オーダー
- 無効なコード値
- スキーマまたはバージョンの不一致
エラー のステータスと説明的なメッセージとともに操作応答で返されます。考えられるエラー:- 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) に請求裁定と支払い結果を送信します。
- 要求ソースは DMS です
- 請求ステータスは次のいずれかです。
- 承認済み
- 部分的に承認されました
- 却下
- 情報を待機中
| 名前 | ラベル | 説明 |
|---|---|---|
| 承認済み金額 | approved_amount | 必須。裁定後のこの特定の修理請求ケースラインの承認金額。 データタイプ:通貨 |
| 相関 ID | correlation_id | 必須。送信応答を元の受信修理請求要求と関連付けるために使用される一意の識別子。 データタイプ:文字列 |
| 外部修復注文番号 | external_ro_number | 必須。ディーラーシステムによって提供された、修理請求ケースに関連付けられた外部修理注文番号。 データタイプ:文字列 |
| ディーラー ID | dealer_number | 必須。修理請求を送信したディーラーまたはサービス組織の一意の識別子。 データタイプ:文字列 |
| レビューアクション | review_action | 必須。請求レビュー中に請求エージェントが実行するアクション。 可能な値:
データタイプ:選択肢 (文字列) |
| レビューコメント | review_comments | オプション。レビューおよび裁定プロセス中に請求エージェントによって入力されたコメント。 データタイプ:翻訳されたテキスト |
| サービス組織 | service_organization | 必須。修理請求に関連付けられたディーラーまたはサービス組織の名前。 データタイプ:文字列 |
| 状況 | state | 必須。応答時の修理請求ケースの全体的な裁定ステータス。 可能な値:
データタイプ:選択肢 (文字列) |
| 承認済み合計金額 | total_approved_amount | 必須。すべてのケースラインにわたって集計された、修理請求ケース全体の承認済み合計金額。 データタイプ:通貨 |
| ステータス | STAR ステータスコード | 意思決定インジケーター |
|---|---|---|
| AWAITING_INFO | 6 | R (却下) |
| 承認済み | 8 | A (承認済み) |
| PARTIALLY_APROVED | 9 | A (承認済み) |
| 却下 | 10 | D (拒否) |
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 ドキュメントを参照してください。