XML WEBSERVICE APPSWS

Transcrição

1 XML WEBSERVICE APPSWS Objetivo: Fornecer acesso, aos nossos clientes, das vendas efetuadas e faturadas junto a Ancoradouro, para que possam integrar com seu Back-Office, confrontando com o que está em seu sistema ou simplesmente dando entrada nas vendas à partir da consulta ao nosso XML WebService. Somente vendas aéreas. Data: 24/11/2014 Versão 7.04r27 RUA DR. LIRÁUCIO GOMES, 55 CAMBUÍ CAMPINAS SP

2 Índice XML WEBSERVICE ANCDWS Índice Versões Introdução AppsWS Modelo Apps Sistemas 5 4. Vendas e usuário para testes Aplicação para teste Como obter seu acesso ao WebService Dúvidas, sugestões e suporte técnico FAQ Perguntas frequentes PÁGINA 2

3 1. Versões Versão Data da liberação Tarefas realizadas 7.04r24 06/11/ Separados os manuais de WebService em AncdWS, AppsWS e AgiWS. 7.04r25 22/05/ Correção do endereço HTTP edo WSDL. 7.04r26 26/09/ Corrigida URL de alteração de senha de login. 7.04r27 24/11/ Atualizados links do portal

4 2. Introdução Este é o WebService padrão do sistema de BackOffice utilizado pela Ancoradouro. Ele tem como vantagem a conexão direta ao nosso BackOffice para obter as informações. Sem intermediação do AncdWS para manter a compatibilidade com integrações antigas ou proprietárias. WebService: Padrão: Endereço HTTP: WSDL HTTP: AppsWS Apps

5 3. AppsWS Modelo Apps Sistemas XML WEBSERVICE ANCDWS Este é o modelo mais novo e o que deve, preferencialmente, ser utilizado. Ele se conecta diretamente ao BackOffice. Para o serviço AppsWS as vendas podem ser consultadas sem restrição, entretanto, utilizar um período acima de 15 dias pode ultrapassar o limite de tempo da requisição, o que é extremamente desaconselhável. Ao utilizar uma data inicial na solicitação, ele trará todas as vendas existentes (já integradas e não integradas), mas se uma data inicial não for informada serão retornadas todas as vendas no sistema que não foram retornadas antes (vendas não integradas). Métodos disponíveis: resumovendas Traz todos os bilhetes de acordo com as opções preenchidas. Existem outros métodos, mas são restritos e por isso não podem e não devem ser utilizados. Eles não terão respostas nas suas requisições a partir de um usuário de integração de agências de viagens.

6 Método: resumovendas Consulta: <resumovendas>(1) <diretorio>string(aaa)</diretorio>(1) <usuario>(1) <senha>string</senha>(1) </usuario> <dtinicial>string(ddmmyy)</dtinicial>(1) </resumovendas> DDMMYY Dia, mês e ano A Alfanumérico # - - (1) Só pode aparecer uma vez Descrição da Consulta: <resumovendas> Tag principal. <diretorio> Deve sempre ser preenchido com ANC... <usuario> Dados do usuário de integração. (Ver capítulo Como obter seu acesso ao WebService ).. < > de usuário... <senha> Senha do usuário... <dtinicial> Data inicial. Se não for preenchida trará todas as vendas ainda não retornadas (status=n) nas consultas anteriores, possivelmente ainda não integradas. Se preenchida (máximo 15 dias passados) trará todas as vendas da agência existentes do período.. Cada ponto corresponde a um nível dentro da tag raiz Resposta: <saidaresumovendas>(1) <retorno>string(xml)</retorno>(1) <mensagem>string</mensagem>(1) <horario>datahora(dd/mm/yyyy-hh:mm)</horario>(1) </saidaresumovendas> DD/MM/YYYY-HH:MM Dia, mês, ano, hora e minuto A Alfanumérico # - Número (1) Só aparecerá uma vez Descrição da Resposta: <saidaresumovendas>. <retorno> Aqui dentro será retornado outro XML, com as vendas (Ver descrição deste XML interno mais abaixo)... <mensagem> Status da consulta. Se houver erro, virá a mensagem de erro, se não virá OK... <horario> Horário da resposta da consulta.. Cada ponto corresponde a um nível dentro da tag raiz

