web service de rastreamento - correios.com.br · 101: serão retornados todos os eventos no idioma...

Web Service de Rastreamento Padrões Técnicos de Comunicação do Web Service.

AC/VICOR/DECOR

02/05/2017

Sumário

1. Introdução ................................................................................. 3

2. Web Service ............................................................................... 3

3. WSDL ....................................................................................... 3

4. XML ......................................................................................... 4

5. SOAP ....................................................................................... 4

6. Web Service de Rastreamento ......................................................... 4

7. Ferramenta de Teste - SoapUI ......................................................... 5

8. Baixando o Certificado .................................................................. 9

9. Implementação de Rastreamento ..................................................... 10

10. Conectando o Servidor da ECT ..................................................... 11

11. Regras de Formatação de Objetos ................................................. 13

12. Retorno das Informações ............................................................ 14

13. Lista de Status de eventos .......................................................... 15

14. Exemplos de Consulta ................................................................ 23

15. Segurança .............................................................................. 27

16. Suporte Técnico ...................................................................... 28

1. Introdução

Guia técnico para implementação do Rastreamento de objetos via Webservice/SOAP. Os

Correios Web Service (CWS) tem o objetivo de fornecer uma plataforma de serviços, baseados na

tecnologia de Web Services, que disponibiliza suas principais informações aos clientes do Comércio

Eletrônico Brasileiro. Estes serviços permitem que as soluções customizadas de TI dos clientes sejam

facilmente integradas aos recursos disponíveis pelos Correios com o intuito de agilizar suas

operações, simplificar seus processos e melhorar sua satisfação.

Este documento contém os padrões técnicos de comunicação dos Correios Web Services, tais

como, uma breve descrição desta tecnologia com definições do protocolo e da arquitetura utilizada,

guia de implementação para consulta de Rastreamento de objetos com exemplos.

2. Web Service

Os Web Services são componentes que permitem às aplicações enviar e receber dados em

formato XML (eXtensible Markup Language) ou JSON (JavaScript Object Notation), independente

de plataforma e de linguagem de programação, pois utilizam protocolos padrões para comunicação e

transferência de dados. Os clientes não precisam estar na mesma plataforma ou sistema operacional

do Web Service e normalmente não precisam ter nenhum conhecimento sobre a sua implementação

ou plataforma de execução, necessita conhecer apenas a interface do Web Service ou WSDL (Web

Services Description Language).

As bases para a construção de um Web Service são os padrões XML e SOAP. O transporte dos

dados é realizado normalmente via protocolo HTTP ou HTTPS para conexões seguras (o padrão não

determina o protocolo de transporte). Os dados são transferidos no formato XML e encapsulados

pelo protocolo SOAP.

A comunicação de um Web Service pode ser síncrona ou assíncrona. No modo síncrono, o

cliente, após invocar uma operação do serviço, ficará aguardando a resposta. Enquanto no modo

assíncrono, o cliente não recebe a resposta do serviço e sim uma confirmação de que a mensagem

foi recebida com sucesso e que estará em processamento. Caso seja necessário uma resposta, deve

ser disponibilizado uma outra operação para recebê-la.

3. WSDL

Web Services Description Language (WSDL) é uma especificação desenvolvida pelo W3C que

permite descrever os serviços e as mensagens do Web Service segundo um formato XML.

https://pt.wikipedia.org/wiki/XML

https://pt.wikipedia.org/wiki/SOAP

https://pt.wikipedia.org/wiki/Protocolo_de_transporte

https://pt.wikipedia.org/wiki/Protocolo

https://pt.wikipedia.org/wiki/HTTP

https://pt.wikipedia.org/wiki/HTTPS

4. XML

Extensible Markup Language (XML) é uma metalinguagem de anotação que especifica como os

dados são representados genericamente, define como e com que qualidade de serviço os dados são

transmitidos, pormenoriza como os serviços são publicados e descobertos. Os Web Services

decodificam as várias partes de XML para interagir com as aplicações.

5. SOAP

Simple Object Access Protocol (SOAP) é um protocolo utilizado para troca de informações

estruturadas em uma plataforma descentralizada e distribuída. O SOAP envia uma mensagem de

XML através de uma requisição HTTP/HTTPS (Hyper Text Transfer Protocol/Hyper Text Transfer

Protocol Secure) e recebe uma resposta, se existir, através da resposta HTTP/HTTPS. Este

protocolo baseado em XML consiste de três partes: um envelope, que define o que está na

mensagem e como processá-la, um conjunto de regras codificadas para expressar instâncias do tipos

de dados definidos na aplicação e uma convenção para representar chamadas de procedimentos e

respostas.

6. Web Service de Rastreamento

A arquitetura de software dos serviços fornecidos pelo Web Service seguem os padrões e os

protocolos de comunicação descritos acima, conforme mostra a Figura 1.

