Validar um endereço

Artigo
04/11/2024

Aplica-se a: Partner Center | Partner Center operado pela 21Vianet | Partner Center para o Microsoft Cloud for US Government

Este artigo explica como validar um endereço usando a API de validação de endereço.

A API de validação de endereço só deve ser usada para pré-validação de atualizações de perfil de cliente. Com base no status de resposta da API, o chamador deve escolher o endereço mais apropriado para o cliente.

Pré-requisitos

Credenciais, conforme descrito em Autenticação do Partner Center. Esse cenário oferece suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.

C#

Para validar um endereço, primeiro instancie um novo objeto Address e preencha-o com o endereço a ser validado. Em seguida, recupere uma interface para operações Validations da propriedade IAggregatePartner.Validations e chame o método IsAddressValid com o 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();
}

Solicitação REST

Sintaxe da solicitação

Método	URI da solicitação
POST	{baseURL}/v1/validations/address HTTP/1.1

Cabeçalhos da solicitação

Para obter mais informações, confira Cabeçalhos REST do Partner Center.

Corpo da solicitação

Esta tabela descreve as propriedades necessárias no corpo da solicitação.

Nome	Tipo	Necessário*	Descrição
linha de endereço1	string	Y	A primeira linha do endereço.
linha de endereço2	string	N	A segunda linha do endereço. Essa propriedade é opcional.
cidade	string	Y	A cidade.
estado	string	Y	O estado.
postalcode	string	Y	O CEP.
country	string	Y	O código de país alpha-2 de ISO de dois caracteres.

* As propriedades necessárias podem mudar de acordo com o país ou região.

Detalhes da resposta

A resposta retorna uma das seguintes mensagens de status. Se a resposta de status não for Verified ou VerifiedShippable, revise seu endereço inserido e/ou endereço sugerido. Cabe ao chamador escolher o endereço mais adequado para o cliente.

Status	Descrição	O número de endereços sugeridos retornados	Recomendação de resposta de status
Destino de entrega verificado	O endereço foi verificado e pode ser usado para entregas.	Single	Prossiga com o endereço verificado.
Verificada	O endereço foi verificado.	Single	Prossiga com o endereço verificado.
Interação necessária	O endereço sugerido é significativamente alterado e precisa da confirmação do usuário.	Single	Prossiga com o endereço confirmado pelo usuário.
Rua parcial	A rua que consta no endereço é parcial e precisa de mais informações.	Múltiplo – máximo de três	Prossiga com o endereço confirmado pelo usuário.
Local parcial	O local determinado (número do prédio, número do conjunto, entre outros) é parcial e precisa de mais informações.	Múltiplo – máximo de três	Prossiga com o endereço confirmado pelo usuário.
Múltiplo	Há vários campos parciais no endereço (pode incluir rua parcial e local parcial).	Múltiplo – máximo de três	Prossiga com o endereço confirmado pelo usuário.
Nenhum	O endereço está incorreto.	Nenhum	Prossiga com o endereço confirmado pelo usuário.
Não validado.	O endereço não pôde ser enviado por meio do processo de validação.	Nenhum	Prossiga com o endereço confirmado pelo usuário.

Exemplo de solicitação

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

Resposta REST

Se bem-sucedido, o método retorna um objeto AddressValidationResponse no corpo da resposta, com um código de status HTTP 200 . Há um exemplo a seguir.

Códigos de êxito e de erro de resposta

Cada resposta vem com um código de status HTTP que indica sucesso ou falha e informações de depuração. Use uma ferramenta de rastreamento de rede para ler esse código, tipo de erro e outros parâmetros. Para obter a lista completa, confira Códigos de erro REST do Partner Center.

Exemplo de resposta

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

Share via