Manual de utilizao

Manual de Utilizao
Documento
Manual_GrepCep.pdf

Grep Cep

Verso
3.0

Pgina 2

Manual de Utilizao

Contedo
Descrio do Servio ....................................................................................................................4
GrepCep Web App....................................................................................................................4
GrepCep WS .............................................................................................................................4
GrepCep WS Especificao tcnica ............................................................................................5
Endereo do wsdl .....................................................................................................................5
Cdigos de retorno ...................................................................................................................5
Chamada via HTTP ....................................................................................................................5
Operaes do WebService ...........................................................................................................7
ObterEnderecoCep ...................................................................................................................7
Entrada .................................................................................................................................7
Sada .....................................................................................................................................7
Ferramenta de Cache ...................................................................................................................9
Segurana ...................................................................................................................................10
Exemplo..............................................................................................................................10
Criao de um client ...................................................................................................................11
Eclipse IDE ..............................................................................................................................11

Grep Cep

Pgina 3

Manual de Utilizao
Descrio do Servio
O Grep Cep uma aplicao dividida em duas categorias:

GrepCep Web App

Grep Cep WS

GrepCep Web App

Este o aplicativo web (http://grepcep.com) onde os usurios podem se cadastrar, adicionar
ceps inconsistentes, entre outros. O mesmo no ser tratado neste manual.

GrepCep WS
o servio (WebService) que obtm os dados do logradouro. Mais detalhes nas prximas
sees.

Grep Cep

Pgina 4

Manual de Utilizao
GrepCep WS Especificao tcnica
Endereo do wsdl
Ao se cadastrar no GrepCep, voc recebe um email com o wsdl de nossos WebService em
anexo. Porm, como estamos sempre evoluindo, melhorando e aprimorando nossos servios,
o wsdl original enviado poder sofre atualizaes. Para isto, basta baixar novamente o mesmo
pelo endereo:
http://webservice.grepcep.com/GrepCepWS/services/GrepCep?wsdl
Importante: A url de chamada ao WebService do GrepCep ser:
http://webservice.grepcep.com/ {conforme contido no wsdl}
Exemplo:
http://webservice.grepcep.com/GrepCepWS/services/GrepCep.GrepCepHttpSoap12Endpoint/

Cdigos de retorno
Os cdigos de retorno do WebService so os seguintes:
Cdigo
1
-1
-400
-999
45000
45001

Descrio
Sucesso
Cep no encontrado
Parmetro no informado ou invlido.
Erro genrico na consulta do servio.
Token informado invlido.
Token informado est inativo.

Chamada via HTTP

Uma das formas de se invocar o WebService fazendo uma chamada HTTP (GET ou POST) ao
nosso servidor. Esta forma facilita o uso para usurios de outras linguagens de programao,
ou mesmo o Java.
Exemplo de utilizao:
Faa uma chamada :
http://grepcep.com/callws.do?token={seuToken}&cep={seuCep}&style={estiloDeResposta}
Onde:
Atributo
token
cep
Grep Cep

Descrio
Token utilizado para as
consultas
Cep buscado

Exemplo
201111123333ADGGG13

Obrigatrio
SIM

06753-111

SIM
Pgina 5

Manual de Utilizao
style

Estilo
XML
String
Json

Estilo das respostas (ver tabela

abaixo)

xml

NO

Descrio
O retorno ser em XML
O retorno ser em String, utilizando o pipe (|) como separador.
O retorno ser em Json

Obs: Caso o parmetro style no seja passado, o retorno padro ser em String.

Grep Cep

Pgina 6

Manual de Utilizao
Operaes do WebService
A seguir a lista de operaes do servio.

ObterEnderecoCep
Est operao obtm um endereo completo com base no CEP.
Entrada
Abaixo vemos um exemplo da entrada deste servio:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:ws="http://ws.grepcepws.com">
<soap:Header/>
<soap:Body>
<ws:obterEnderecoCep>
<ws:cep>99999-999</ws:cep>
<ws:token>2011111009999999AAAA</ws:token>
</ws:obterEnderecoCep>
</soap:Body>
</soap:Envelope>
Sada
Abaixo vemos um exemplo de sada deste servio:
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
<soapenv:Body>
<ns:obterEnderecoCepResponse xmlns:ns="http://ws.grepcepws.com">
<ns:return type="com.grepcepws.entity.ObterCepResponse"
xmlns:ax21="http://entity.grepcepws.com/xsd">
<ax21:cepList type="com.grepcepws.entity.Cep">
<ax21:bairro>Bela Vista</ax21:bairro>
<ax21:cep>01310-000</ax21:cep>
<ax21:cidade>So Paulo</ax21:cidade>
Grep Cep

Pgina 7

Manual de Utilizao
<ax21:estado>So Paulo</ax21:estado>
<ax21:id>587730</ax21:id>
<ax21:latitude>-23.56360</ax21:latitude>
<ax21:logradouro>Avenida Paulista - at 610 - lado par</ax21:logradouro>
<ax21:longitude>-46.65389</ax21:longitude>
<ax21:regiao>Sudeste</ax21:regiao>
</ax21:cepList>
<ax21:responseCode>1</ax21:responseCode>
<ax21:responseDescription>Sucesso</ax21:responseDescription>
<ax21:transactionId>20111123133D2A673EA82100022</ax21:transactionId>
</ns:return>
</ns:obterEnderecoCepResponse>
</soapenv:Body>
</soapenv:Envelope>

Grep Cep

Pgina 8

Manual de Utilizao
Ferramenta de Cache
O Web Service utiliza-se de uma ferramenta de cache, uma das mais usadas no mercado opensource, para agilizar a pesquisa e economizar a memria de seus servidores, alm de
proporcionar um requisito positivo frente aos seus concorrentes.

Grep Cep

Pgina 9

Manual de Utilizao
Segurana
O GrepCepWs possui um mecanismo de segurana baseado em token, onde as consultas
somente sero processadas se for informado um vlido.
Exemplo
Exemplo de um token para consulta no WebService:
201110178088008DAKOFCMMMDPOOOA

Grep Cep

Pgina 10

Manual de Utilizao
Criao de um client
Abaixo segue um exemplo de criao de um client em JAVA para acesso ao WebService.
Lembrando que por ser uma tecnologia de Web Services, qualquer linguagem pode acess-la,
porm, nesta verso inicial apenas a linguagem JAVA ser exemplificada.
No esquea tambm de que existem diversas maneiras de se criar um client. Abaixo ser
explicada apenas uma destas formas.

Eclipse IDE
1. Crie um novo projeto Java, e d um nome, exemplo GrepCepClient.
2. Neste projeto, clique com o boto direito, e depois v em New -> Other e na caixa de
busca, digite web service client, conforme imagem abaixo:

3. Clique em next.
4. Na tela seguinte, clique em browse para selecionar o wsdl do GrepCep:

Grep Cep

Pgina 11

Manual de Utilizao

5. Clique em OK.
6. Aps isso, no tipo de configurao, deixe apenas develop client, conforme abaixo:

Grep Cep

Pgina 12

Manual de Utilizao

7. Clique em finish.
8. Crie uma classe Java que tenha um mtodo main, e adicione o restante do cdigo
conforme abaixo:
public class Main {
public static void main(String[] args) {
try {
GrepCepSoap11BindingStub stub =
new GrepCepSoap11BindingStub(
new
URL("http://webservice.grepcep.com/GrepCepWs/services/GrepCep.Gr
epCepHttpSoap11Endpoint/"), null);
ObterCepResponse resp =
stub.obterEnderecoCep("CEP", "TOKEN");
System.out.println(resp.getResponseDescription());
}

catch (Throwable e) {
e.printStackTrace();

}
}
}

9. Pronto, s testar.
Grep Cep

Pgina 13