XML WEBSERVICE AGIWS

Transcrição

1 XML WEBSERVICE AGIWS 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. Este manual só deve ser utilizado para clientes da Agi Sistemas. Data: 24/11/2014 Versão 1.0r23 RUA DR. LIRÁUCIO GOMES, 55 CAMBUÍ CAMPINAS SP

2 Índice XML WEBSERVICE ANCDWS Índice Versões Introdução AgiWS Modelo STur AGI Sistemas 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 /01/ Criado o WebService e liberado para acesso de testes. 1.0r20 06/11/ Separados os manuais em AncdWS, AppsWS e AGIWS. 1.0r22 29/09/ Corrigida URL de testes e URLs do serviço 1.0r23 24/11/ Atualizados links e s do portal

4 2. Introdução Este WebService foi criado apenas para ser utilizado pela empresa Agi Sistemas. Não deve ser utilizado por outras empresas. Caso você não seja cliente da Agi, baixe o manual do AppsWS para efetuar uma nova conexão. WebService: Padrão: Endereço HTTP: Endereço HTTPS: WSDL HTTP: AgiWS STur

5 3. AgiWS Modelo STur AGI Sistemas XML WEBSERVICE ANCDWS Ao utilizar uma data inicial na solicitação, ele trará todas as vendas existentes, mas se uma data inicial não for informada serão retornadas todas as vendas no sistema que não foram retornadas antes. Métodos disponíveis ConsultarVenda Traz todos os bilhetes referentes a um localizador ou o bilhete especificado. ConsultarVendaXML Traz todos os bilhetes referentes a um localizador ou o bilhete especificado em formato string. ConsultarVendas Traz todos os bilhetes referentes do período especificado. O período máximo é de 15 dias. Entretanto, recomenda-se consultar apenas de um dia, pois a consulta de muitos bilhetes é mais demorada. ConsultarVendasXML Traz todos os bilhetes referentes do período especificado, mas numa string em formato XML. O período máximo é de 15 dias. Entretanto, recomenda-se consultar apenas de um dia, pois a consulta de muitos bilhetes é mais demorada.

6 Método: ConsultarVenda Consulta: <ConsultarVenda xmlns=" <dataemissao>string</dataemissao> <localizador>string</localizador> <usuario>string</usuario> <senha>string</senha> </ConsultarVenda> Tag Tamanho Formato Descrição dataemissao 10 String dd/mm/yyyy Data de emissão do bilhete ou do localizador. Se não for preenchido é considerada a data atual. localizador 0-7 String Localizador da reserva usuario String senha 6-30 String Resposta: <ConsultarVendaResponse xmlns=" <vendas> <venda> <origem>string</origem> <idvenda>string</idvenda> <tipoproduto>string</tipoproduto> <clasproduto>string</clasproduto> <idemissor>string</idemissor> <dtemissao>string</dtemissao> <idcliente>string</idcliente> <idoperador>string</idoperador> <idfornecedor>string</idfornecedor> <formrec>string</formrec> <vencrec>string</vencrec> <formpagto>string</formpagto> <vencpagto>string</vencpagto> <cartaocia>string</cartaocia> <cartaonumero>string</cartaonumero> <cartaovalidade>string</cartaovalidade> <cartaocodseguranca>string</cartaocodseguranca> <titularcartao>string</titularcartao> <movimentos> <aereorodoviario> <pax>string</pax> <tipo>string</tipo> <basetarifaria>string<basetarifaria> <tarifa>string</tarifa> <tarifacheia>string</tarifacheia> <moeda>string</moeda> <cambio>string</cambio> <datacambio>string</datacambio> <taxaembarque>string</taxaembarque> <taxaservico>string</taxaservico> <repassedu>string</repassedu> <taxacartaodu>string</taxacartaodu> <bilhetes> <bilhete>

7 <numero>string</numero> </bilhete> <bilhete>...</bilhete> </bilhetes> <comisrecforvalor>string</comisrecforvalor> <descpagclivalor>string</descpagclivalor> <observacao>string</observacao> </aereorodoviario> <trechos> <segmento> <de>string</de> <para>string</para> <datasaida>string</datasaida> <horasaida>string</horasaida> <datachegada>string</datachegada> <horachegada>string<horachegada> <ciaaerea>string</ciaaerea> <voo>string</voo> <classe>string</classe> <localizador>string</localizador> <status>string</status> </segmento> <segmento>...</segmento> </trechos> </movimentos> </venda> <venda>...</venda> <erros> <erro> <numero>int</numero> <descricao>string</descricao> <local>string</local> </erro> <erro>...</erro> <observacao>string</observacao> </erros> </vendas> </ConsultarVendaResponse> Tag Tamanho Formato Descrição vendas - - Tag principal. Não se repete. Dentro virá uma array venda venda - Array Cada localizador ou forma de pagamento vem dentro de uma venda. Se não vier esta tag foi porque deu erro. Neste caso, virá a tag erros. origem 11 String Sempre virá ANCORADOURO idvenda 1-20 String Id da reserva em nosso sistema tipoproduto - String Aereo Bilhere físico Etkt Bilhete eletrônico clasproduto - String N Nacional I - Internacional idemissor 1-10 String Código do emissor ou do digitador dtemissao 10 String dd/mm/yyyy idcliente - String Sempre virá em branco, pois não temos o código do cliente da agência. idoperador 13 String Virá sempre Consolidadora