7 Ajustes pós-importação no XML contido na tag retorno: <?xml version=\"1.0\" encoding=\"utf-8\"?><xml>< O texto do retorno vem conforme acima, pois um XML dentro do outro deve ter um tratamento diferenciado para caracteres especiais. Estes devem ser manipulados para sucesso da importação. Alguns recursos já o fazem automaticamente dependendo da plataforma utilizada. < < > > Após feito o ajuste o XML estará conforme descrito abaixo. XML contido na tag retorno: <?xml version="1.0" encoding="utf-8"?> <xml>(1+) <vendas>(1+) <venda>(0+) <status>string</status>(0-1) <codint>inteiro</codint>(0-1) <loc>string</loc>(0-1) <unidade>string(##/aaa)</unidade>(0-1) <cliente/>(0-1) <ccusto>string</ccusto>(0-1) <contato/>(0-1) <emissor>string</emissor>(0-1) <requisicao/>(0-1) <produto>string</produto>(0-1) <emissao>data(dd/mm/yyyy)</emissao>(0-1) <vencimento>data(dd/mm/yyyy)</vencimento>(0-1) <tpbil>string</tpbil>(0-1) <cia>string</cia>(0-1) <bastarif>string</bastarif>(0-1) <tourcode>string</tourcode>(0-1) <tottarifas>moeda(###.###,##)</tottarifas>(0-1) <tottaxas>moeda(###.###,##)</tottaxas>(0-1) <acrescia>moeda(###.###,##)</acrescia>(0-1) <outrosacresc>moeda(###.###,##)</outrosacresc>(0-1) <outrosdescontos>moeda(###.###,##)</outrosdescontos>(0-1) <comissao>moeda(###.###,##)</comissao>(0-1) <incentivo>moeda(###.###,##)</incentivo>(0-1) <abatimento>moeda(###.###,##)</abatimento>(0-1) <fee>moeda(###.###,##)</fee>(0-1) <du>moeda(###.###,##)</du>(0-1) <repassedu>moeda(###.###,##)</repassedu>(0-1) <cambio>moeda(#,#####)</cambio/>(0-1) <fpgto>inteiro</fpgto>(0-1) <cartao>(0-1) <bandeira>string(aaaaa)</bandeira> (0-1) <numero>string( )</numero>(0-1) <validade>data(mm/yy)</validade>(0-1) <titular>string</titular>(0-1) <parcelas>número(##)</parcelas>(0-1) <entrada>moeda(###.###,##)</entrada>(0-1) <juros>moeda(###.###,##)</juros>(0-1) <valorcartao>moeda(###.###,##)<valorcartao>(0-1) </cartao> <sinal>moeda(###.###,##)</sinal>(0-1) <saldo>moeda(###.###,##)</saldo>(0-1) <paxes>(0-1)

