Validar una dirección

Artículo
07/11/2024

Se aplica a: Centro de partners | Centro de partners operado por 21Vianet | Centro de partners para Microsoft Cloud for US Government

En este artículo se explica cómo validar una dirección mediante la API de validación de direcciones.

La API de validación de direcciones solo debe usarse para la validación previa de las actualizaciones de perfil de cliente. En función del estado de respuesta de la API, el autor de la llamada debe elegir la dirección más adecuada para el cliente.

Requisitos previos

Credenciales tal como se describen en el artículo Autenticación del Centro de partners. Este escenario admite la autenticación con credenciales de aplicación independiente y app+usuario.

C#

Para validar una dirección, primero cree una instancia de un nuevo objeto Address y rellene con la dirección que se va a validar. A continuación, recupere una interfaz a las operaciones validations de la propiedad IAggregatePartner.Validations y llame al método IsAddressValid con el objeto 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();
}

Solicitud REST

Sintaxis de la solicitud

Método	URI de solicitud
POST	{baseURL}/v1/validations/address HTTP/1.1

Encabezados de solicitud

Para obtener más información, consulta Encabezados REST del Centro de partners.

Cuerpo de la solicitud

En esta tabla se describen las propiedades necesarias en el cuerpo de la solicitud.

Nombre	Tipo	Obligatorio*	Descripción
addressline1	string	Y	Primera línea de la dirección.
addressline2	string	N	Segunda línea de la dirección. Esta propiedad es opcional.
city	string	Y	La ciudad.
state	string	Y	Estado
postalcode	string	Y	Código postal.
country	string	Y	El código de país ISO alpha-2 de dos caracteres.

* Las propiedades requeridas pueden cambiar en función del país o región.

Detalles de la respuesta

La respuesta devuelve uno de los siguientes mensajes de estado. Si la respuesta de estado no es Verificado o VerifiedShippable, revise la dirección especificada o la dirección sugerida. Depende del autor de la llamada elegir la dirección más adecuada para el cliente.

Estado	Descripción	Número de direcciones sugeridas devueltas	Recomendación de respuesta de estado
Verified shippable	La dirección está comprobada y puede recibir envíos.	Single	Continúe con la dirección verificada.
Verificada	La dirección está comprobada.	Single	Continúe con la dirección verificada.
Interaction required	La dirección sugerida cambia significativamente y necesita confirmación del usuario.	Single	Continúe con la dirección confirmada por el usuario.
Street partial	La calle indicada en la dirección es parcial y necesita más información.	Varias: tres como máximo	Continúe con la dirección confirmada por el usuario.
Premises partial	Los locales especificados (número de edificio, número de suite, etc.) son parciales y se necesita más información.	Varias: tres como máximo	Continúe con la dirección confirmada por el usuario.
Varios	La dirección tiene varios campos que son parciales (también puede incluir Street partial y Premises partial).	Varias: tres como máximo	Continúe con la dirección confirmada por el usuario.
None	La dirección es incorrecta.	None	Continúe con la dirección confirmada por el usuario.
No validado	La dirección no se pudo enviar a través del proceso de validación.	None	Continúe con la dirección confirmada por el usuario.

Ejemplo de solicitud

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

Respuesta REST

Si se ejecuta correctamente, el método devuelve un objeto AddressValidationResponse en el cuerpo de la respuesta, con un código de estado HTTP 200 . A continuación se muestra un ejemplo.

Códigos de error y de respuesta correctos

Cada respuesta incluye un código de estado HTTP que indica información de éxito o error y depuración. Use una herramienta de seguimiento de red para leer este código, tipo de error y otros parámetros. Para obtener la lista completa, consulta Códigos de error de REST del Centro de partners.

Ejemplo de respuesta

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

Compartir a través de