O serviço que será detalhado neste documento utiliza o protocolo HTTPS com comunicação

síncrona e o padrão de resposta encode UTF-8, que é a forma mais amplamente utilizada para

https://pt.wikipedia.org/wiki/Computa%C3%A7%C3%A3o_distribu%C3%ADda

representar texto Unicode nas páginas da Web. Este serviço fornecerá aos clientes às informações

sobre o rastreamento de objetos postados.

7. Ferramenta de Teste - SoapUI

SoapUi é uma ferramenta open source escrita em Java cuja principal função é consumir e testar

Web Services.

Com essa ferramenta é possível realizar testes funcionais, de performance, de carga e

segurança.

O SoapUi utiliza Web Service para a interação e comunicação entre aplicações diferentes através

de um tipo de schema XML chamado WSDL (Web Service Description Language).

Link para download: https://sourceforge.net/projects/soapui/

Criando um novo projeto

Para iniciar a utilização do SoapUI, você deverá criar um novo projeto. Para tal tarefa, você deverá clicar no

menu “File>New WSDL Project”, como pode ser visto na figura abaixo. O SoapUI abrirá um diálogo

solicitando o nome do novo projeto e o endereço WSDL do projeto.

Tela para criar um novo projeto de teste de web service na ferramenta SoapUI

Você precisa ter o endereço do WSDL do web servisse e no nosso caso iremos utilizar o web service dos

Correios para rastreamento de encomendas:

https://sourceforge.net/projects/soapui/

https://regifelix.files.wordpress.com/2013/01/soapui_01.jpg

http://www.correios.com.br/webservices/

http://www.correios.com.br/webservices/

http://webservice.correios.com.br/service/rastro/Rastro.wsdl

Você deve colocar o endereço do WSDL na tela New SoapUI Project conforme imagem abaixo:

Tela de criação de um novo projeto de web service

Após colocar o nome do projeto e o endereço WSDL do web service clique em OK, será feita a importação

do WSDL e irá montar o projeto de teste com todos os métodos disponíveis no web service.

Tela de importação do web service dos correios na ferramenta de testes SoapUI


Depois de montado o projeto, na lista de métodos do web service, selecione o método que deseja, no

nosso caso o método buscaEventos, clique no sinal (+) para expandir a lista e clique duas vezes no

item Request conforme imagem abaixo:

Tela para abrir o método buscaEventos

Após clicar no item Request irá abrir uma tela o SoapUI criará uma Requisição Default (Request 1) para a

operação:

Instrução XML para operação Request criado pelo SoapUI

O SoapUI irá colocar uma interrogação “?” em cada campo que deverá ser preenchido e você deve

preenchê-los com as informações conforme exemplo abaixo (o usuário e senha devem ser obtidos junto ao

gestor comercial do contrato):

Exemplo de chamada ao web service dos correios usando a ferramenta de testes SoapUI

Feito isso, clique no botão submit request no canto superior esquerdo da janela do centro onde está a

instrução request conforme imagem abaixo:

Tela de teste do web service dos correios

O SoapUI irá enviar uma requisição ao web service e o retorno será apresentado na tela direita:

Tela de envio de requisição ao webservice de cálculo de frete dos correios usando a ferramenta de testes

SoapUI

8. Baixando o Certificado

Para utilizar o endereço seguro, é necessário que seja instalado um certificado.

Faça download do nosso certificado para o servidor em que será executada a aplicação.

a- sem certificado


b- com certificado

https://webservice.correios.com.br/service/rastro/Rastro.wsdl

Exemplo usando o Firefox para baixar o cerificado - Siga os passos:

1. Acesse a sua URL via HTTPS:// e clique duas vezes sobre o cadeado que aparece no canto inferior

direito

2. Na aba Segurança, clique em Exibir Certificado

https://regifelix.files.wordpress.com/2013/01/soapui_10.jpg


https://webservice.correios.com.br/service/rastro/Rastro.wsdl

3. Clique na aba Detalhes

4. Na aba Detalhes, clique em Exportar

9. Implementação de Rastreamento

A comunicação entre clientes e servidores é feita através do SOAP (Simple Object Access

Protocol). Esse protocolo é definido em XML, sendo assim, as chamadas a procedures remotas (RPC)

são codificadas em XML para transporte das mensagens é usado o HTTP.

Cada consulta ao sistema é realizada através dos serviços SOAP que tem como característica de

funcionamento, uma requisição HTTPS de POST contendo, dentro de seu payload, chamada

envelope SOAP.

Método a ser Consumido pela requisição com certificado de autenticação:


Um envelope SOAP nada mais é que uma estrutura em XML que permite, dentro de seu

conteúdo, seja enviada informações relevantes ao seu serviço.

Serviços disponibilizados:

Serviço Descrição buscaEventos Retorna mensagem XML de retorno do rastro SRO buscaEventosLista Retorna mensagem XML de retorno do rastro SRO

10. Conectando ao Servidor da ECT

Para ter acesso a este serviço, o cliente deverá:

1. Solicitar junto à área comercial da ECT a disponibilidade do serviço juntamente com o

certificado de segurança emitido pela autoridade responsável;

2. Receber, da área comercial, a autorização para execução do aplicativo, juntamente com

uma identificação de usuário e senha de conexão;

3. Implementar, em seus sistemas, as funcionalidades de conexão com o servidor SRO. Cada

consulta ao servidor SRO deverá informar, obrigatoriamente:

Para os serviços: buscaEventos e buscaEventosLista.

Campo Descrição Valores

usuario

Identificação do cliente.

Informado pela área comercial dos Correios na ativação do serviço. Este campo diferencia letras maiúsculas e minúsculas (case-sensitive).

senha

Senha do cliente.

Informado pela área comercial dos Correios na


ativação do serviço. Este campo diferencia letras maiúsculas e minúsculas (case-sensitive).

tipo

Definição de como a lista de identificadores de objetos deverá ser interpretada pelo servidor SRO.

L: lista de objetos. O servidor fará a consulta individual de cada identificador informado; F: intervalo de objetos. O servidor fará a consulta sequencial do primeiro ao último objeto informado,

resultado

Delimitação do escopo da resposta a ser dada à consulta do rastreamento de cada objeto.

T: serão retornados todos os eventos do objeto; U: será retornado apenas o último evento do objeto.

lingua

Definição do idioma que será apresentado pelo servidor SRO.

101: Serão retornados todos os eventos no idioma Português 102: Serão retornados todos os eventos no idioma Inglês.

objetos

Lista de objetos a pesquisar.

Código do objeto formado por 2 letras, 9 números e 2 letras. Este campo diferencia letras maiúsculas e minúsculas (case-sensitive). Exemplo: AA458226057BR (sempre informar tudo em letras maiúsculas).

Exemplo de acesso ao serviço:

http://webservice.correios.com.br/service/rastro/Rastro.wsdl?"usuario=9999999999&senha=S@1234YWC5&tipo=

L&resultado=T&lingua=101&objetos=JO999999999BR

Abaixo mostra exemplos de envelopes SOAP que são estruturas XML que permite enviar

informações do serviço desejado dentro de seu conteúdo.

buscaEventos (opção 1 com apenas 1 objeto):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:res="http://resource.webservice.correios.com.br/"> <soapenv:Header/> <soapenv:Body> <res:buscaEventos> <usuario>USUARIO</usuario> <senha>SENHA</senha> <tipo>L</tipo> <resultado>T</resultado> <lingua>101</lingua> <objetos>AA598971235BR</objetos> </res:buscaEventos> </soapenv:Body> </soapenv:Envelope>

buscaEventos (opção 2 com vários objetos concatenados na tag objetos):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:res="http://resource.webservice.correios.com.br/"> <soapenv:Header/> <soapenv:Body> <res:buscaEventos> <usuario>USUARIO</usuario> <senha>SENHA</senha> <tipo>L</tipo> <resultado>T</resultado> <lingua>101</lingua> <objetos>AA598971235BRBB123456789BRCC123456789BR</objetos> </res:buscaEventos> </soapenv:Body> </soapenv:Envelope>

buscaEventosLista (método que possibilita a consulta de até 5.000 objetos): <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:res="http://resource.webservice.correios.com.br/">

<soapenv:Header/>

<soapenv:Body>

<res:buscaEventosLista>

<usuario>USUARIO</usuario>

<senha>SENHA</senha>

<tipo>L</tipo>

<resultado>T</resultado>

<lingua>101</lingua>

<objetos>AA598971235BR</objetos>

<objetos>BB123456789BR</objetos>

<objetos>CC123456789BR</objetos>

</res:buscaEventos>

</soapenv:Body>

</soapenv:Envelope>

11. Regras de Formatação de Objetos

Abaixo estão às regras para formação da lista de objetos a pesquisar:

1. Todos os identificadores objetos deverão ter o formato padrão de 13 (treze) posições. Sendo

duas letras para identificação do serviço, 8 (oito) caracteres numéricos, 1 (um) dígito

verificador e duas letras finais para identificação do país.

2. Estes identificadores são informados pelos Correios na postagem da encomenda.

Ex: SQ458226057BR

3. Não poderá haver espaços em branco, ou outros caracteres separadores, entre um objeto e

outro. Exemplo: para a pesquisa de 50 objetos será criada uma string de 650 caracteres (13 x

50).

12. Retorno das Informações

As informações serão retornadas numa mensagem XML conforme o padrão abaixo:

Elemento Pai Elemento filho

