fonte da imagem: http://1.bp.blogspot.com

Por diversas vezes precisei de um Web Service dos Correios para automatizar o rastreamento das minhas encomendas, mas nunca encontrei um que prestasse. Pelo andar da carruagem, acredito que pelas próximas décadas não haverá uma solução oficial.Tomei vergonha na cara e fiz uma de graça. Quer saber como usufruir? Leia o post completo!

A primeira questão foi: qual padrão/técnica usar? Optei pelo mais leve, simples e largamente utilizado no mercado, o REST. A segunda questão foi: qual formato retornar? Tomei como base novamente a tendência: JSON. Antes de mostrar o serviço, vou explicar como fiz.

A única fonte de dados que os Correios disponibilizam é uma página no formato HTML como esta:

Página de rastreamento dos Correios

Moderno… mas precisei separar as informações úteis do código de apresentação da página utilizando a técnica Web Scraping. Claro que não reinventei a roda. Utilizei o projeto Alfred Library idealizado pelo meu amigo Marlon Carvalho. O Alfred fez todo o trabalho sujo e me entregou os dados praticamente prontos para uso. Fiz apenas alguns tratamentos para remover redundâncias e corrigir formatações.

Ainda no espírito colaborativo, resolvi incrementar outro projeto do Marlon, o EncomendaZ, que segue a mesma filosofia open source do serviço que criei. Registramos juntos o domínio encomendaz.net, onde disponibilizei o serviço: services.encomendaz.net. Chega de explicações e vamos ao que interessa.

Rastreamento

Por enquanto esta é a única funcionalidade, mas em breve disponibilizarei outras. A URL é a seguinte: http://services.encomendaz.net/tracking.json.

Os parâmetros são estes:

• id (obrigatório): identificação/código do objeto a ser rastreado.
• start (opcional): indica à partir de qual registro deve constar na lista.
• end (opcional): similar ao start, porém representa o índice do último registro.
• callback (opcional): nome da função de retorno utilizada por chamadas JSONP.

Finalmente, um exemplo. A requisição http://services.encomendaz.net/tracking.json?id=PB882615209BR devolverá o seguinte:

{
	"status": "ok",
	"data": [
		{
			"date": "Wed, Jan 11 15:30:00 -0300 2012",
			"city": "Garibaldi",
			"state": "RS",
			"status": "acceptance"
		},
		{
			"date": "Wed, Jan 11 17:14:00 -0300 2012",
			"city": "Garibaldi",
			"state": "RS",
			"status": "enroute",
			"description": "Em trânsito para CTE Porto Alegre/RS"
		},
		{
			"date": "Thu, Jan 12 11:53:00 -0300 2012",
			"city": "Porto Alegre",
			"state": "RS",
			"status": "enroute",
			"description": "Encaminhado para CTE Salvador/BA"
		},
		{
			"date": "Sat, Jan 21 13:24:00 -0300 2012",
			"city": "Salvador",
			"state": "BA",
			"status": "enroute",
			"description": "Saiu para entrega"
		},
		{
			"date": "Sat, Jan 21 14:41:00 -0300 2012",
			"city": "Salvador",
			"state": "BA",
			"status": "enroute",
			"description": "Empresa sem Expediente"
		},
		{
			"date": "Mon, Jan 23 11:01:00 -0300 2012",
			"city": "Salvador",
			"state": "BA",
			"status": "enroute",
			"description": "Saiu para entrega"
		},
		{
			"date": "Mon, Jan 23 16:15:00 -0300 2012",
			"city": "Salvador",
			"state": "BA",
			"status": "enroute",
			"description": "Entrega não efetuada"
		},
		{
			"date": "Tue, Jan 24 09:04:00 -0300 2012",
			"city": "Salvador",
			"state": "BA",
			"status": "enroute",
			"description": "Saiu para entrega"
		},
		{
			"date": "Tue, Jan 24 16:15:00 -0300 2012",
			"city": "Salvador",
			"state": "BA",
			"status": "delivered"
		}
	]
}

Suponha que você esteja implementando um aplicativo para dispositivos móveis e na primeira atualização só existiam 3 registros. Para economizar rede, nas tentativas seguintes basta obter à partir do 4º registro:

http://services.encomendaz.net/tracking.json?id=PB882615209BR&start=4.

A resposta será a seguinte:

{
	"status": "ok",
	"data": [
		{
			"date": "Sat, Jan 21 13:24:00 -0300 2012",
			"city": "Salvador",
			"state": "BA",
			"status": "enroute",
			"description": "Saiu para entrega"
		},
		{
			"date": "Sat, Jan 21 14:41:00 -0300 2012",
			"city": "Salvador",
			"state": "BA",
			"status": "enroute",
			"description": "Empresa sem Expediente"
		},
		{
			"date": "Mon, Jan 23 11:01:00 -0300 2012",
			"city": "Salvador",
			"state": "BA",
			"status": "enroute",
			"description": "Saiu para entrega"
		},
		{
			"date": "Mon, Jan 23 16:15:00 -0300 2012",
			"city": "Salvador",
			"state": "BA",
			"status": "enroute",
			"description": "Entrega não efetuada"
		},
		{
			"date": "Tue, Jan 24 09:04:00 -0300 2012",
			"city": "Salvador",
			"state": "BA",
			"status": "enroute",
			"description": "Saiu para entrega"
		},
		{
			"date": "Tue, Jan 24 16:15:00 -0300 2012",
			"city": "Salvador",
			"state": "BA",
			"status": "delivered"
		}
	]
}

Agora somente os 2 primeiros registros com retorno JSONP:

http://services.encomendaz.net/tracking.json?id=PB882615209BR&end=2&callback=retorno

retorno({
	"status": "ok",
	"data": [
		{
			"date": "Wed, Jan 11 15:30:00 -0300 2012",
			"city": "Garibaldi",
			"state": "RS",
			"status": "acceptance"
		},
		{
			"date": "Wed, Jan 11 17:14:00 -0300 2012",
			"city": "Garibaldi",
			"state": "RS",
			"status": "enroute",
			"description": "Em trânsito para CTE Porto Alegre/RS"
		}
	]
})

Caso haja erro na requisição, o serviço continuará retornando a mesma estrutura de dados JSON:

http://services.encomendaz.net/tracking.json?id=XX000000000BR

{
	"status": "error",
	"message": "O sistema dos Correios não possui dados sobre o objeto informado"
}

O serviço está hospedado no plano gratuito da nuvem Google App Engine. O código-fonte está no GitHub. Sugestões, colaborações e experimentações serão muito bem vindas! Se quiser propor melhorias ou relatar bugs, clique aqui.

Se gostou, escreve aí nos comentários