API padronizada de endereços

Funcionalidades e convenções

1. Apoio ao preenchimento de formulários: quando preenchemos o CEP, alguns campos do formulário já ficam automaticamente preenchidos.
2. Confirmação visual do endereço: a localização espacial do endereço no mapa ajuda na confirmação de expectativa, ou seja, faz o usuário a reconhecer que o contexto geográfico bate com o esperado.

Solicitações REST

Como criamos uma convenção para expressar os endereços em URI, dispensa variáveis detalhadas. O endpoint pode ser expresso pelos parâmetros solicitados.

1. GET /ADR_compact/{cepVia}~{descritor_predial}~{complementoCompact}/geo:{strGeo}: tanto a parte cadastral como espacial fornecidas de maneira altamente padronizada. Não há trafego de grafias intermediárias nem sugestão de melhor preenchimento.
2. POST /ADR_free/: tudo numa só string multilinha.
3. POST /ADR_parts/: cada parte numa variável, com alternativas, por exemplo entre $uf+$municipio ou $cod_Ibge.

Respostas REST

As respostas são pacotes JSON, mas seu status HTTP apoia principalmente na troca de formato do JSON, que ocorre nas mensagens de erro.

• status 200: OK. O JSON devolvido é um endereço (preexistente na base) encontrado.
• status 201: Created. O JSON devolvido é relativo a aceitação do fornecido como "novo endereço válido". Raramente ocorre, exceto se foi um cliente de fato confirmando.
• status 202: Accepted. O JSON informa ID de Job, etc. mas não diz que aceitou nem que não aceitou, apenas pede pro usuário aguardar.
• status 400: Bad Request. Ocorre quando o formato do CEP ou endereço enviado está incorreto ou incompleto. JSON informa o erro, o tipo de inconsistência, entre numeração predial e CEP por exemplo ...
• status 404: Not Found. Indica ou que a requisição está correta, ou que o CEP (ou outra parte) não existe na base de dados.

Protocolo do ID inteligente

... Para além da resposta imediata em REST, há também a resposta de longo prazo (horas a semanas) à solicitação do endereço, quando o gid é negativo...