Olá amigos!

Quem aqui nunca teve problemas em fazer formulários com endereço completo e de deparou com a dificuldade em combinar corretamente o CEP ao endereço, consultando sua correspondência no próprio site dos Correios, fazendo o seu usuário clicar e navegar até lá para conferir?

Certo, os Correios oferecem um webservice que faz isso, porém ele é pago e nem sempre temos condições ou nossos clientes estão dispostos a pagar por este serviço.

Pensando nisso um grupo de desenvolvedores criou uma iniciativa completamente aberta e gratuita para a consulta de Cep e endereço, é o BuscarCep Webservice que permite a qualquer desenvolvedor fazer consultas em tempo real dos Ceps, endereços e códigos do Ibge para cada município Brasileiro. Isso em si já é uma enorme facilidade e pensando em tornar cada vez mais simples essa consulta eu criei uma API em ActionScript3 que encapsula todos os métodos necessários para consultar um Cep e resultar o endereço completo ou o inverso, informar uma rua e uma cidade e receber uma lista de Ceps para cada rua correspondente à pesquisa.

Abaixo eu apresentarei essa Api (ConsultaCep) e mostrarei um exemplo prático em Flash (Funciona pra Flash e Air) da utilização da mesma, assim como sua facilidade. Para exemplificar essa idéia considerem um formulário de contato onde você quer coletar os dados das pessoas e dentre esses dados estão o Cep e o endereço corretos dela, seguimos:

Formulário de exemplo

Como funciona a API

A ConsultaCep API funciona fazendo requisições pré-determinadas ao webservice BuscarCep.com.br e tratando as respotas e as mensagens de erro.

Cada item da resposta que contém todas as informações (cep, logradouro, bairro, cidade, estado, etc) é guardado em um objeto da Classe “LocalItem” (na documentação contém a descrição), esse objeto contém todas as propriedades do endereço, esse objeto é transportado até nós através da Classe ConsultaCepEvent, que responde aos eventos disparados ao enviar e receber os dados de uma consulta.

A Classe ConsultaCepEvent (que extende a Classe Event) carrega um objeto público “data“, que é um objeto da Classe DataItem, que guarda guarda as mensagens “data.message” e os resultados em um array “response“, e estes são tratados no ConsultaCepEvent.RESPONSE (para sucesso) ou ConsultaCepEvent.ERROR (para falhas).

Basicamente, você cria um objeto da ConsultaCep e adiciona os eventos response e error, abaixo segue um exemplo prático de uma DocumentClass que dispara uma consulta quando se digita um último dígito de um Cep.
Neste exemplo eu utilizo somente o padrão da Classe que é consultar utilizando interface XML e sem autenticação, o que só te permite fazer 5 consultas por minuto por IP.

A interface de resposta pode ser selecionada entre XML e TEXT, através da propriedade responseMethod do objeto ConsultaCep.

A autorização para consulta pode ser definida entre Assinada e Não-assinada, para isso você utiliza mais duas propriedades do objeto ConsultaCep que são authMethod e key, você deve selecionar AuthMethod.SIGNED para utilizar a sua apikey (fornecida pelo serviço) e conseguir um número de 20 consultas por minuto. Veja mais detalhes na documentação.

FormExample.as

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

