주소 유효성 검사

아티클
04/11/2024

적용 대상: 파트너 센터 | 21Vianet에서 운영되는 파트너 센터 | Microsoft Cloud for US Government 파트너 센터

이 문서에서는 주소 유효성 검사 API를 사용하여 주소의 유효성을 검사하는 방법을 설명합니다.

주소 유효성 검사 API는 고객 프로필 업데이트의 유효성 검사에만 사용해야 합니다. API 응답 상태 따라 호출자는 고객에게 가장 적합한 주소를 선택해야 합니다.

필수 조건

자격 증명(파트너 센터 인증에서 설명). 이 시나리오는 독립 실행형 앱과 App+사용자 자격 증명을 모두 사용하여 인증을 지원합니다.

C#

주소의 유효성을 검사하려면 먼저 새 Address 개체를 인스턴스화하고 유효성을 검사할 주소로 채웁니다. 그런 다음 IAggregatePartner.Validations 속성에서 유효성 검사 작업에 대한 인터페이스를 검색하고 주소 개체를 사용하여 IsAddressValid 메서드를 호출합니다.

IAggregatePartner partnerOperations;

// Create an address to validate.
Address address = new Address()
{
    AddressLine1 = "One Microsoft Way",
    City = "Redmond",
    State = "WA",
    PostalCode = "98052",
    Country = "US"
};

// Validate the address.
AddressValidationResponse result = partnerOperations.Validations.IsAddressValid(address);

// If the request completes successfully, you can inspect the response object.

// See the status of the validation.
Console.WriteLine($"Status: {addressValidationResult.Status}");

// See the validation message returned.
Console.WriteLine($"Validation Message Returned: {addressValidationResult.ValidationMessage ?? "No message returned."}");

// See the original address submitted for validation.
Console.WriteLine($"Original Address:\n{this.DisplayAddress(addressValidationResult.OriginalAddress)}");

// See the suggested addresses returned by the API, if any exist.
Console.WriteLine($"Suggested Addresses Returned: {addressValidationResult.SuggestedAddresses?.Count ?? "None."}");

if (addressValidationResult.SuggestedAddresses != null && addressValidationResult.SuggestedAddresses.Any())
{
    addressValidationResult.SuggestedAddresses.ForEach(a => Console.WriteLine(this.DisplayAddress(a)));
}

// Helper method to pretty-print an Address object.
private string DisplayAddress(Address address)
{
    StringBuilder sb = new StringBuilder();

    foreach (var property in address.GetType().GetProperties())
    {
        sb.AppendLine($"{property.Name}: {property.GetValue(address) ?? "None to Display."}");
    }

    return sb.ToString();
}

REST 요청

요청 구문

메서드	요청 URI
POST	{baseURL}/v1/validations/address HTTP/1.1

요청 헤더

자세한 내용은 파트너 센터 REST 헤더를 참조하세요.

요청 본문

이 표에서는 요청 본문의 필수 속성을 설명합니다.

이름	Type	필수*	설명
addressline1	string	Y	주소의 첫 번째 줄입니다.
addressline2	string	N	주소의 두 번째 줄입니다. 이 속성은 선택 사항입니다.
city	string	Y	도시입니다.
state	string	Y	주.
postalcode	string	Y	우편번호입니다.
country	string	Y	두 문자 ISO alpha-2 국가 코드입니다.

* 필수 속성은 국가 또는 지역에 따라 변경 될 수 있습니다.

응답 정보

응답은 다음 상태 메시지 중 하나를 반환합니다. 상태 응답이 확인되거나 VerifiedShippable이 아닌 경우 입력한 주소 및/또는 제안된 주소를 검토합니다. 고객에게 가장 적합한 주소를 선택하는 것은 호출자에게 달려 있습니다.

