Convalidare un indirizzo

Articolo
03/08/2025

si applica a: Centro per i partner | Centro per i partner gestito da 21Vianet | Centro per i partner per Microsoft Cloud per il governo degli Stati Uniti

Questo articolo illustra come convalidare un indirizzo usando l'API di convalida degli indirizzi.

L'API di convalida degli indirizzi deve essere usata solo per la prevalida degli aggiornamenti del profilo cliente. In base allo stato della risposta dell'API, il chiamante deve scegliere l'indirizzo più appropriato per il cliente.

Prerequisiti

Credenziali come descritto in autenticazione del Partner Center. Questo scenario supporta l'autenticazione con credenziali autonome per l'app e con le credenziali dell'App+Utente.

C#

Per convalidare un indirizzo, creare prima un'istanza di un nuovo oggetto Address e popolarlo con l'indirizzo da convalidare. Recuperare quindi un'interfaccia per le operazioni di convalida dalla proprietà IAggregatePartner.Validations e chiamare il metodo IsAddressValid con l'oggetto address.

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

Richiesta REST

Sintassi della richiesta

Metodo	URI della richiesta
POST	{baseURL}/v1/validations/address HTTP/1.1

Intestazioni della richiesta

Per ulteriori informazioni, vedere intestazioni REST del Partner Center.

Corpo della richiesta

Questa tabella descrive le proprietà necessarie nel corpo della richiesta.

Nome	Digitare	Obbligatorio*	Descrizione
addressline1	corda	Y	Prima riga dell'indirizzo.
addressline2	corda	N	Seconda riga dell'indirizzo. Questa proprietà è facoltativa.
città	corda	Y	La città.
stato	corda	Y	Stato.
codice postale	corda	Y	Codice postale.
paese	corda	Y	Codice paese ISO alfa-2 a due caratteri.

* Le proprietà obbligatorie possono cambiare in base al paese o all'area geografica.

Dettagli della risposta

La risposta restituisce uno dei messaggi di stato seguenti. Se la risposta di stato non è verificato o verificato spedibile, esaminare l'indirizzo immesso e/o l'indirizzo suggerito. Spetta al chiamante scegliere l'indirizzo più appropriato per il cliente.

Stato	Descrizione	Numero di indirizzi suggeriti restituiti	Raccomandazione sulla risposta allo stato
Verificato per la spedizione	L'indirizzo viene verificato ed è idoneo per la spedizione.	Singolo	Procedere con l'indirizzo verificato.
Verificato	L'indirizzo viene verificato.	Singolo	Procedere con l'indirizzo verificato.
Interazione necessaria	L'indirizzo suggerito viene modificato in modo significativo e richiede la conferma dell'utente.	Singolo	Procedere con l'indirizzo confermato dall'utente.
Parziale chiusura della strada	La strada specificata nell'indirizzo è parziale e necessita di maggiori informazioni.	Multiplo: massimo tre	Procedere con l'indirizzo confermato dall'utente.
Premesse parziali	I locali specificati (numero di edificio, numero di suite e altri) sono parziali e necessitano di altre informazioni.	Multiplo: massimo tre	Procedere con l'indirizzo confermato dall'utente.
Multiplo	Ci sono più campi parziali nell'indirizzo (inclusi potenzialmente anche campi parziali della via e dei locali).	Multiplo: massimo tre	Procedere con l'indirizzo confermato dall'utente.
Nessuno	L'indirizzo non è corretto.	Nessuno	Procedere con l'indirizzo confermato dall'utente.
Non convalidato	L'indirizzo non è stato in grado di essere inviato tramite il processo di convalida.	Nessuno	Procedere con l'indirizzo confermato dall'utente.

Esempio di richiesta

# "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"
}

Risposta REST

Se ha esito positivo, il metodo restituisce un oggetto AddressValidationResponse nel corpo della risposta, con un codice di stato HTTP 200. Di seguito è riportato un esempio.

Codici di errore e esito positivo della risposta

Ogni risposta viene fornita con un codice di stato HTTP che indica l'esito positivo o negativo e le informazioni di debug. Usare uno strumento di traccia di rete per leggere questo codice, il tipo di errore e altri parametri. Per l'elenco completo, vedere codici di errore REST del Centro per i partner.

Esempio di risposta

# "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'"
}

Condividi tramite