Perguntas · Moradas

Como acrescento o preenchimento automático de moradas ao meu formulário?

O que vê quem preenche

Escreve «r augusta» e vê «Rua Augusta», com as localidades onde essa rua existe; se já preencheu a localidade, as sugestões apertam-se a ela. Escolhida a rua, escreve o número de porta e o formulário diz-lhe se consta no registo: em Portugal é o troço da rua que decide os três últimos algarismos do código postal, e o código que chega é o desse troço, não os quatro algarismos genéricos da cidade.

Na seleção os campos morada, código postal e localidade preenchem-se com o registo passado pelo motor, o mesmo da verificação de moradas. A base de contactos nasce limpa em vez de ser limpa depois.

Como se paga

Por sessão, não por tecla premida. Os pedidos de sugestão enquanto se escreve são gratuitos; conta-se uma só operação quando o utilizador seleciona a morada e os campos se preenchem. Se depois mudar o número e voltar a selecionar na mesma sessão, não paga de novo. Cada sessão admite até trinta pedidos e vale dez minutos. Os preços estão na página de preços.

Como se integra

Três peças:

1. Um token da API, na área pessoal.
2. Um pequeno proxy no seu servidor, uma página que recebe o pedido do browser, acrescenta o token e o reencaminha para o nosso endpoint. É preciso porque o token nunca deve estar no código que corre no browser.
3. O widget ra-suggerisci.js, sem dependências: indica-lhe o endereço do proxy e os seletores dos campos do formulário, e ele faz o resto: trata sozinho da espera enquanto se escreve, do contexto dos campos já preenchidos e do preenchimento na escolha.

Quem prefere fazer por si chama diretamente o endpoint /api/v1/suggest: um identificador de sessão gerado pelo cliente, o texto escrito, os campos já conhecidos como contexto; depois a ação de seleção com a rua escolhida e o número. Está tudo na documentação da API.

Casos particulares

• Outros países: as sugestões existem em cada país com o registo de moradas em serviço (a lista); o formulário passa o país escolhido pelo utilizador e o widget procura lá, com a forma do número e do código postal desse país. O utilizador pode escrever tudo num só campo («Kalverstraat 92 Amsterdam»): a resposta diz como o leu (parsed: rua, número, código postal). Num país sem registo a resposta di-lo e não abre nenhuma sessão: o preenchimento continua à mão, sem cobrança.
• WooCommerce e PrestaShop: não é preciso escrever nada, há o plugin WooCommerce e o módulo PrestaShop com o preenchimento automático no checkout e a verificação das encomendas.
• Rua que não aparece: em Portugal o registo nacional não cobre todas as ruas, e o utilizador pode sempre escrever a morada por inteiro; o registo passará pela verificação num segundo momento, a partir do ficheiro ou da API.
• Vários formulários, vários sites: o mesmo token serve todos os formulários; o proxy pode estar em cada site ou ser um só.

O que acontece aos campos

A rua é completada na forma do registo, a localidade escolhida entre as que têm essa rua, o código postal de sete algarismos posto pelo motor: com o número chega o código do troço, não o genérico da cidade.