package 
{
	import br.ederlima.CEP.ConsultaCep;
	import br.ederlima.CEP.events.ConsultaCepEvent;
	import br.ederlima.CEP.data.LocalItem;
	import flash.display.MovieClip;
	import flash.display.Sprite;
	import flash.events.Event;
	import flash.text.TextField;
 
	/**
	 * FormExample - Consula Cep API
	 * @author Eder Lima
	 * @copy FlashPedia
	 */
	public class FormExample extends Sprite
	{
		//Criando uma referência para o formulário que está na biblioteca
		private var form:Form = new Form();
		//Criando uma referência para o inputtext do cep
		private var mycep:TextField = form.cep;
		//criando um objeto ConsultaCep
		private var consulta:ConsultaCep = new ConsultaCep();
 
		public function FormExample()
		{
			//configurando o ambiente ao iniciar
			addEventListener(Event.ADDED_TO_STAGE, configure);
		}
		//Função que configura o ambiente
		private function configure(event = null):void
		{
			//posicionando o formulário
			form.x = form.y = 0;
			//adicionando o formulário ao palco
			addChild(form);
			//desconsiderando os filhos da mensagem (apenas para evitar que o cursor mude)
			form.msg.mouseChildren = false;
			//escondendo a mensagem
			form.msg.visible = false;
			//criando um ouvinte para a resposta da consulta
			consulta.addEventListener(ConsultaCepEvent.RESPONSE, responseHandler);
			//criando um ouvinte para a resposta de erro
			consulta.addEventListener(ConsultaCepEvent.ERROR, errorHandler);
			//adicionando um evento ao digitar o cep
			mycep.addEventListener(Event.CHANGE, inputHandler);
			//limitando a quantidade de caracteres do cep a 8 caraceteres "79103600", sem máscara 
			mycep.maxChars = 8;
		}
		//Função que responde a interação com o campo cep
		private function inputHandler(event:Event):void
		{
			//Limpar os campos (caso não seja a primeira busca)
			clearFields();
			form.msg.visible = false;
			//caso o campo contenha 8 caracteres
			if (mycep.length == 8)
			{
				//Mostrar mensagem informando que a busca está em andamento
				form.msg.msg.text = "Buscando endereço...";
				form.msg.visible = true;
				//Relizar a Busca utilizando o cep digitado
				consulta.buscarLocal(mycep.text);
			}
 
		}
		//Função de resposta positiva da consulta
		private function responseHandler(event:ConsultaCepEvent):void
		{
			//cria-se um objeto LocalItem (que comporta os dados)
			//utilizando a posição 0[1] do objeto data.response (objeto "data" e array "response" com os dados da consulta)
			var localItem:LocalItem = event.data.response[0];
			//informando os dados em cada campo utlizando as propriedades de cada objeto LocalItem
			form.logradouro.text = localItem.logradouro;
			form.bairro.text = localItem.bairro;
			form.cidade.text = localItem.cidade;
			form.estado.text = localItem.uf;
			//Informando o status enviado pelo serviço sobre a consulta (data.message)
			form.msg.msg.text = event.data.message;
			form.msg.visible = true;
		}
		//Função que responde ao erro da consulta
		private function errorHandler(event:ConsultaCepEvent):void
		{
			//limpa os campos
			clearFields();
			//exibe a mensagem de erro carregada no objeto (data.message)
			form.msg.msg.text = event.data.message;
			form.msg.visible = true;
		}
		//Função que limpa os campos
		private function clearFields():void
		{
			form.logradouro.text = "";
			form.bairro.text = "";
			form.cidade.text = "";
			form.estado.text = "";
			form.msg.msg.text = "";
		}
	}
 
}

Notem como eu utilizo criar um objeto LocalItem para ler os dados recebidos pela consulta e trazidos pelo objeto “data” na função responseHandler.

Bom, é a primeira versão desta API, então com certeza melhorias devem ser feitas e eu estarei sempre atualizando-a para permitir o melhor funcionamento com o serviço.

Lembrando que para você utilizar uma APIKEY é necessário cadastrar-se no site do serviço, você reberá a sua imediantamente durante o cadastro, mais detalhes em http://www.buscarcep.com.br.

Update: Consultas autenticadas e Método TEXT

Fazendo uma consulta com sua APIKey e alternando o método para TEXT ao invés de XML:

1
2
3
4
5
6
7
8
9
10
11
12
13

import br.ederlima.CEP.ConsultaCep;
import br.ederlima.CEP.data.LocalItem;
import br.ederlima.CEP.methods.authMethod;
import br.ederlima.CEP.methods.ResponseMethod;
 
var consulta:ConsultaCep = new ConsultaCep();
//configurando uma consulta assinada
consulta.authMethod = AuthMethod.SIGNED;
consulta.key = "suachaveunicacedidapelosistema";
//configurando o método TEXT, ao invés de XML
consulta.responseMethod = ResponseMethod.TEXT_METHOD;
 
//.... Todas as funções de controle, como acima

Documentação da API:
http://www.ederlima.com.br/arquivos/flash/ConsultaCep

Download dos Fontes deste exemplo:

Consulta CEP Exemplo
Baixado 316 vezes
Tamanho 129.12 KB

Update em 22/10 – Flash Builder 4 beta 2

Para visualizar o funcionamento da API também no Flash Builder, confira este endereço:

http://www.ederlima.com.br/arquivos/flash/consultacepflex/
Clique com o botão direito para visualizar o código fonte do MXML.

É necessário o Flash Builder 4 beta 2 para visualizar, porém você pode modificar o código para rodar utilizando o Adobe Flex Builder 3.

Download do projeto

Exemplo Consulta CEP Flash Builder 4
Baixado 251 vezes
Tamanho 1.65 MB

Enjoy! ;)