Validar um endereço

Artigo
07/11/2024

Aplica-se a: Partner Center | Partner Center operado pela 21Vianet | Partner Center for 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 na autenticação do Partner Center. Este 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();
}

Pedido REST

Sintaxe da solicitação

Método	URI do pedido
POST	{baseURL}/v1/validações/endereço HTTP/1.1

Cabeçalhos do pedido

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

Corpo do pedido

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

Nome	Tipo	Necessário*	Description
endereço1	string	Y	A primeira linha do endereço.
endereço2	string	N	A segunda linha do endereço. Esta propriedade é opcional.
cidade	string	Y	A cidade.
state	string	Y	O Estado.
pós-alcoda	string	Y	O código postal.
país/região	string	Y	O código de país ISO alfa-2 de dois caracteres.

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

Detalhes da resposta

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

Status	Description	Número de endereços sugeridos devolvidos	Recomendação de resposta de status
Transitável verificado	O endereço é verificado e pode ser enviado para.	Única	Prossiga com o endereço verificado.
Verificado	O endereço é verificado.	Única	Prossiga com o endereço verificado.
Interação necessária	O endereço sugerido é significativamente alterado e precisa da confirmação do usuário.	Única	Prossiga com o endereço confirmado pelo usuário.
Rua parcial	A rua indicada 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.
Premissas parciais	As premissas dadas (número do edifício, número da suíte e outras) são parciais e precisam de mais informações.	Múltiplo — máximo de três	Prossiga com o endereço confirmado pelo usuário.
Várias	Há vários campos que são parciais no endereço (potencialmente também incluindo rua parcial e instalações parcial).	Múltiplo — máximo de três	Prossiga com o endereço confirmado pelo usuário.
Nenhuma	O endereço está incorreto.	Nenhuma	Prossiga com o endereço confirmado pelo usuário.
Não validado	O endereço não pôde ser enviado através do processo de validação.	Nenhuma	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: 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"
}

Resposta do REST

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

Códigos de sucesso e 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, consulte 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: 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'"
}

Partilhar via