Elemento filho Descrição

versao Versão do SRO XML

qtd Quantidade de objetos consultados

objeto numero Número do objeto

sigla Sigla do objeto solicitado

nome Nome do objeto solicitado

categoria Categoria do objeto solicitado

evento tipo Tipo do evento de retorno

status Status do evento de retorno

data Data do evento

hora Hora do evento

descricao Descrição do evento

detalhe Detalhe adicional do evento

local Local onde ocorreu o evento

codigo CEP da unidade ECT

cidade Cidade onde ocorreu o evento

uf Unidade da Federação

Observações:

Os tipos e os status dos eventos são descritos no Anexo 1 deste manual, bem como sugestões de

ações a serem tomadas pelo cliente;

Os dados do recebedor só serão apresentados para os eventos de entrega (tipo=BDE status=01). Pode

haver casos em que estes dados não existam e, portanto, não serão exibidos;

Para evitar uma quantidade excessiva de pesquisa, o cliente deverá registrar, no seu banco de

dados, todos os objetos que tiveram seu rastreamento concluído.

Para isso, indicamos que todos os objetos que forem retornados com o evento tipo BDE, BDI e BDR

com status 01 ou 23 estão com o rastro concluído. Não será mais necessário enviá-los para novas

consultas.

O cliente poderá optar por gravar, na sua base de dados, todo o retorno relativo ao objeto

rastreado e/ou apenas alguns dos eventos. Por exemplo: somente a entrega.

Abaixo está um exemplo de uma mensagem XML de retorno:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

<soapenv:Body>

<ns2:buscaEventosResponse xmlns:ns2="http://resource.webservice.correios.com.br/">

<return>

<versao>2.0</versao>

<qtd>1</qtd>

<objeto>

<numero>AA598971235BR</numero>

<sigla>JF</sigla>

<nome>REMESSA ECONÔMICA C/AR DIGITAL</nome>

<categoria>REMESSA ECONÔMICA TALÃO/CARTÃO</categoria>

<evento>

<tipo>BDE</tipo>

<status>23</status>

<data>18/03/2014</data>

<hora>18:37</hora>

<descricao>Objeto devolvido ao remetente</descricao>

<detalhe/>

<local>CTCE MACEIO</local>

<codigo>57060971</codigo>

<cidade>MACEIO</cidade>

<uf>AL</uf>

</evento>

</objeto>

</return>

</ns2:buscaEventosResponse>

</soapenv:Body>

</soapenv:Envelope>

13. Lista de Status de eventos

A maior parte dos eventos é informativa e não necessita de ações específicas por parte do cliente. Os

eventos relacionados à etapa final da entrega são os mais relevantes e são destacados na lista completa de

eventos abaixo. A última coluna sugere o que apresentar ao usuário do site, seja ele destinatário ou

remetente. Estas mensagens são compatíveis com as informações exibidas no rastreamento de objetos no

site dos Correios.

Tipos Status Descrição Detalhe O que o cliente deve fazer

BDE BDI BDR

0 Objeto entregue ao destinatário

Recebido por: Finalizar a entrega. Não é mais necessário prosseguir com o acompanhamento.

BDE 1 Objeto entregue ao Recebido por: Finalizar a entrega. Não é


BDI BDR

destinatário mais necessário prosseguir com o acompanhamento.

BDE BDI BDR

2 A entrega não pode ser efetuada - Carteiro não atendido

Aguarde! Objeto estará disponível para retirada na unidade a ser informada.

Acompanhar. O interessado deverá buscar o objeto em uma Unidade dos Correios.

BDE BDI BDR

3 Remetente não retirou objeto na Unidade dos Correios

Objeto em análise de destinação

Acompanhar. O interessado não buscou o objeto na unidade dos Correios durante o período de guarda.

BDE BDI BDR

4 A entrega não pode ser efetuada - Cliente recusou- se a receber

Objeto será devolvido ao remetente

Acompanhar o retorno do objeto ao remetente.

BDE BDI BDR

5 A entrega não pode ser efetuada



BDE BDI BDR

6 A entrega não pode ser efetuada - Cliente desconhecido no local



BDE BDI BDR

7 A entrega não pode ser efetuada - Endereço incorreto

Objeto sujeito a atraso na entrega ou a devolução ao remetente

Acompanhar

BDE BDI BDR




BDE BDI BDR

9 Objeto não localizado <a href="http://www.correios.com. br/servicos/falecomoscorreios/ conteudo/eventos_sro.cfm">F avor entrar em contato com os Correios. </a>

Acionar atendimento dos Correios.

BDE BDI BDR

10 A entrega não pode ser efetuada - Cliente mudou-se



BDE BDI BDR

12 Remetente não retirou objeto na Unidade dos Correios



BDE BDI BDR




BDE BDI BDR


