Valider une adresse

Article
07/11/2024

S’applique à : Espace partenaires | Espace partenaires géré par 21Vianet | Espace partenaires de Microsoft Cloud for US Government

Cet article explique comment valider une adresse à l’aide de l’API de validation d’adresse.

L’API de validation d’adresse ne doit être utilisée que pour la prévalidation des mises à jour de profil client. En fonction de l’état de réponse de l’API, l’appelant doit choisir l’adresse la plus appropriée pour le client.

Prérequis

Informations d’identification, comme décrit dans Authentification auprès de l’Espace partenaires. Ce scénario prend en charge l’authentification avec les informations d’identification d’application et d’application+utilisateur autonomes.

C#

Pour valider une adresse, instanciez d’abord un nouvel objet Address et remplissez-le avec l’adresse à valider. Ensuite, récupérez une interface vers les opérations Validations à partir de la propriété IAggregatePartner.Validations , puis appelez la méthode IsAddressValid avec l’objet d’adresse.

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

Demande REST

Syntaxe de la requête

Méthode	URI de demande
POST	{baseURL}/v1/validations/address HTTP/1.1

En-têtes de requête

Pour plus d’informations, consultez En-têtes REST de l’Espace Partenaires.

Corps de la demande

Ce tableau décrit les propriétés requises dans le corps de la requête.

Nom	Type	Obligatoire*	Description
addressline1	string	Y	Première ligne de l’adresse.
addressline2	string	N	Deuxième ligne de l’adresse. Cette propriété est facultative.
city	chaîne	Y	La ville.
état	chaîne	Y	État.
postalcode	string	Y	Le code postal.
country	string	Y	Le code pays alpha-2 ISO à deux caractères.

* Les propriétés requises peuvent changer en fonction du pays ou de la région.

Détails de la réponse

La réponse retourne l’un des messages d’état suivants. Si la réponse d’état n’est pas Vérifié ou VérifiéShippable, passez en revue votre adresse entrée et/ou l’adresse suggérée. Il appartient à l’appelant de choisir l’adresse la plus appropriée pour le client.

Statut	Description	Nombre d’adresses suggérées retournées	Recommandation de réponse d’état
Verified shippable (Valide pour l’expédition)	L’adresse est vérifiée, et valide en tant qu’adresse d’expédition.	Unique	Passez à l’adresse vérifiée.
Vérifié	L’adresse est vérifiée.	Unique	Passez à l’adresse vérifiée.
Interaction required (Interaction nécessaire)	L’adresse suggérée est considérablement modifiée et nécessite la confirmation de l’utilisateur.	Unique	Passez à l’adresse confirmée par l’utilisateur.
Street partial (Informations sur la voie incomplètes)	La rue donnée dans l’adresse est partielle et nécessite davantage d’informations.	Multiple (maximum trois)	Passez à l’adresse confirmée par l’utilisateur.
Premises partial (Informations sur le bâtiment incomplètes)	Les informations fournies sur le bâtiment (numéro de bâtiment, numéro de suite, etc.) sont incomplètes.	Multiple (maximum trois)	Passez à l’adresse confirmée par l’utilisateur.
Multiple	Plusieurs champs sont incomplets dans l’adresse (notamment ceux concernant la voie et le bâtiment).	Multiple (maximum trois)	Passez à l’adresse confirmée par l’utilisateur.
Aucun	L’adresse est incorrecte.	Aucun	Passez à l’adresse confirmée par l’utilisateur.
Non validée	L’adresse n’a pas pu être envoyée via le processus de validation.	Aucun	Passez à l’adresse confirmée par l’utilisateur.

Exemple de requête

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

Réponse REST

Si elle réussit, la méthode renvoie un objet AddressValidationResponse dans le corps de la réponse, avec un code d’état HTTP 200 . Un exemple suit.

Codes d’erreur et de réussite de la réponse

Chaque réponse est fournie avec un code d’état HTTP qui indique la réussite ou l’échec et les informations de débogage. Utilisez un outil de suivi réseau pour lire ce code, le type d’erreur et d’autres paramètres. Pour obtenir la liste complète, consultez Codes d’erreur REST de l’Espace partenaires.

Exemple de réponse

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

Partager via