8 idfornecedor 2-3 String Código da empresa aérea formrec 0-1 String Somente será preenchido se for cartão de crédito. 3 - Cartão de crédito vencrec - String Virá sempre vazio, pois não temos a informação de como o cliente pagou ao cliente. formpagto - String 1 - Cash/À vista 2 - Faturado Vencpagto 0 String Dia do vencimento da fatura desta venda. Será retornado sempre vazio. cartaocia - String VI Visa MC Mastercard DC Diners Club AM Amex HC Hypercard Obs: Nosso sistema não diferencia as bandeiras Mastercard ou cartões corporativos e cartões pessoas físicas. Somente será preenchido se for cartão de crédito. 3 - Cartão de crédito cartaonumero 0-20 String Número do cartão de crédito, se a venda o contiver. cartaovalidade 0,7 String MM/yyyy Somente será preenchido se for cartão de crédito. 3 - Cartão de crédito Validade do cartão de crédito, se a venda o contiver. Somente será preenchido se for cartão de crédito. 3 - Cartão de crédito cartaocodseguranca 0 String Sempre será retornado vazio. titularcartao 0-50 String Nome do titular, se a venda o contiver. Somente será preenchido se for cartão de crédito. 3 - Cartão de crédito movimentos - - Não se repete. Dentro virão vários bilhetes em tags aereorodoviario aereorodoviario - Array Cada bilhete vem dentro de uma tag aereorodoviario. Se o passageiro possuir mais de um bilhete, virão duas tags com o mesmo passageiro. pax 3-40 String Nome e sobrenome do passageiro. Exemplo: SILVA/JOAOMR ou SILVA/JOSE MR ou SILVA/J MR tipo - String ADT - Adulto CHD - Criança

9 basetarifaria 8 String tarifa 4-15 String ###.###.##0,00 tarifacheia 4-15 String ###.###.##0,00 INF Colo Tarifa em reais. XML WEBSERVICE ANCDWS Tarifa normal da rota sem desconto ou repetição da tarifa aplicada. Em reais. moeda - String Sempre será retornado R$ cambio 4-10 String Sempre será retornado 1,00. Em reais. ###.##0,00 datacambio 10 String Sempre será retornado o dia da emissão. dd/mm/yyyy taxaembarque 4-15 String Taxas de embarque e penalidade. Em reais. ###.###.##0,00 taxaservico 4-15 String ###.###.##0,00 repassedu 4-15 String ###.###.##0,00 taxacartaodu 4-15 String ###.###.##0,00 Taxa por serviços prestados pela Ancoradouro. Em reais. Exemplo: emissão de bilhetes sem comissão ao consolidador. Repasse a terceiros. Em reais. Fatura: Se cartão, será creditado em fatura. Se outra forma de pagamento, não constará na fatura. Taxa cobrada pela administradora do cartão sobre o repasse a terceiros. Em reais. Fatura: Será descontado na fatura. bilhetes - - Dentro virão os números dos bilhetes e comissões. bilhete - Array Bilhetes referentes à este passageiro ou forma de pagamento. Apesar de ser uma array, normalmente virá apenas um. numero 1-10 String AZUL ou GOL: Virá o localizador da reserva OUTRA: Virá o número do bilhete comisrecforvalor 4-15 String ###.###.##0,00 descpagclivalor 4-15 String ###.###.##0,00 Comissão da venda do bilhete. Não inclui a DU. Em reais. Pertence à tag aereorodoviario. Será retornado sempre 0,00, pois a Ancoradouro não controla o desconto que a agência passa ao cliente final. Pertence à tag aereorodoviario. observacao 0-70 String Caso o bilhete tenha algum desconto além da comissão será retornada aqui. Exemplo: Desconto de R$100,00. Pertence à tag aereorodoviario. trechos - - Serão retornados os vôos do itinerário em tags segmento. segmento - Array Cada tag corresponde a um vôo que compõe o itinerário. de 3 String Código da cidade de origem. para 3 String Código da cidade de destino. Data de saída do vôo. Data de embarque. datasaida 10 String dd/mm/yyyy