Será realizada nova tentativa de entrega

Acompanhar

BDE BDI BDR




BDE BDI BDR

22 Objeto devolvido aos Correios

Acompanhar

BDE BDI BDR

23 Objeto devolvido ao remetente

Recebido por: Acompanhar

BDE BDI BDR

24 Objeto disponível para retirada em Caixa Postal

Acompanhar

BDE 25 A entrega não pode ser A entrega deverá ocorrer no Acompanhar

http://www.correios.com/

BDE BDI BDR

26 Destinatário não retirou objeto na Unidade dos Correios



BDE BDI BDR

28 Objeto e/ou conteúdo avariado

<a href="http://www.correios.com. br/servicos/falecomoscorreios/


conteudo/eventos_sro.cfm">F avor entrar em contato com os Correios. </a>

BDE BDI

32 Objeto com data de entrega agendada

Acompanhar

BDR

BDE BDI BDR

33 A entrega não pode ser efetuada - Destinatário não apresentou documento



exigido

BDE BDI BDR

34 A entrega não pode ser efetuada - Logradouro com numeração irregular


Acompanhar

BDE BDI BDR

35 Coleta ou entrega de objeto não efetuada

Será realizada nova tentativa de coleta ou entrega

Acompanhar

BDE BDI BDR

36 Coleta ou entrega de objeto não efetuada



BDE BDI BDR

37 Objeto e/ou conteúdo avariado por acidente com veículo



conteudo/eventos_sro.cfm">F avor entrar em contato com os Correios. </a>

BDE BDI BDR

38 Objeto endereçado à empresa falida

Objeto será encaminhado para entrega ao administrador judicial

Acompanhar

BDE BDI BDR

40 A importação do objeto/conteúdo não foi autorizada pelos órgãos



fiscalizadores

BDE BDI

41 A entrega do objeto está condicionada à composição

Acompanhar

BDR do lote

BDE BDI BDR

42 Lote de objetos incompleto Objeto será devolvido ao remetente


BDE BDI BDR

43 Objeto apreendido por órgão de fiscalização ou outro órgão anuente



conteudo/eventos_sro.cfm">F avor entrar em contato com os Correios.</a>

BDE BDI BDR

45 Objeto recebido na unidade de distribuição

Entrega prevista para o próximo dia útil

Acompanhar

BDE 46 Tentativa de entrega não Entrega prevista para o Acompanhar


BDI BDR

efetuada - Empresa sem expediente

próximo dia útil





BDI BDR

efetuada próximo dia útil

BDE BDI BDR

47 Saída para entrega cancelada

Será efetuado novo lançamento para entrega

Acompanhar

BDE BDI BDR

48 Retirada em Unidade dos Correios não autorizada pelo remetente



BDE BDI BDR

49 As dimensões do objeto impossibilitam o tratamento e a entrega



BDE BDI BDR

50 Objeto roubado <a href="http://www.correios.com. br/servicos/falecomoscorreios/



BDE BDI BDR




BDE BDI BDR




BDE BDI

53 Objeto reimpresso e reenviado

Acompanhar

BDR

BDE BDI BDR

54 Para recebimento do objeto, é necessário o pagamento do ICMS Importação

Acompanhar. O interessado deverá pagar o imposto devido para retirar o objeto em

uma Unidade dos Correios.

BDE BDI

55 Solicitada revisão do tributo estabelecido

Acompanhar

BDR

BDE BDI BDR

56 Declaração aduaneira ausente ou incorreta



BDE BDI

57 Revisão de tributo concluída

- Objeto liberado

Acompanhar

BDR

BDE BDI BDR

58 Revisão de tributo concluída - Tributo alterado

O valor do tributo pode ter aumentado ou diminuído

Acompanhar

BDE BDI BDR

59 Revisão de tributo concluída - Tributo mantido

Poderá haver incidência de juros e multa.

Acompanhar

BDE BDI BDR

66 Área com distribuição sujeita a prazo diferenciado

Restrição de entrega domiciliar temporária

Acompanhar

BDE BDI

69 Objeto com atraso na entrega

Acompanhar





BDR BDE BDI BDR

80 Objeto Extraviado Acionar a CAC dos Correios

BLQ 1 Entrega de objeto bloqueada a pedido do remetente


Acompanhar

CD 0 Objeto recebido na Unidade dos Correios

Acompanhar


Acompanhar


Acompanhar


Acompanhar

CMT 0 Objeto recebido na Unidade dos Correios

Acompanhar

CO 1 Objeto coletado Acompanhar

CUN 0 Objeto recebido na Unidade dos Correios

Acompanhar

CUN 1 Objeto recebido na Unidade dos Correios

Acompanhar

DO 0 Objeto encaminhado para <nome da cidade> Acompanhar



EST 1 Favor desconsiderar a informação anterior

Acompanhar