Status	설명	반환되는 추천 주소 수	상태 응답 권장 사항
배송 가능 확인됨	주소가 확인되어 제품을 배송할 수 있습니다.	Single	확인된 주소를 계속 진행합니다.
확인됨	주소가 확인되었습니다.	Single	확인된 주소를 계속 진행합니다.
상호 작용 필요	제안된 주소가 크게 변경되었으며 사용자 확인이 필요합니다.	Single	사용자 확인 주소를 계속 진행합니다.
거리명 부분	주소에 입력된 거리명이 완전하지 않아 추가 정보가 필요합니다.	여러 개(최대 3개)	사용자 확인 주소를 계속 진행합니다.
부지 부분	입력된 부지(건물 번호, 다세대 동호수 등)가 완전하지 않아 추가 정보가 필요합니다.	여러 개(최대 3개)	사용자 확인 주소를 계속 진행합니다.
여러	주소에서 완전하지 않은 필드가 여러 개 있습니다(거리명 부분과 부지 부분 포함).	여러 개(최대 3개)	사용자 확인 주소를 계속 진행합니다.
None	주소가 올바르지 않습니다.	None	사용자 확인 주소를 계속 진행합니다.
확인 안 함	유효성 검사 프로세스를 통해 주소를 보낼 수 없습니다.	None	사용자 확인 주소를 계속 진행합니다.

요청 예제

# "VerifiedShippable" Request Example

POST https://api.partnercenter.microsoft.com/v1/validations/address HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>
MS-CorrelationId: 29624f3c-90cb-4d34-a7e9-bd2de6d35218
MS-RequestId: eb55c2b8-6f4b-4b44-9557-f76df624b8c0
Host: api.partnercenter.microsoft.com
Content-Length: 137
X-Locale: en-US

{
    "AddressLine1": "1 Microsoft Way",
    "City": "Redmond",
    "State": "WA",
    "PostalCode": "98052",
    "Country": "US"
}

# "StreetPartial" Request Example

POST https://api.partnercenter.microsoft.com/v1/validations/address HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>
MS-CorrelationId: 2c95c9bc-fdfb-4c6a-84f4-57c9b0826b43
MS-RequestId: ee6cf74c-3ab5-48d6-9269-4a4b75bd59dc
Host: api.partnercenter.microsoft.com
Content-Length: 135
X-Locale: en-US

{
    "AddressLine1": "Microsoft Way",
    "City": "Redmond",
    "State": "WA",
    "PostalCode": "98052",
    "Country": "US"
}

REST 응답

성공하면 메서드는 응답 본문에 HTTP 200 상태 코드를 사용하여 AddressValidationResponse 개체를 반환합니다. 예를 들면 다음과 같습니다.

응답 성공 및 오류 코드

각 응답에는 성공 또는 실패 및 디버깅 정보를 나타내는 HTTP 상태 코드가 함께 제공됩니다. 네트워크 추적 도구를 사용하여 이 코드, 오류 유형 및 기타 매개 변수를 읽습니다. 전체 목록은 파트너 센터 REST 오류 코드를 참조하세요.

응답 예제

# "VerifiedShippable" Response Example

HTTP/1.1 200 OK
Date: Mon, 17 May 2021 23:19:19 GMT
Content-Type: application/json; charset=utf-8
MS-CorrelationId: 29624f3c-90cb-4d34-a7e9-bd2de6d35218
MS-RequestId: eb55c2b8-6f4b-4b44-9557-f76df624b8c0
X-Locale: en-US
 
{
    "originalAddress": {
        "country": "US",
        "city": "Redmond",
        "state": "WA",
        "addressLine1": "1 Microsoft Way",
        "postalCode": "98052"
    },
    "suggestedAddresses": [
        {
            "country": "US",
            "city": "Redmond",
            "state": "WA",
            "addressLine1": "1 Microsoft Way",
            "postalCode": "98052-8300"
        }
    ],
    "status": "VerifiedShippable"
}

# "StreetPartial" Response Example

HTTP/1.1 200 OK
Date: Mon, 17 May 2021 23:34:08 GMT
Content-Type: application/json; charset=utf-8
MS-CorrelationId: 2c95c9bc-fdfb-4c6a-84f4-57c9b0826b43
MS-RequestId: ee6cf74c-3ab5-48d6-9269-4a4b75bd59dc
X-Locale: en-US
 
{
    "originalAddress": {
        "country": "US",
        "city": "Redmond",
        "state": "WA",
        "addressLine1": "Microsoft Way",
        "postalCode": "98052"
    },
    "suggestedAddresses": [
        {
            "country": "US",
            "city": "Redmond",
            "state": "WA",
            "addressLine1": "1 Microsoft Way",
            "postalCode": "98052-6399"
        }
    ],
    "status": "StreetPartial",
    "validationMessage": "Address field invalid for property: 'Region', 'PostalCode', 'City'"
}