10 horasaida 5 String HH:MM datachegada 10 String dd/mm/yyyy XML WEBSERVICE ANCDWS Horário de saída do vôo. Horário de embarque. Data de chegada do vôo. Data de desembarque. Não será retornada, pois a Ancoradouro não guarda a data de desembarque. horachegada 5 String HH:MM Horário de chegada do vôo. Horário de desembarque. ciaaerea 2-3 String Código da companhia aérea do vôo. Se for codeshare, virá o código da companhia que vendeu o vôo, não a que opera. Exemplos: DL, se for DL operado por DL, DL, se for DL operado por LX e AMG se for Air Minas. voo 4 String #### ou OPEN Número do vôo. Retornará a palavra OPEN se o trecho for um trecho em aberto. Exemplos: 0001 e classe 1-2 String Classe de reserva. localizador 1-7 String Localizador da reserva. Caso o vôo contenha o localizador direto da companhia aérea, ele será retornado. status 0-10 String Situação do vôo. Exemplo: HK ou HL erros - - Só virá se houver algum erro. Neste caso, não virá a tag venda, só os erros. erro - Array Cada erro encontrado e que motive a venda não ser mostrada será colocado aqui. Caso dê erro nenhuma venda será retornada. numero 1-3 String Ordem do erro na lista de erros. ##0 descricao - String Descrição do erro. Não há um tamanho definido, pois o erro de sistema vem completo. local - String Em qual processo o erro ocorreu. 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

11 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 (Em fase de implementação) 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 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 usuário (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.

12 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.

13 Método: ConsultarVendaXML Consulta: <ConsultarVendaXML xmlns=" <dataemissao>string</dataemissao> <localizador>string</localizador> <usuario>string</usuario> <senha>string</senha> </ConsultarVendaXML> Tag Tamanho Formato Descrição dataemissao 10 String dd/mm/yyyy Data de emissão do bilhete ou do localizador Se não for preenchido é considerada a data atual. localizador 0-7 String Localizador da reserva bilhete 0-10 String Formulário e série do bilhete de passagem sem o número da companhia usuario String senha 6-30 String Resposta: <ConsultarVendaXMLResponse xmlns=" <ConsultarVendaXMLResult>string</ConsultarVendaXMLResult> </ConsultarVendaXMLResponse> Tag Tamanho Formato Descrição ConsultarVendaXMLResult - String É uma tag contendo o XML de vendas. Dentro dela será retornado: <?xml version="1.0" encoding="utf-8"?> <vendas> <venda/> <venda/> </vendas> Todas as outras tags vêm na mesma estrutura do método ConsultarVenda, só que serializado.

14 Método: ConsultarVendas Consulta: <ConsultarVendas xmlns=" <datainicial>string</datainicial> <usuario>string</usuario> <senha>string</senha> </ConsultarVendas> Tag Tamanho Formato Descrição datainicial 10 String dd/mm/yyyy datafinal 10 String dd/mm/yyyy usuario String senha 6-30 String Data inicial do período de vendas. Máximo 15 dias no período. Se não for informada será utilizada a mesma data do final do período. Se nenhuma das duas for preenchida é considerada a data atual. Data final do período de vendas. Máximo 15 dias no período. Se não for informada será utilizada a mesma data do início do período. Se nenhuma das duas for preenchida é considerada a data atual. Resposta: Mesmo conteúdo do método ConsultarVenda Tag Tamanho Formato Descrição vendas - - Mesmo conteúdo do método ConsultarVenda, só que permite que seja consultado um período de vendas.

15 Método: ConsultarVendasXML Consulta: <ConsultarVendasXML xmlns=" <datainicial>string</datainicial> <usuario>string</usuario> <senha>string</senha> </ConsultarVendasXML> Tag Tamanho Formato Descrição data inicial 10 String dd/mm/yyyy datafinal 10 String dd/mm/yyyy usuario String senha 6-30 String Data inicial do período de vendas. Máximo 15 dias no período. Se não for informada será utilizada a mesma data do final do período. Data final do período de vendas. Máximo 15 dias no período. Se não for informada será utilizada a mesma data do início do período. Resposta: <ConsultarVendasXMLResponse xmlns=" <ConsultarVendasXMLResult>string</ConsultarVendasXMLResult> </ConsultarVendasXMLResponse> Tag Tamanho Formato Descrição string - String É uma tag string contendo o XML de vendas. <?xml version="1.0" encoding="utf-8"?> <vendas> <venda/> <venda/> </vendas> Todas as outras tags vêm na mesma estrutura do método ConsultarVendas, só que serializado.

16 4. Vendas e usuário para testes 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.

17 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:

18 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.

19 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

20 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.