Acompanhar


Acompanhar


Acompanhar


Acompanhar


Acompanhar


Acompanhar

FC 1 Objeto será devolvido por solicitação do remetente


FC 2 Objeto com data de entrega agendada

Acompanhar

FC 3 Objeto mal encaminhado Encaminhamento a ser corrigido.

Acompanhar

FC 4 A entrega não pode ser efetuada - Endereço incorreto


Acompanhar

FC 5 Objeto devolvido aos Correios

Acompanhar

FC 7 A entrega não pode ser efetuada - Empresa sem expediente

A entrega deverá ocorrer no próximo dia útil

Acompanhar

IDC 2 Objeto não localizado Houve indenização dos valores correspondentes

Acompanhar

IDC 3 Objeto não localizado Houve indenização dos Acompanhar valores correspondentes

IDC 4 Objeto não localizado Houve indenização dos Acompanhar

valores correspondentes


IDC 6 Objeto não localizado Houve indenização dos Acompanhar

valores correspondentes


LDE 9 Objeto saiu para entrega ao remetente

Acompanhar

LDI 0 Objeto aguardando retirada no endereço indicado

Endereço: Acompanhar. O interessado deverá buscar o objeto em





LDI 2 Objeto disponível para retirada em Caixa Postal

Acompanhar. O interessado deverá buscar o objeto em








OEC 0 Objeto saiu para entrega ao destinatário

Acompanhar. O interessado deverá buscar o objeto em


PAR 15 Objeto recebido em <destino>

Acompanhar

PAR 16 Objeto recebido no Brasil Objeto sujeito à fiscalização e Acompanhar

atraso na entrega

PAR 17 Objeto liberado pela alfândega

Acompanhar

PAR 18 Objeto recebido na unidade de exportação

Acompanhar

PMT 1 Objeto encaminhado para <nome da cidade> Acompanhar

PO 0 Objeto postado Acompanhar

PO 1 Objeto postado Acompanhar

PO 9 Objeto postado após o horário limite da agência

Objeto sujeito a encaminhamento no próximo

Acompanhar

dia útil

RO 0 Objeto encaminhado para <nome da cidade> Acompanhar

RO 1 Objeto encaminhado para <nome da cidade> Acompanhar

TRI 0 Objeto encaminhado para <nome da cidade> Acompanhar


IDC 1 Objeto não localizado Houve indenização dos valores correspondentes

Acompanhar

Os tipos dos eventos correspondem a mecanismos de controle interno dos Correios, sendo desnecessário ao

cliente o entendimento de seus detalhes:

Tipos Significado

BDE Baixa de distribuição externa

BDI Baixa de distribuição interna

BDR Baixa corretiva

BLQ Bloqueio de objetos

CAR Conferência de lista de registro

CD Conferência de nota de despacho

CMT Chegada de um meio de transporte

CO Coleta de objetos

CUN Conferência de lista de registro

DO Expedição de nota de despacho

EST Estorno

FC Função complementar

IDC Indenização de objetos

LDI Lista de distribuição interna

LDE Lista de distribuição externa

OEC Lista de Objetos Entregues ao Carteiro

PAR Conferência Unidade Internacional

PMT Partida Meio de Transporte

PO Postagem (exceção)

RO Expedição de Lista de Registro

TRI Triagem

14. Exemplos de Consulta

Exemplo em JAVA

O método a ser testado é o buscaEventos para isso enviaremos a seguinte mensagem

SOAP.

Mensagem SOAP:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:res="http://resource.webservice.correios.com.br/">

<soapenv:Header/>

<soapenv:Body>

<res:buscaEventos>

<usuario>USUARIO</usuario>

<senha>SENHA</senha>

<tipo>L</tipo>

<resultado>T</resultado>

<lingua>101</lingua>

<objetos>AA598971235BR</objetos>

</res:buscaEventos>

</soapenv:Body>

</soapenv:Envelope>

Observações sobre a solicitação SOAP:

Em <SOAP-ENV:Envelope>, SOAP-ENV é o nome de um namespace e Envelope é o

nome do elemento XML.

O estilo de codificação dos tipos de dados (regras para codificar tipos da dados) para

uma mensagem SOAP é estabelecido via o atributo SOAP-ENV encodingStyle.

Para usar a codificação SOAP 1.1, deves-se usar:

SOAP-ENV : encodingStyle = ”http://schemas.xmlsoap.org/soap/encoding”. Para usar

as regras de codificação SOAP 1.2 deve-se usar o valor de atributo:

http://www.w3.org/2001/09/soap-encoding.

Não indico consumir um serviço desta forma, a melhor forma sempre será gerar os

stubs do lado cliente, porém podemos também consumir um serviço desta maneira,

realizo a implementação de forma simples passando a requisição dentro de uma

