Moradas certas nos registos de clientes: área de cliente, CRM e back-office

O cliente começa a escrever a rua, escolhe a morada numa lista, e o código postal (CP7), a localidade e o concelho preenchem-se sozinhos — como no portal de cliente de um operador, onde a morada de faturação e a de instalação têm de bater certo. São duas linhas: carregar o widget e ligá-lo ao campo da morada.

<script src="https://moradas.dev/widget.js"></script>
<script>
  PTAddress.attach(document.querySelector('#morada'), {
    endpoint: 'https://moradas.dev',
    fill: { postal: '#cp7', city: '#localidade', municipality: '#concelho' },
    onSelect: function (data) {
      // data = the suggestion's data object: street, localidade, concelho, distrito, cp7...
      document.querySelector('#rua').value = data.street; // the street name as written in the data
    }
  });
</script>

Todos os campos continuam editáveis e, se o serviço não responder, o formulário funciona como um formulário normal. Numa rua com vários códigos postais, o widget preenche o CP7 exato quando o cliente escreve o número de porta. Todas as opções (fill, onSelect, onResolve, endpoint, lang…) estão na documentação do widget, com exemplos para React e Vue.

Quem regista moradas ao telefone não tem tempo para procurar códigos postais. O mesmo widget liga-se aos formulários do operador — o CRM de uma empresa de serviços, a ficha de cliente numa ferramenta interna — e o CP7 sai certo à primeira. Quando a rua tem vários códigos postais, o número de porta decide: o widget trata disso no browser; no servidor, /resolve faz o mesmo com o art_id da sugestão e o número.

GET /resolve?art=132467&numero=10        (art_id of "Rua das Adelas, Lisboa" in a fresh /suggest)

{ "resolved": { "value": "Rua das Adelas, Lisboa",
                "data": { "art_id": 132467, "kind": "street", "street": "Rua das Adelas",
                          "localidade": "Lisboa", "concelho": "Lisboa", "distrito": "Lisboa",
                          "cp7": "1200-008", "nseg": 2 } },
  "segments": [ { "cp7": "1200-007", "label": "Impares de 3 a 17A" },
                { "cp7": "1200-008", "label": "Pares de 2 a 28" } ] }

O art_id muda a cada atualização dos dados: use-o logo a seguir ao /suggest e não o guarde no registo — guarde a morada, o CP7 e a localidade. Sem número de porta, resolved vem null e segments lista os troços, para o operador escolher.

Uma base de clientes com anos de moradas escritas à mão tem códigos postais errados, localidades trocadas e registos repetidos. Com POST /batch passam-se até 100 moradas num só pedido — na prática, envie até 50 de cada vez — e cada linha volta com um veredicto: ok (código postal determinado, em cp7), ambiguous (sem resposta única: vários candidatos, uma rua com vários códigos sem número de porta, ou só uma localidade) ou not_found. As linhas ok corrigem-se sozinhas; as ambiguous vêm com a melhor candidata, para alguém decidir. Serve também para verificações de conformidade: confirmar que a morada declarada num registo existe e tem aquele código postal.

curl -s -X POST "https://moradas.dev/batch" -H "Content-Type: application/json" \
  -d '{"items":[{"id":"o-1001","q":"Avenida da Liberdade 196, Lisboa"},
             {"id":"o-1003","q":"xyzxyz qqq"}]}'
# {"results":[{"id":"o-1001","q":"Avenida da Liberdade 196, Lisboa","status":"ok",
#              "cp7":"1250-147","suggestion":{…}},
#             {"id":"o-1003","q":"xyzxyz qqq","status":"not_found",
#              "cp7":null,"suggestion":null}]}

id é o seu identificador do registo, devolvido tal e qual. Um pedido com N moradas conta como N pedidos no limite geral; num 429, espere os segundos do cabeçalho Retry-After e continue. O exemplo completo em Python e os pormenores dos veredictos estão na documentação do /batch.

Muitos registos já têm um código postal, mas não a localidade, o concelho ou o distrito — ou têm-nos errados. /cp/{cp7} devolve a ficha do código: localidade, concelho, distrito e as ruas que abrange. Com só os quatro primeiros dígitos, /cp/{cp4} lista todos os códigos dessa zona — útil para validar um campo ou preencher uma lista de escolha.

GET /cp/1000-098

{ "cp7": "1000-098", "cp4": "1000", "cp3": "098",
  "distrito": "Lisboa", "concelho": "Lisboa", "localidade": "Lisboa",
  "arterias": [ { "art_id": 130446, "street": "Praça do Chile",
                  "troco": null, "porta": null, "cliente": null } ] }

Valide o formato antes de chamar (^\d{4}-\d{3}$); um código inexistente devolve 404 com o motivo no cabeçalho X-Moradas-Hint. Mais em Validar código postal.