RESTful Web Services dos Correios

12mar12

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 😉

Anúncios


32 Responses to “RESTful Web Services dos Correios”

  1. Iniciativa muito bacana cara. Parabéns. Você podia escrever também um post sobre RESTful Web Services, usando Jersey, por exemplo. Mas de qualquer forma, parabéns, boa iniciativa.

  2. 2 Herbertt Pavani Bamonde

    Cara, DEMAIS!!! Parabéns pela iniciativa.

  3. Muito bom Cleverson, preciso de fazer um desse para pegar dados de alguns tribunais de justiça, para atualizar dentro de um sistema de acompanhamento de processos. Faz um artigo completo com essas tecnologias !!! mas parabéns, belo artigo.

  4. 4 lucasddaniel

    opa amigo, vc ja viu o http://www.muambator.com.br? faz isso que vc fez.

    • 5 lucasddaniel

      isso foi uma dica construtiva, nao uma critica pelo seu trabalho e esfor’co. pensei que pudesse ser interpretado erroneamente depois que cliquei no postar… 😉 tou retratando

      • O muambator não dispõe de uma API, e o que ele fez pode ser usado em qualquer aplicação sem pagar.

  5. 8 racquad

    Gostaria de deixar minha sugestão de nosso webservice: a API ceplivre. Ela oferece resultados precisos em formato XML, CSV e JSON, além de fornecer dados complementares do endereço, como código IBGE do município e código DDD. Visitem.

  6. Parabéns pelo projeto. Vi que no app Encomendaz, é mostrado a bandeira do país de origem da encomenda. Porém, no retorno JSON não vejo nenhuma informação direta sobre o país. Você realiza algum tratamento baseado no código do estado, é isso?

  7. Segue um exemplo sobre como testar o web service dos correios usando a ferramenta SoapUI

    http://regifelix.com/2013/01/06/testes-de-web-services-com-a-ferramenta-soapui/

  8. 12 Nicolas

    Qual é o formato de hora usado? Tipo esses “dd/MM/yyyy”, etc.

  9. Como que descreve esse formato de data? Ex: “yyyy/MM/dd”. Abraços!

  10. 15 Ronaldo

    Ola !
    Muito legal o serviço.
    A cidade e estado não está retornando…

  11. Cara achei fantástico o post e a didática simples e prática.
    Meus parabéns.
    Vou consumi-la rsrs

  12. 17 allysonjeronimo

    Olá amigo. Obrigado por responder as dúvidas. Tenho mais uma observação. Ao tentar rastrear uma encomenda internacional, postado na China por exemplo, o WS não está retornando detalhes da localidade, como por exemplo ocorre em encomendas nacionais ou no site dos correios. O que eu poderia fazer seria tratar utilizando o sufixo do código do país (CN) para informar que foi postado na China. Mas não seria interessante incluir tbm informações de localidade em encomendas internacionais? Ou será que o problema é específico com esse meu ID? Abraços!

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

    http://websro.correios.com.br/sro_bin/txect01$.QueryList?P_LINGUA=001&P_TIPO=001&P_COD_UNI=RA396206829CN

    • Outra duvida amigo. Rastreando o mesmo codigo RA396206829CN, consta que ainda está no status Recebido/Brasil. Enquanto que no site dos correios esse status ja foi atualizado. Como o WS usa o site dos correios, não deveria estar obendo os estados atualizados?

      []’s

  13. Blz, o status agora está ok. Não se viu a minha duvida anterior, mas vai la: Com esse mesmo ID, o primeiro status no site dos correios informa que foi postado na China, enquando que o WS não retorna nenhuma informação de localidade. Viu isso aí? []’s

  14. Olá amigo. Mais uma compra que realizei e não foi atualizado. No sites dos correios ja consta como entregue, mas no WS não.
    http://services.encomendaz.net/tracking.json?id=RA874960347BR

  15. Muito boa a iniciativa!
    Uma sugestão que seria bom, não sei se é viável, ou ideal para todos é permitir obter só os últimos N registros, mesmo sem saber a quantidade total de registros, por exemplo, tenho a necessidade de saber somente o último status (se foi entregue ou ainda não) e do jeito que está sou obrigado a obter todos os registros, e usando LINQ navegar até o último. Economizaria muita banda e processamento, se pudesse já ir direto pro último.

  16. 24 Fernando Mussio

    Show de bola, parabéns! Obrigado por compartilhar!!

  17. 25 Felipe Guerra

    Bela iniciativa, caso você tire o serviço do ar, vai fazer um post avisando?

    abraço

  18. Olá, ótima API.
    Mas uma GRANDE dúvida, existe um limite de consumo?

    obrigado!

  19. 27 Eduardo Mendonça

    Parabéns pelo projeto! Você já tentou fazer algo para processos dos Tribunais como o Tjba ou TRTba para pegar as movimentações dos processos?

  20. 28 ATV

    Suddenly http://services.encomendaz.net/ is down, any alternatives?


  1. 1 Objective-C e RESTful Web Services « Cleverson Sacramento
  2. 2 EncomendaZ na App Store « Cleverson Sacramento
  3. 3 Objective-C e RESTful Web Services « Demoiselle Laboratory
  4. 4 EncomendaZ na App Store « Demoiselle Laboratory

E aí, o que você achou? Comenta aí...

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s