Validar una dirección

  • Article

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

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