보증 클레임 SOAP API
보증 클레임 SOAP API는 딜러 시스템에서 들어오는 수리 주문을 처리하여 Oracle Enterprise Manager(OEM) 플랫폼 내에서 보증 클레임으로 변환합니다.
이 API는 SOAP 1.1 규칙을 따르며 자동차 서비스 시스템 간의 상호 운용성을 위해 STAR(Standards for Technology in Automotive Retail) XML 스키마를 사용합니다.
- MCO에서 ServiceNow 직접 DMS의 보증 클레임을 생성하고 확인합니다.
- 판결 및 승인 결과를 포함하여 제출된 클레임의 상태를 쿼리하고 해당 결과를 다시 검색합니다 ServiceNow.
- 다음 세 가지 핵심 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 |
| 메시지 형식 | 텍스트/XML |
| 프로토콜 | TLS 1.2+를 통한 HTTPS; STAR 파트너에 대한 상호 TLS 옵션 |
액세스 및 인증
- 기본 인증(사용자 이름/암호)
- Configurable 모든 DMS의 엔드포인트당
세분화된 역할 및 엔터티
이 SOAP API에는 특정 MCO 기능 및 책임에 액세스하고, 사용자 지정 ACL 없이 CRU 권한을 제공하고, 지원되는 엔터티에 직접 매핑하기 위한 세분화된 역할이 필요합니다. 지원되는 세분화된 역할에 대한 자세한 내용은 을 참조하십시오 세분화된 역할 및 엔터티 .
엔드포인트 상세 정보
보증 청구 SOAP API는 MCO에서 ServiceNow 스크립트된 SOAP 웹 서비스로 노출됩니다.
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 파트 | 설명 |
|---|---|
<instance_name> |
ServiceNow 인스턴스 호스팅 MCO(OEM별, OEM당 고정). |
sn_mco_integ_ |
MCO 통합 네임스페이스입니다. |
RepairClaimSOAPHandler.do |
스크립팅된 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(문자열) |
| 자산 | 자산 | 필수 클레임의 일련 번호 또는 자산 태그입니다. 테이블: 자산 [alm_asset] 데이터 유형: 참조(문자열) |
| 원인 제공 부품 | product_model | 필수 문제의 근본 원인으로 식별된 부품의 모델 번호입니다. 테이블: 제품 모델 [cmdb_model] 데이터 유형: 참조(문자열) |
| 수령된 금액 | claimed_amount | 옵션입니다. 이 특정 수리 클레임 케이스 라인에 대해 수령된 비용 금액입니다. 데이터 유형: 통화(문자열) |
| 소비자 | 소비자 | 옵션입니다. 소비자 또는 차량 소유자. 소비자 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 | 필수 수리 시 차량의 사용량 판독값(예:ample, 주행한 킬로미터 또는 마일). 데이터 유형: 숫자(10진수) |
| 수량 | 수량 | 필수 영향을 받거나 교체한 부품의 수입니다. 데이터 유형: 숫자(10진수) |
| 수리 작업 | repair_action | 필수 문제를 해결하기 위해 수행된 작업입니다. 유효한 값은 다음과 같습니다.
데이터 유형: 선택(문자열) |
| 수리 클레임 케이스 | parent_case | 필수 이 케이스 라인과 연결된 수리 클레임 케이스입니다. 테이블: 고객 케이스 [sn_customerservice_case] |
| 수리 상세 정보 | 세부사항 | 필수 수행된 문제, 진단 및 복구에 대한 자세한 설명입니다. 데이터 유형: 번역된 HTML |
| 교체 부품 | replacement_part | 조건부. = 교체인 경우 repair_action , 교체된 부품의 이름 또는 모델 번호를 지정합니다.테이블: 제품 모델 [cmdb_model]/이름/모델 번호 데이터 유형: 참조(문자열) |
| 보고 날짜 | reported_date | 필수 차량이 딜러 또는 서비스 센터에 도착한 날짜 및 시간입니다. 형식: YYYY-MM-DDThh:mm:ss 데이터 유형: DateTime |
| 소스 | 소스 | 옵션입니다. 수리 클레임 요청을 제출한 원래 시스템 또는 채널입니다. 데이터 유형: 문자열 |
| 제출됨 | submitted_at | 필수 클레임이 제출된 날짜 및 시간입니다. 형식: YYYY-MM-DDThh:mm:ss 데이터 유형: DateTime |
| 수령된 총 금액 | total_claimed_amount | 필수 전체 수리 클레임 케이스에 대해 수령된 총 금액입니다. 데이터 유형: 통화(문자열) |
| 유형 | 유형 | 필수 제출 중인 클레임의 유형입니다. 유효한 값은 다음과 같습니다.
데이터 유형: 선택(문자열) |
| 측정 단위 | 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 | 확인 - 요청이 성공적으로 처리되었습니다. |
| 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 | 필수 수리 클레임과 연결된 딜러 또는 서비스 조직의 이름입니다. 데이터 유형: 문자열 |
| 상태 | 상태 | 필수 응답 당시 수리 클레임 케이스의 전반적인 판결 상태입니다. 가능한 값:
데이터 유형: 선택(문자열) |
| 승인된 총 금액 | 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 설명서를 참조하십시오.