Weryfikowanie adresu

Artykuł
03/09/2025

Dotyczy: Centrum partnerskie | Centrum partnerskie obsługiwane przez firmę 21Vianet | Centrum partnerskie dla chmury firmy Microsoft dla instytucji rządowych USA

W tym artykule wyjaśniono, jak zweryfikować adres przy użyciu interfejsu API weryfikacji adresów.

Interfejs API sprawdzania poprawności adresów powinien być używany tylko do prewalidacji aktualizacji profilu klienta. Na podstawie stanu odpowiedzi interfejsu API obiekt wywołujący powinien wybrać najbardziej odpowiedni adres dla klienta.

Warunki wstępne

Poświadczenia, jak opisano w uwierzytelnianiu Centrum partnerskiego. Ten scenariusz obsługuje uwierzytelnianie zarówno przy użyciu autonomicznych poświadczeń aplikacji, jak i aplikacji i użytkownika.

C#

Aby zweryfikować adres, najpierw utwórz wystąpienie nowego obiektu Address i wypełnij go adresem w celu zweryfikowania. Następnie pobierz interfejs w celu operacje weryfikacji z właściwości IAggregatePartner.Validations i wywołaj metodę IsAddressValid z obiektem adresu.

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();
}

Żądanie REST

Składnia żądania

Metoda	Identyfikator URI żądania
POST	{baseURL}/v1/validations/address HTTP/1.1

Nagłówki żądań

Aby uzyskać więcej informacji, zobacz Nagłówki REST Centrum partnerskiego.

Treść żądania

W tej tabeli opisano wymagane właściwości w treści żądania.

Nazwa	Typ	Wymagane*	Opis
Adres linia 1	struna	Y	Pierwszy wiersz adresu.
dodatkowa_linia_adresu	struna	N	Drugi wiersz adresu. Ta właściwość jest opcjonalna.
miasto	struna	Y	Miasto.
stan	struna	Y	Stan.
kod pocztowy	struna	Y	Kod pocztowy.
kraj	struna	Y	Dwuznaczny kod kraju ISO alfa-2.

* Wymagane właściwości mogą ulec zmianie w zależności od kraju lub regionu.

Szczegóły odpowiedzi

Odpowiedź zwraca jeden z następujących komunikatów o stanie. Jeśli odpowiedź na stan nie jest Zweryfikowany lub Gotowy do wysyłki, przejrzyj wprowadzony lub sugerowany adres. To osoba dzwoniąca wybiera najbardziej odpowiedni adres dla klienta.

Stan	Opis	Liczba zwróconych sugerowanych adresów	Zalecenie dotyczące reakcji na status
Zweryfikowano możliwość wysyłki	Adres jest zweryfikowany i można na niego wysyłać przesyłki.	Singiel	Postępuj ze zweryfikowanym adresem.
Zweryfikowano	Adres jest weryfikowany.	Singiel	Kontynuuj z użyciem zweryfikowanego adresu.
Wymagana interakcja	Sugerowany adres jest znacznie zmieniony i wymaga potwierdzenia użytkownika.	Pojedynczy	Przejdź do adresu potwierdzonego przez użytkownika.
Fragment ulicy	Dana ulica w adresie jest częściowa i potrzebuje więcej informacji.	Wielokrotność — maksymalnie trzy	Przejdź do adresu potwierdzonego przez użytkownika.
Pomieszczenia częściowe	Podane lokale (numer budynku, numer apartamentu i inne) są częściowe i wymagają dodatkowych informacji.	Wiele — maksymalnie trzy	Przejdź do adresu potwierdzonego przez użytkownika.
Wielokrotny	Istnieje wiele pól, które są niekompletne w adresie (potencjalnie w tym także niepełne dane dotyczące ulicy i niepełne dane dotyczące lokalu).	Wielokrotność — maksymalnie trzy	Przejdź do adresu potwierdzonego przez użytkownika.
Żaden	Adres jest niepoprawny.	Żaden	Kontynuuj wprowadzenie potwierdzonego adresu użytkownika.
Nie zweryfikowano	Nie można wysłać adresu za pośrednictwem procesu weryfikacji.	Żaden	Przejdź do adresu potwierdzonego przez użytkownika.

Przykład żądania

# "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: aaaa0000-bb11-2222-33cc-444444dddddd
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: bbbb1111-cc22-3333-44dd-555555eeeeee
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"
}

Odpowiedź REST

W przypadku powodzenia metoda zwraca obiekt AddressValidationResponse w treści odpowiedzi z kodem stanu HTTP 200 . Poniżej przedstawiono przykład.

Kody sukcesu i błędów odpowiedzi

Każda odpowiedź zawiera kod stanu HTTP, który wskazuje powodzenie lub niepowodzenie i informacje o debugowaniu. Użyj narzędzia do śledzenia sieci, aby odczytać ten kod, typ błędu i inne parametry. Aby uzyskać pełną listę, zobacz Kody błędów REST Centrum partnerskiego.

Przykład odpowiedzi

# "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: aaaa0000-bb11-2222-33cc-444444dddddd
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: bbbb1111-cc22-3333-44dd-555555eeeeee
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'"
}

Udostępnij za pośrednictwem