Manual de Integrração Tecnologia: WebSerrvices SO OAP XML Áreea: CDC Produto: Ad dministraação Verrsão: 1.0 Auttor: Angeelo Beste etti Junior Con nteúdo Introd dução ......................................................................................................................................... 3 Consiiderações Iniciais ...................................................................................................................... 4 Privacidade ........................................................................................................................................ 5 WebSServices SOA AP/XML .................................................................................................................. 6 Modeelo Operacio onal ......................................................................................................................... 7 WebSServices EndPoints .................................................................................................................... 8 Saldo o ‐ Requisição o SOAP/XMLL 1.2 .................................................................................................... 9 Saldo o ‐ Resposta SOAP/XML 1 1.2 ..................................................................................................... 10 Estrutura de Dado os: PessoaFísicaEstendidda .................................................................................. 11 ML 1.2 ............................................................................................... 12 Extrato ‐ Requisiçção SOAP/XM Extrato ‐ Resposta SOAP/XMLL 1.2 .................................................................................................. 13 os: Extrato ........................................................................................................... 14 Estrutura de Dado oníveis .................................................................................................................. 15 Transsações Dispo Arquiitetura de Co omunicação ......................................................................................................... 16 Literaatura sobre W WebServicess ........................................................................................................ 17 Ferraamentas paraa WebService es ..................................................................................................... 18 odução Intro Este d documento ttem por obje etivo a defin ição das especificações e e critérios té cnicos necesssários para integração entre os sisttemas de infformações da as empresas e o Portal do SOAW WebServicess. Este d documento éé especifico para a trans ações de “Sa aldo” e “Extrrato” Consideraçõe es Iniciais Para um bom enttendimento d deste manuaal é requerid da alguma experiência em m desen nvolvimento o de aplicações Web. Connceitos de prrotocolos, tra ansações, coonexões de dados podem ou serão aabordadas neste documeento. Privacidade As infformações contidas nessse documentto, incluindo as URLs e ou utras referênncias de web bsite, são p passíveis de m mudança sem m aviso prévvio. A menos que haja nota específicaa, as compan nhias de exxemplo, orgaanizações, prrodutos, nom mes de domín nio, endereçços de e‐maill, logos, pesssoas, lugares e eventoss são fictícioss e não têm nnenhuma associação com m alguma am mbiente real. Estar de acordo ccom todas ass leis aplicáveeis de copyright é de resp ponsabilidadde do usuário o. Não limitando os direitos sob b o copyright,, nenhuma p parte deste d documento ppode ser repro oduzida, arm mazenada, reccuperada atrravés de sistemas de leitura, transmiitida por qua alquer formaa ou por quaalquer meio (eletrônico, mecânico, fo otocópia, gra avação ou ouutros), ou para qualq quer propósito sem a exp pressa permiissão por esccrito da i‐Stre eam Realtim me Business. A i‐Sttream Realtime Businesss pode ter paatentes, marrcas, direitoss autorais ou outros direiitos de prropriedade in ntelectual em m relação aoo objeto princcipal deste d documento. EExceto caso expreessamente descrito em q qualquer term mo de licençça de uso da i‐Stream Reaaltime Busin ness, o forn necimento d deste documento não lhee oferece nen nhuma licença sobre esssas patentes,, marcas, direitos aautorais, ou outra propri edade intele ectual. Web bServices SOAP/XM ML Websservice é um ma solução uttilizada na inttegração de sistemas e n na comunica ção entre aplicaações diferen ntes. Com essta tecnologiia é possível que novas a aplicações poossam interagir com aaquelas que já existem e e que sistemaas desenvolvvidos em plattaformas differentes seja am comp patíveis. Os W Webservices são componnentes que p permitem às aplicações eenviar e receber dados em formatto XML. Cada a aplicação ppode ter a sua própria "lin nguagem", qque é traduziida al, o formatoo XML. para uma linguaggem universa Para as empresass, os Webservices podem m trazer agilid dade para oss processos ee eficiência n na comu unicação entre cadeias de produção oou de logística. Toda e qualquer com municação en ntre sistem mas passa a ser dinâmica a e principalm mente segurra, pois não h há intervençãão humana. As basess para a consstrução de um Webservicce são os padrões XML e e SOAP. O traansporte doss dados é realizado o normalmen nte via protoocolo HTTP (o o padrão não o determina o protocolo de transsporte). Os dados são transferidos noo formato XM ML, encapsulados pelo prrotocolo SOA AP. Uma vantagem a destacar é q que no pontoo de venda n não é necessário instalar nenhum softw ware para reaalizar a comu unicação (au torizadores, por exemplo o), pois, a auutomação comeercial acessa diretamente e os nossos sservidores. O quee é WSDL Web Service Definition Langu uage define uum sistema p para a descrição de serviçços. Através dela, ernos, ou inteerfaces que são oferecidos por uma ddeterminada a descrrevemos os sserviços exte aplicaação, indepeendente de sua plataform ma ou linguagem de prog gramação. O seu principa al objettivo é descrever as interffaces apresenntadas e apo ontar a localização dos seeus serviços. Por ser um documentto XML, sua leitura se to rna fácil e accessível. Mod delo Operracional Nosso o portal conssiste em um hub de servviços próprios e agregado os que disponnibilizam para sua infraeestrutura de informações a maior ga ma de soluções em diversas áreas. Áreass atendidas: Informações financeiras Serasa Exxperian CDC ‐ Con nfirmação de e Dados Cadaastrais Sintegra Imposto d de Renda CEP Boletos B Bancários Geo Inforrmações Cotaçõess de Moedas Telefoniaa Web bServices EndPoints Endp point (URL) d de Produção:: http:///www.soaw webservices.com.br/webbservices/pro oducao/sws//administracaao.asmx WSDL de Produçãão: http:///www.soaw webservices.com.br/webbservices/pro oducao/sws//administracaao.asmx?WSSDL Sald do ‐ Requisição SOA AP/XML 1..2 POST T /webserv vices/prod ducao/sws/ /administr racao.asmx x HTTP/1.1 1 Host t: www.soa awebservic ces.com.br r Cont tent-Type: applicat tion/soap+ +xml; char rset=utf-8 8 Cont tent-Lengt th: length h <?xm ml version n="1.0" en ncoding="u utf-8"?> <soa ap12:Envel lope xmlns s:xsi="htt tp://www.w w3.org/200 01/XMLSche ema-instan nce" xmln ns:xsd="ht ttp://www.w3.org/20 001/XMLSch hema" xmln ns:soap12= ="http://w www.w3.org g/2003/05/ /soap-enve elope"> <s soap12:Bod dy> <Saldo xm mlns="SOAW WebService es"> <Creden nciais> <Emai il>string< </Email> <Senh ha>string< </Senha> </Crede enciais> </Saldo> </ /soap12:Bo ody> </so oap12:Enve elope> Sald do ‐ Respo osta SOAP P/XML 1.2 HTTP P/1.1 200 OK Cont tent-Type: applicat tion/soap+ +xml; char rset=utf-8 8 Cont tent-Lengt th: length h <?xm ml version n="1.0" en ncoding="u utf-8"?> <soa ap12:Envel lope xmlns s:xsi="htt tp://www.w w3.org/200 01/XMLSche ema-instan nce" xmln ns:xsd="ht ttp://www.w3.org/20 001/XMLSch hema" xmln ns:soap12= ="http://w www.w3.org g/2003/05/ /soap-enve elope"> <s soap12:Bod dy> <SaldoRes sponse xml lns="SOAWe ebServices s"> <SaldoR Result> <Sald do>Decimal l</Saldo> <Mens sagem>stri ing</Mensa agem> <Stat tus>boolea an</Status s> </Saldo oResult> </SaldoRe esponse> </ /soap12:Bo ody> </so oap12:Enve elope> Estrutura de D Dados: Sa aldo Estru utura de Dad dos Item 1 2 3 Tipo Decimal Nome N Saldo Varchar(max) Boolean Mensagem M Status Descrição D Saldo atual de s S seu contrato. Esste campo é formatado com f 4 casas decimaais. Mensagem do S M Sistema para a transação Status da Trans S acao ATEN NÇÃO: Como o informado acima no ca ampo de núm mero 3, o campo status rretorna verddadeiro (true) no caso da transação o ser realizad da com sucessso, caso con ntrário irá re etornar comoo Falso (false e). O Staatus de Falso o normalmen nte é retornaado em caso de falhas de comunicaçãão, dígitos verificadores erraados, saldo in nsuficiente ppara contas P Pré‐Pagas etc etc. Extrrato ‐ Requisição SO OAP/XML 1.2 POST T /webserv vices/prod ducao/sws/ /administr racao.asmx x HTTP/1.1 1 Host t: www.soa awebservic ces.com.br r Cont tent-Type: applicat tion/soap+ +xml; char rset=utf-8 8 Cont tent-Lengt th: length h <?xm ml version n="1.0" en ncoding="u utf-8"?> <soa ap12:Envel lope xmlns s:xsi="htt tp://www.w w3.org/200 01/XMLSche ema-instan nce" xmln ns:xsd="ht ttp://www.w3.org/20 001/XMLSch hema" xmln ns:soap12= ="http://w www.w3.org g/2003/05/ /soap-enve elope"> <s soap12:Bod dy> <Extrato xmlns="SO OAWebServi ices"> <Creden nciais> <Emai il>string< </Email> <Senh ha>string< </Senha> </Crede enciais> <Mes>st tring</Mes s> <Ano>st tring</Ano o> </Extrato o> </ /soap12:Bo ody> </so oap12:Enve elope> Extrrato ‐ Resp posta SOA AP/XML 1.2 HTTP P/1.1 200 OK Cont tent-Type: applicat tion/soap+ +xml; char rset=utf-8 8 Cont tent-Lengt th: length h <?xm ml version n="1.0" en ncoding="u utf-8"?> <soa ap12:Envel lope xmlns s:xsi="htt tp://www.w w3.org/200 01/XMLSche ema-instan nce" xmln ns:xsd="ht ttp://www.w3.org/20 001/XMLSch hema" xmln ns:soap12= ="http://w www.w3.org g/2003/05/ /soap-enve elope"> <s soap12:Bod dy> <ExtratoR Response xmlns="SOA x AWebServic ces"> <Extrat toResult> <Prod dutos> <Pr roduto> < <Produto>s string</Pr roduto> < <Mes>strin ng</Mes> < <Ano>strin ng</Ano> < <Quantidad de>int</Qu uantidade> > < <Consumo>d decimal</C Consumo> </P Produto> <Pr roduto> < <Produto>s string</Pr roduto> < <Mes>strin ng</Mes> < <Ano>strin ng</Ano> < <Quantidad de>int</Qu uantidade> > < <Consumo>d decimal</C Consumo> </P Produto> </Pro odutos> <Sald do>decimal l</Saldo> <Mens sagem>stri ing</Mensa agem> <Stat tus>boolea an</Status s> </Extra atoResult> > </Extrato oResponse> > </ /soap12:Bo ody> </so oap12:Enve elope> Estrutura de D Dados: Exxtrato Estru utura de Dad dos Item 1 2 3 4 5 6 7 Tipo Node Node Varchar(100 0) Varchar(2) Varchar(4) Integer Decimal Nome N Produtos P Produto P Produto P Mes M Ano A Quantidade Q Consumo C 8 Decimal Saldo 9 10 Varchar(max) Boolean Mensagem M Status Descrição D Node XML com N lista de Produttos consumidoss Node XML com N Produto consuumido Nome do Produ N uto Mês do Comsum M mo Ano do Consum A mo Quantidade de Q transações connsumidas Valor Total do a V acumulo das faiixas de consum mo totalizando em t valores reais o o consumo no periodo. Este ca p ampo é formataado com 4 casa as decimais. d Saldo atual do c S contrato. Este ccampo é formatado com 4 casas dec c cimais. Mensagem do S M Sistema para a transação Status da Trans S acao ATEN NÇÃO: Como o informado acima no ca ampo de núm mero 10, o campo statuss retorna verrdadeiro (true) no caso da transação o ser realizad da com sucessso, caso con ntrário irá re etornar comoo Falso (false e). O Staatus de Falso o normalmen nte é retornaado em caso de falhas de comunicaçãão, dígitos verificadores erraados, saldo in nsuficiente ppara contas P Pré‐Pagas etc etc. Tran nsações D Disponíveiss Ambiiente de Pro odução: Extrato Consulta Extrato de su ua Conta Saldo Consulta Saldo de sua a Conta Arqu uitetura d de Comunicação Um eexemplo de p preenchimen nto em ASP..NET (VB) pa ara a transaçção de “Saldoo” abaixo: ' Lem mbre‐se de importar a “Service R Reference” e usar o n nome “svcSW S” Publi ic Sub Cons sultaSaldo() ' Declar ra o Servico o que vai s ser usado Dim oWeb bServices A As New svcSW WS.Administ tracao ' Declar ra o Objeto o que contem m as creden nciais de A Acesso Dim Cred denciais As New svcSWS S.Credencia ais ' Declar ra o Objeto o que ira re etornar os dados, not tem que comoo o ' objeto o de servico o tem o nom me de Saldo o e o objeto de retornno tambem ' se cha ama Saldo o Visual Stu udio altera a o nome para Saldo1 Dim Ret torno As New svcSWS.Sa aldo ' Preen nche com sua credencia ais o objet to "Credenc ciais" Credenc ciais.Email = "seu‐ema ail" Credenc ciais.Senha = "sua‐sen nha" Try ' Faz‐s se a chamada do Servic co passando o os parame etros crede nciais ' e o C CEP desejado o e retorna a os valore es no objeto Retorno Ret torno = oWebServices.S Saldo(Crede enciais) Catch e ex As Exception ' T Tratamento de Erro End Try y E End Sub Literratura sob bre WebServices http://im masters.com.br/autor/5755/angelo‐bestetti http://ww ww.w3schoo ols.com/SOA AP/soap_intro o.asp http://arttigos.tekever.eu/ver/?633/consumir_ _web_service es_em_php__com_nusoap/ http://ww ww.macoratti.net/09/088/ws_cwf1.httm http://ww ww.drbob42 2.com/exami nes/examin4 45.htm Ferrramentas para Web bServices SOAP P UI (Recome endado) http:///www.soap pui.org/ Micro osoft Visual Studio 2010 0 http:///www.micrrosoft.com/vvisualstudio/pt‐br/