8 <pax>(0+) <nome>string</nome>(0-1) <tipo>string</tipo>(0-1) <tarifausd>moeda(###.###,##)</</tarifausd>(0-1) <tarifabrl>moeda(###.###,##)</</tarifabrl>(0-1) <taxa>moeda(###.###,##)</</taxa>(0-1) <bilhete>inteiro(##########)</bilhete>(0-1) <conjugados>(0-1) <conjugado>numero(##########)</conjugado>(0+) </conjugados> </pax> </paxes> <rota>(0-1) <origem>string(aaa)</origem>(0-1) <destino>string(aaa)</destino>(0-1) <rtow>string</rtow>(0-1) <trechos>(0-1) <trecho>(0+) <ciaaerea>string(aaa)</ciaaerea>(0-1) <origem>string(aaa)</origem>(0-1) <destino>string(aaa)</destino>(0-1) <numvoo>inteiro(####)</numvoo>(0-1) <classe>string<classe>(0-1) <dtsaida>data(dd/mm/yyyy)</dtsaida>(0-1) <horasaida>hora(hh:mm)</horasaida>(0-1) <dtchegada>data(dd/mm/yyyy)</dtchegada>(0-1) <horachegada>hora(hh:mm)</horachegada>(0-1) </trecho> </trechos> </rota> <observacoes>(0-1) <obsreserva>(0-1) <observacoes>string</observacoes>(0-4) </obsreserva> <obsvenda>(0-1) <observacoes>string</observacoes>(0-4) </obsvenda> </observacoes> <trfcomparativa>(0-1) <trfcheia>moeda(###.###,##)</trfcheia>(0-1) <trfsugerida>moeda(###.###,##)</trfsugerida>(0-1) <codmotivo>string</codmotivo>(0-1) <complemotivo>string</complemotivo>(0-1) </trfcomparativa> </venda> </vendas> </xml> DD/MM/YYYY Dia, mês e ano HH:MM Hora e minuto A Alfanumérico X Qualquer caractere # - Número (0-2) Poderá aparecer a quantidade de vezes mostrada, neste caso de 0 a 2 vezes (0+) Poderá aparecer mais de 1 vez, podendo não ser retornada (1+) Poderá aparecer mais de 1 vez, mas pelo menos na quantidade mostrada Descrição do XML contido na tag retorno: <xml>. <vendas> Retorna uma lista de tags venda... <venda> Cada tag vem com os dados de uma venda no sistema, com um ou mais passageiros e com um ou mais bilhetes de passagem.... <status> I=Vendas já retornadas pelo menos uma vez

9 N=Primeira vez que a venda é retornada... <codint> Id da venda em nosso sistema (também chamado de LI)... <loc> Localizador da reserva.... <unidade> O número corresponde ao escritório da Ancoradouro onde a venda foi adquirida. O código da cidade é o IATA de emissão da passagem. Escritórios: - 01 Campinas - 02 Ribeirão Preto - 03 São José dos Campos - 04 Bauru... <cliente> Sempre retornará vazia.... <ccusto> Centro de custo da agência, caso esta utilize a fatura separada por centro de custo. (Não confundir com centro de custo corporativo)... <contato/> Sempre retornará vazia... <emissor> Usuário ou funcionário da Ancoradouro que deu entrada da venda no sistema.... <requisicao/> Sempre retornará vazia.... <produto> Tipo de venda. Três valores são possíveis: EBTA, RAV ou vazio para E-TKT.... <emissao> Data de emissão da passagem.... <vencimento> Data de previsão de vencimento da fatura da venda.... <tpbil> N=Nacional R=Regional I=Internacional... <cia> Código de 2 ou 3 letras da companhia aérea.... <bastarif> Base tarifária principal da rota.... <tourcode> Código de comissionamento e desconto interno utilizado.... <tottarifas> Total das tarifas de todos os passageiros da venda. Se for internacional trará o valor em dólares, que deve ser convertido para reais pelo câmbio da tag cambio. Em reais.... <tottaxas> Total de taxas de todos os passageiros da venda. Em reais.... <acrescia> Total de taxas extras de todos os passageiros da venda. Quando tiver pagamento no cartão, a taxa DU será repetida aqui para evitar devolução duplicada. Em reais.... <outrosacresc> Total de taxas adicionais cobradas pela Ancoradouro de todos os passageiros da venda. Em reais.... <outrosdescontos> Total de descontos concedidos a todos os passageiros da venda. Em reais.... <comissao> Total de comissão de todos os passageiros da venda. Quando tiver pagamento no cartão, a taxa DU virá neste campo, deduzido o valor da taxa administrativa do cartão. Em reais.... <incentivo> Total de incentivos de todos os passageiros da venda. Em reais.... <abatimento> Total de descontos adicionais de todos os passageiros da venda. Em reais.... <fee> Total de taxas de serviços cobradas pela Ancoradouro de todos os de todos os passageiros da venda. Em reais.

10 ... <du> Taxa de repasse à terceiros de todos os passageiros da venda. Em reais.... <repassedu> Retorna o valor que será creditado em fatura referente à taxa DU, normalmente só são são devolvidas DU no cartão de crédito. Quando faturado, já são descontadas em fatura e não há o que devolver. Este é valor da DU menos a taxa administrativa do cartão. Em reais.... <cambio> Câmbio de emissão quando a venda for internacional, sempre será o câmbio para conversão de dólares para reais.... <fpgto> Forma de pagamento: 1=Faturado e 3=Cartão de crédito. Quando for múltiplas formas incluindo cartão virá como 3. Neste caso, o valor do cartão será explicitamente indicado nos dados do cartão.... <cartao> Virá vazia se não contiver pagamento no cartão..... <bandeira> Sempre retornará vazia..... <numero> Número do cartão de crédito..... <validade> Sempre retornará vazia..... <titular> Sempre retornará vazia..... <parcelas> Sempre virá 1, mesmo que pago em mais parcelas..... <entrada> Sempre retornará vazia..... <juros> Sempre retornará vazia..... <valorcartao> Valor pago através do cartão de crédito. O restante será faturado ou cash. Em reais.... <sinal> Valor pago cash pela agência. Em reais. Obs: O valor faturado sempre será: (tottarifas+tottaxas+acrescia+outrosacresc+fee+du)-(valorcartao)-(sinal)... <saldo> Valor líquido da venda. (+) Valor a ser pago pela agência. (-) Crédito a ser recebido pela agência.... <paxes> Cada passageiro virá numa tag pax..... <pax> Lista de passageiros da venda <nome> Nome do passageiro. O campo é um texto livre. Se contiver / foi digitado SOBRENOME/NOME, se não contiver / será NOME SOBRENOME. Nome e sobrenome podem ser compostos e separados por espaço ou hífen <tipo> ADT=Adulto, CHD=Criança e INF=Colo <tarifausd> Valor em dólar da tarifa do passageiro, quando internacional. Em dólares <tarifabrl> Valor em reais da tarifa do passageiro. Quando internacional, é a tarifausd convertida pelo cambio. Em reais <taxa> Taxa de embarque e penalidades do pagamento. Em reais. Acréscimos e descontos não serão discriminados por passageiro <bilhete> Número do bilhete. Será retornado um bilhete fictício para as companhias ticketless. Exemplo de companhias ticketless: AD e G3. Também será retornado um número fictício quando for uma RAV <conjugados> Lista de bilhetes conjugados. Não inclui o primeiro bilhete, mas todos os bilhetes sequenciais.

11 <conjugado> Bilhete conjugado.... <rota> Itinerário da passagem..... <origem> Cidade de origem da rota inteira. Código de 3 letras..... <destino> Cidade de origem da rota inteira. Código de 3 letras..... <rtow> OW=One Way (Somente ida) e RT=Round Trip (Ida e volta)..... <trechos> Cada trecho virá numa tag trecho <trecho> Lista de trechos da rota <ciaaerea> Código de 2 ou 3 letras da companhia aérea <origem> Cidade de origem do trecho. Código de 3 letras <destino> Cidade de origem do trecho. Código de 3 letras <numvoo> Número do voo. Desconsiderar quando Open <classe> Classe de reserva <dtsaida> Data de saída. Virá nas as 4 primeiras posições a palavra OPEN quando for Open <horasaida> Horario de saída. Desconsiderar quando Open <dtchegada> Data de chegada. Desconsiderar quando Open <horachegada> Horário de chegada. Desconsiderar quando Open.... <observacoes> Lista de observações da venda..... <obsreserva> Observações referentes à reserva. Ver detalhamento Abaixo <observacoes> Observação referente à reserva..... <obsvenda> Observações referentes à venda. Ver detalhamento Abaixo <observacoes> Observação referente à venda.... <trfcomparativa> Tarifa para efeito de comparação com a escolhida. Só haverá informações se a venda foi feita diretamente em nosso portal..... <trfcheia> Maior tarifa para o trecho. Só haverá informação se a venda foi feita diretamente em nosso portal. Em reais..... <trfsugerida> Menor tarifa disponível para o trecho. Só haverá informação se a venda foi feita diretamente em nosso portal. Em reais..... <codmotivo> Motivo da escolha da tarifa mais cara. Não é utilizado pela Ancoradouro..... <complemotivo> Motivo complementar. Não é utilizado pela Ancoradouro.. Cada ponto corresponde a um nível dentro da tag raiz; RAV Remuneração do agente de viagem Com a retirada das comissões das companhias, as agências são obrigadas a cobrar um fee (taxa de serviço). Há 3 modos de cobrança de fees: DU, RAV e TASF. Veja abaixo como o sistema trata cada uma delas: DU Vem discriminada nas tags <du/> e <repassedu/>. A tag <repassedu/> só existe quando cartão, e é a DU menos a taxa administrativa do cartão. A DU é uma cobrança da companhia ao passageiro.

12 RAV Somente são lançadas as RAVs no cartão, uma vez que a DU é uma cobrança da agência ao passageiro. O lançamento tem como objetivo apenas repassar o valor do cartão à agência, que utilizou a maquineta da Ancoradouro para a cobrança. Elas são lançadas numa venda totalmente separada da venda original, pois nem sempre o cartão da cobrança é o mesmo da venda. Vem discriminada nas tags <du/> e <repassedu/>. A tag <repassedu/> só existe quando cartão, e é a DU menos a taxa administrativa do cartão. TASF São cobrados pelo BSP utilizando as maquinetas da Ancoradouro. A Ancoradouro não utiliza TASF, por isto seus campos nem estão descritos neste manual. Detalhamento da tag observações Além das observações gerais que podem ser inseridas na venda e que são retornadas há dois tipos de observações que poderão ser de interesse da agência. AUTORIZAÇÃO DO CARTÃO DE CRÉDITO As vendas no cartão de crédito poderão vir com o código de autorização. Normalmente, as que são emitidas no portal conterão estes códigos. AUT:AUTORIZACAODOCARTAO INFORMAÇÕES REFERENTES AO CARTÃO CORPORATIVO EBTA Quaisquer dos campos de observação, seja nas tags obsreserva ou nas tags obsvenda, podem retornar um destes valores: CC:CENTRODECUSTO MAT:MATRICULA REQ:REQUISICAO DPTO:DEPARTAMENTO AUT:AUTORIZACAODOCARTAO Cada valor virá numa tag observacao diferente. Exemplo: <observacoes>dpto:vendas</observacoes> INFORMAÇÕES INSERIDAS NO PORTAL ANCORADOURO Serão retornadas 3 tags observacao sequenciais que deverão ser montadas, formando uma única linha com os valores. AGT1:EMISSOR,CLIENTE,SOLICITANTE,CENTRODECUSTO,UN.NEG, AGT2:DEPTO,PROJETO,ATIVIDADE,MOTIVO,CTA.CONT.,CLS.VALO AGT3:R,REQ,MATR,EMPENHO,EVENTO,REF1,REF2,INF.CT.,LOGIN Linha montada: EMISSOR,CLIENTE,SOLICITANTE,CENTRODECUSTO,UN.NEG,DEPTO,PROJETO,ATIVIDADE,MOTIVO,CT A.CONT.,CLS.VALOR,REQ,MATR,EMPENHO,EVENTO,REF1,REF2,INF.CONTROLE,LOGIN

13 Após montada a linha, os campos terão os seguintes significados, nesta ordem: 1º - Emissor do bilhete. Retornará o código do emissor no BackOffice da agência se este for configurado no cadastro de usuários (EMISSOR) 2º - Código do cliente da agência no seu BackOffice, configurado no cadastro do cliente (CLIENTE) 3º - Solicitante corporativo da emissão (SOLICITANTE) 4º - Centro de custo do cliente da agência (CENTRODECUSTO) 5º - Unidade de negócio (UN.NEG) 6º - Departamento (DEPTO ) 7º - Código do projeto (PROJETO) 8º - Atividade (ATIVIDADE) 9º - Motivo (MOTIVO) 10º - Conta contábil (CTA.CONT) 11º - Classe de valor (CLS.VALOR) 12º - Requisição (REQ) 13º - Matrícula (MATR) 14º - Empenho (EMPENHO) 15º - Evento (EVENTO) 16º - Código de referência (REF1) 17º - Código de referência adicional (REF2) 18º - Informação de controle (INF.CONTROLE) 19º - Login do Emissor (LOGIN) Estes códigos não têm sentido sem uma necessidade corporativa. Por isso, Caso não exista algum destes valores na venda o campo virá simplesmente vazio. Exemplo: <observacoes>agt1:100,1234,,,,,,,,,,a129, ,,,,,,</observacoes> Todos os dados couberam numa única linha, portanto não foram retornadas 3. Se ultrapassar de 3 linhas, o que não deve ocorrer, os últimos dados não serão retornados.

14 4. Vendas e usuário para testes XML WEBSERVICE ANCDWS A Ancoradouro não tem como disponibilizar um usuário para testes, visto que só existe o sistema em produção em vigor. Pedimos utilizar como data inicial para os testes apenas o dia corrente, para evitar que muitas vendas sejam retornadas desnecessariamente, a não ser que um determinado tipo de venda seja procurado. Lembramos que ao não informar uma data, todas as vendas não retornadas antes serão agora retornadas e marcadas como já retornadas, para que não sejam mais retornadas neste caso.

15 5. Aplicação para teste No nosso site é possível obter, além deste manual em formato PDF, uma aplicação de testes que pode ser rodada em qualquer máquina que possua acesso aos links: Baixar o manual em PDF: Baixar a aplicação: A aplicação de testes contém todo o código de integração em C#. Também contém uma versão compilada. Basta executar o atalho TesteAncdWS dentro da pasta Executar Teste.

16 6. Como obter seu acesso ao WebService XML WEBSERVICE ANCDWS Para o acesso à integração via XML WebService fornecida pela Ancoradouro é preciso ter um usuário e uma senha. Para solicitar um usuário com acesso ao WebService ou a regularização de um usuário existente envie um para: Help Desk help@efacilplus.com.br Importante: somente será criado um usuário para integração, uma vez que ele retornará todas as vendas. Este usuário deve ser cadastrado em todos da agência que farão a integração. Basta informar que precisa de um usuário para acesso à integração via XML WebService. Caso não seja informado um (único) específico para a integração, será criado em nome do do solicitante. Caso o usuário possua acesso ao nosso portal de vendas, ele deve evitar utilizar a mesma senha, uma vez que esta será de uso geral somente para integração de vendas BackOffice-BackOffice. A agência pode também optar por criar um específico para a integração, vinculada a outro e- mail existente. Isto evita o inconveniente de conflitar com usuário do portal e o risco de se utilizar a mesma senha.

17 7. Dúvidas, sugestões e suporte técnico XML WEBSERVICE ANCDWS Enviar para help@efacilplus.com.br Telefone: Atenção, o suporte técnico é somente para desenvolvedores. O suporte para as agências se dará pelo financeiro@efacilplus.com.br. Este suporte inclui: - Falta de vendas a serem integradas - Vendas que não são da agência aparecendo na integração - Erros nos dados de lançamento gerado. Qualquer problema técnico deverá ser feito pelo desenvolvedor, com a descrição do problema

18 8. FAQ Perguntas frequentes XML WEBSERVICE ANCDWS sistema? 1. O sistema fica com alguma sessão aberta? Como funciona o logon e o logoff do Não fica nenhuma sessão aberta. O sistema trabalha de modo off-line. Dentro do sistema o logon é efetuado, a consulta é feita, o logoff é efetuado e depois o resultado é retornado. 2. Por que algumas reservas que não possuem trechos em aberto veem com apenas um dos trechos marcado como OPEN? Ao digitar algumas vendas se coloca apenas o primeiro trecho da viagem, sem a informação do vôo e dos outros vôos. Isto é feito para agilizar o processo interno, mas com a liberação dos WebServices a necessidade do lançamento completo da venda será necessário. O agente deve entrar em contato com o departamento administrativo e solicitar a digitação correta se for muito importante a informação. Vendas que são inseridas automaticamente em nosso sistema normalmente contêm todos os dados dos vôos. dados? 3. Desenvolvo em Delphi, por que só me vem a resposta de que não estou passando os O Delphi funciona sem problemas para WebServices desenvolvidos até a versão 2003 do Visual Studio. Para versões mais novas (2005 e 2008) é necessário registrar, na seção inicialization a chamada InvRegistry.RegisterInvokeOptions(TypeInfo(ConsultaVendaSoap), iodocument);. O consultavendasoap é o serviço que será utilizado e deve estar como importado pelo Delphi. Esta informação não vale para o serviço AppsWS, que é gerado em PHP.