DOCS
InícioPara fornecedores logísticos Sugerir e validar moradas

Sugerir e validar moradas

Complete moradas enquanto os clientes escrevem e confirme uma morada antes de enviar para ela.

GraphQL

Utilize locationSuggest para oferecer moradas completas enquanto um cliente escreve e locationValidate para verificar uma morada e obtê-la num formato normalizado. Quando uma morada é validada, pode passar o resultado para partyCreate ou partyCreateWorkflow para que a morada fique registada como verificada.

Sugerir moradas enquanto os clientes escrevem 

Envie a morada parcial que o cliente escreveu e o país onde pesquisar. locationSuggest devolve moradas completas correspondentes, com a mesma estrutura do input de localização de partyCreate, para que possa preencher o resto do formulário de morada a partir da que o cliente escolher.

1query LocationSuggest($input: LocationSuggestInput!) {
2 locationSuggest(input: $input) {
3 line1
4 line2
5 locality
6 administrativeArea
7 administrativeAreaCode
8 postalCode
9 countryCode
10 latitude
11 longitude
12 }
13}

Campos de input da sugestão

Campo↕Obrigatório↕Descrição↕
countryCodeO código ISO 3166-1 alfa-2 do país onde pesquisar.
limitO número máximo de sugestões a devolver, de 1 a 20. O valor predefinido é 10.
queryA morada parcial, em texto livre, que o cliente escreveu, como 22382 Avenida Emp.

As sugestões são um ponto de partida, não uma morada verificada. Valide a morada final do cliente antes de criar uma party com ela.

Validar uma morada 

Envie a morada completa para locationValidate. Devolve o grau de verificação da morada, a morada no seu formato normalizado e um verificationToken quando a morada é verificada.

1query LocationValidate($input: LocationValidateInput!) {
2 locationValidate(input: $input) {
3 status
4 verificationToken
5 address {
6 line1
7 line2
8 locality
9 administrativeArea
10 administrativeAreaCode
11 postalCode
12 countryCode
13 latitude
14 longitude
15 propertyType
16 }
17 }
18}

Campos de input da validação

Campo↕Obrigatório↕Descrição↕
administrativeAreaO nome do estado, província ou região.
administrativeAreaCodeO código do estado, província ou região, como CA.
countryCodeO código ISO 3166-1 alfa-2 do país.
line1A primeira linha da morada.
line2 – line4Linhas de morada adicionais, se aplicável.
localityA cidade, vila ou aldeia.
postalCodeO código postal ou ZIP.

Envie o máximo de informação da morada de que dispuser. Um código postal, ou uma localidade com uma área administrativa, oferece os melhores resultados.

Estados de validação

Estado↕Significado↕Próximo passo sugerido↕
VERIFIEDA morada foi verificada até ao edifício ou à fração exata.Utilize a morada normalizada.
PARTIALLY_VERIFIEDApenas parte da morada foi verificada, como a rua ou a cidade, mas não o edifício.Peça ao cliente que confirme detalhes como o número da porta ou da fração.
UNVERIFIEDNão foi possível verificar a morada. address é null.Peça ao cliente que confirme a morada.

A morada normalizada

Quando a morada é VERIFIED ou PARTIALLY_VERIFIED, address contém o seu formato normalizado. Pode diferir do que enviou: detalhes em falta, como a cidade, podem ser preenchidos, o código postal pode ser completado e as maiúsculas e abreviaturas são corrigidas. Mostre a morada normalizada ao cliente ou utilize-a em vez do que ele escreveu.

  • latitude e longitude são incluídas quando disponíveis.
  • propertyType é RESIDENTIAL ou COMMERCIAL quando a morada é verificada e o seu tipo é conhecido, e null caso contrário. Não é aplicado automaticamente. Passe-o no input de localização ao criar a party, se o quiser utilizar.

Registar uma morada verificada numa party 

Um resultado VERIFIED inclui um verificationToken. Passe-o no input location de partyCreate ou partyCreateWorkflow, juntamente com a morada normalizada exatamente como locationValidate a devolveu. A localização da party fica então registada como verificada, sem que a morada seja verificada novamente.

1mutation PartyCreate($input: PartyCreateInput!) {
2 partyCreate(input: $input) {
3 id
4 type
5 location {
6 id
7 line1
8 locality
9 administrativeAreaCode
10 postalCode
11 countryCode
12 propertyType
13 }
14 }
15}

Tenha em conta estas regras ao passar um token:

  • Um token é válido durante um dia. Um token expirado é ignorado e a party é criada na mesma.
  • Os campos da morada têm de corresponder à morada normalizada. Se o cliente editar a morada depois de a validar, o token é ignorado e a party é criada na mesma. Valide a morada editada para obter um novo token.
  • latitude, longitude, propertyType e metadata podem ser alterados sem afetar o token.
  • Trate o token como um valor opaco. Não o analise nem o altere. Um token que tenha sido alterado, ou que tenha sido emitido para outra organização, faz falhar o pedido.

Erros 

Mensagem↕Causa↕O que fazer↕
Address verification is unavailableNão foi possível concluir as sugestões ou a validação neste momento.Tente novamente mais tarde. Deixe o cliente continuar com a morada que introduziu.
Invalid location verification tokenO verificationToken foi alterado ou foi emitido para outra organização.Passe o token exatamente como locationValidate o devolveu ou omita-o.
limit must be between 1 and 20O limit passado a locationSuggest estava fora do intervalo permitido.Passe um limit de 1 a 20 ou omita-o para obter 10 sugestões.
GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

LocationSuggestInput LocationValidateInput PartyCreateInput PartyCreateWorkflowInput

MUTATIONS

partyCreate partyCreateWorkflow

Esta página foi útil?

Obter suporte·Documentos legais·© 2026 Zonos
Nesta página:
  • Sugerir e validar moradas
  • Sugerir moradas enquanto os clientes escrevem
  • Validar uma morada
  • Registar uma morada verificada numa party
  • Erros