String mas também podemos montar essa entrada dentro do próprio código com

XStream nada nos impede de criar e implementar códigos de modo genérico para que

atendam nossas necessidades.

Requisição SOAP:

import java.io.BufferedReader; import java.io.IOException;

import java.io.InputStreamReader;

import java.io.OutputStreamWriter; import java.net.URL;

import java.net.URLConnection;

public class RequisicaoSoap

{

public static void main(String[] args)

{

try {

String msgRetorno = "";

// Definir a URL Do Serviço sem a ?WSDL no fim

URL url = new URL("http://localhost:8080/WsServidor"); URLConnection conn = url.openConnection();

// Define que a Conexão terá uma saída/retorno conn.setDoOutput(true);

// Método a ser Consumido pela requisição conn.setRequestProperty("SOAPAction",

"http://webservice.correios.com.br/service/rastro/Rastro.wsdl");

// Propriedades da Mensagem SOAP conn.setRequestProperty("Type","Request-Response");

conn.setRequestProperty("Content-Type", "text/xml;charset=UTF-8"); conn.setRequestProperty("Accept-Encoding","gzip,deflate"); conn.setRequestProperty("User-Agent","Jakarta Commons-HttpClient/3.1"); // Canal de Saída da Requisição

OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());

// Mensagem no Formato SOAP String xml = " < soapenv: Envelope xmlns: soapenv = "http://schemas.xmlsoap.org/soap/envelope/"

xmlns: res = "http://resource.webservice.correios.com.br/" > < soapenv: Header / > < soapenv: Body > < res: buscaEventos >

< usuario > ECT < /usuario> <senha>SRO</senha > < tipo > L < /tipo>

<resultado>T</resultado > < lingua > 101 < /lingua>

<objetos>JF598971235BR</objetos > < /res:buscaEventos> </soapenv: Body > < /soapenv:Envelope>

";

wr.write(xml); wr.flush();

System.out.println("Requisição >> "+conn.getOutputStream());

/ / Leitura da Resposta do Serviço BufferedReader rd = new BufferedReader(new

InputStreamReader(conn.getInputStream()));

// Leituras das Linhas da Resposta while (rd.ready()){ msgRetorno += rd.readLine();

}

wr.close();

rd.close();

conn.getInputStream().close();

System.out.println("Resposta >> " + msgRetorno);

} catch (IOException e)

{

e.printStackTrace(); }

finally

{

System.out.println("Fim");

}

} }

Resposta do serviço:

<soapenv:Envelope

xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

<soapenv:Body>

<ns2:buscaEventosResponse

xmlns:ns2="http://resource.webservice.correios.com.br/">

<return>

<versao>2.0</versao>

<qtd>1</qtd>

<objeto>

<numero> AA598971235BR</numero>

<sigla>JF</sigla>

<nome>REMESSA ECONÔMICA </nome>

<categoria>REMESSA TALÃO/CARTÃO</categoria>

<evento>

<tipo>BDE</tipo>

<status>23</status>

<data>18/03/2014</data>

<hora>18:37</hora>

<descricao>Objeto devolvido ao remetente</descricao>

<detalhe/>

<local>CTCE MACEIO</local>

<codigo>57060971</codigo>

<cidade>MACEIO </cidade>

<uf>AL</uf>

</evento>

</objeto>

</return>

</ns2:buscaEventosResponse>

</soapenv:Body>

</soapenv:Envelope>

As duas ações de SOAP (request e response), conectando ao Serviço de Tempo do

provedor de serviços Xmethods, têm elementos importantes a notar.

A ação Request inclui um único elemento Envelope que é obrigatório, o qual inclui

um elemento Body, também obrigatório.

Um total de quatro namespaces são definidos. Os namespaces são usados para não

permitir ambiguidades de elementos XML e seus atributos, e frequentemente são

usados para referenciar esquemas externos. Na ação do SOAP request, usa-se

namespaces com o Envelope SOAP:

xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”

Para a codificação de dados via XML Schemas usa-se o namespaces

xmlns:xsi=”http://www.w3.org/2001/X MLSchema-instance”

xmlns:xsd=http://www.w3.org/2001/XMLSchema

E mais: identificadores da aplicação específicos de Xmethods:

urn:xmethods-Temperature

Isto faz com que a aplicação tenha modularidade, enquanto também provê

flexibilidade para mudanças futuras às aplicações.

O elemento Body encapsula o “payload” da mensagem SOAP. Neste ponto, o único

elemento é getTemp, o qual é atrelado ao namespace Xmethods e corresponde ao

nome do método remoto a ser invocado. Cada parâmetro no método aparece como

um sub-elemento.

A resposta SOAP inclui os elementos Envelope e Body e os mesmos quatro

namespaces XML. Entretanto, o elemento Body inclui um único elemento

getTempResponse, correspondendo a requisição inicial. O elemento de resposta

inclui um único elemento de retorno, indicando um tipo de dado xsd:float.

Header

O elemento Header é parte opcional de uma mensagem SOAP, que oferece uma

estrutura flexível para especificar requisitos adicionais no nível da aplicação.

Por exemplo, o elemento Header pode ser usado para especificar uma assinatura

digital para serviços protegidos por senhas; da mesma forma ele pode ser usado para

especificar um número de conta para serviços SOAP que são pagos por uso.

Muitos serviços SOAP não utilizam o elemento Header, mas a estrutura Header pode

prover um mecanismo aberto para autenticação, gerenciamento de transação e

autorização de pagamento.

Os details do elemento Header são finalizados abertos, provendo assim, flexibilidade

máxima para desenvolvedores de aplicação.

O protocolo SOAP especifica dois atributos para Header:

Actor Attribute

Define um message path como uma lista de sites de serviço SOAP. Cada destes sites

intermediários podem realizar algum processamento e então enviar adiante a

mensagem ao próximo site na cadeia. Por estabelecer o atributo Actor, o cliente

pode especificar o destinatário (o recipiente) do header.

MustUnderstand attribute

Indica se um elemento Header é opcional ou obrigatório. Se estabelecido a true, o

destinatário (recipiente) deve entender e processar o atributo Header de acordo com

a sua semântica definida, ou retornar uma falha.

Um exemplo Header é mostrado a seguir:

<SOAP-ENV : Header>

<ns1 : PaymentAccount xmlns:ns1=“ urn:ecerami” SOAP-ENV: mustUnderstand=“

true”>

orsenigo473

</ns1:PaymentAccount>

</SOAP-ENV : Header>

Fault

No caso de um evento-erro, o elemento Body incluirá um elemento Fault.

No que segue é apresentado um exemplo prevendo falhas (Fault). Neste exemplo, o

cliente requisita um método chamado ValidaSRO, mas o serviço não suporta tal

método. Isto representa um erro de requisição do cliente e o servidor retorna a

seguinte resposta SOAP:

<?xml version=’1.0’ encoding=’UTF-8’ ?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”

xmlns:xsi=”http://www.w3.org/1999/X MLSchema-instance” xmlns:xsd=”http://www.w3.org/1999/XMLSchema”>

<SOAP-ENV:Body>

<SOAP-ENV : Fault>

<faultcode xsi:type=“ xsd:string”>

SOAP-ENV:Client

</faultcode>

<faultstring xsi:type=“ xsd:string”>

Failed to locate method (ValidaSRO) in class (examplesCreditCard) at /usr/local/ActivePerl-5.6/lib/

site_perl/5.6.0/SOAP/Lite.pm line 1555.

</faultstring>

</SOAP-ENV:Fault>

</SOAP-ENV:Body>

</SOAP-ENV: Envelope>

15. Segurança

Mudança para HTTP para HTTPS:

O protocolo de transferência de hipertexto (HTTP – HyperText Transfer Protocol) é

o protocolo padrão para a Web. Através dele, os navegadores requisitam as

páginas da Web e as recebem. Dessa forma, o HTTP define, entre outras

formalidades, como são requisitadas as páginas da Web, como são enviados os

dados que o usuário insere em formulários e como o servidor envia mensagens de

erro para o navegador do usuário. No entanto, como o HTTP é um protocolo

baseado em texto, ou seja, toda a informação transmitida está em texto, os dados

do usuário e do servidor podem ser interceptados ou alterados no meio do

caminho.

Nesse contexto, um usuário na rede pode interceptar os seus dados e lê-los ou,

pior, alterar a página que você recebe ou a informação que envia para o servidor.

De fato, problemas mais graves e imediatos podem acontecer com transações

financeiras, como é o caso de uma transferência bancária. Se o site do banco fosse

com HTTP e um usuário mal-intencionado desejasse alterar uma ordem de

transferência para depositar o dinheiro na conta dele, esse usuário poderia fazer

tranquilamente, pois não há nenhum mecanismo de segurança no protocolo HTTP.

Com o uso do HTTPS, que é o HTTP seguro, adiciona-se alguns princípios de

segurança, como confidencialidade, integridade e autenticação. Por

confidencialidade, entende-se que a mensagem só é lida pelo destinatário real da

mensagem. A integridade representa que a mensagem não foi alterada e o

princípio da autenticação prova que o servidor é realmente quem diz ser. Nesse

artigo, apresenta-se, portanto, os mecanismos utilizados pelo HTTPS para atingir

esses três princípios básicos.

16. Suporte Técnico

Em caso de dúvida, favor contatar o suporte por meio da caixa postal:

[email protected]

mailto:[email protected]

web service de rastreamento - correios.com.br · 101: serão retornados todos os eventos no idioma...

Documents