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
XML WEBSERVICE ANCDWS
Índice
Índice ......................................................................................................................................................................... 2
1.
Versões .............................................................................................................................................................. 3
2.
Introdução ......................................................................................................................................................... 4
3.
AgiWS – Modelo STur – AGI Sistemas ............................................................................................................... 5
4.
Vendas e usuário para testes .......................................................................................................................... 16
5.
Aplicação para teste ........................................................................................................................................ 17
6.
Como obter seu acesso ao WebService .......................................................................................................... 18
7.
Dúvidas, sugestões e suporte técnico ............................................................................................................. 19
8.
FAQ – Perguntas frequentes ........................................................................................................................... 20
PÁGINA 2
XML WEBSERVICE ANCDWS
1. Versões
Versão
Data da liberação
Tarefas realizadas
1.0
15/01/2009
- Criado o WebService e liberado para acesso de testes.
1.0r20
1.0r22
1.0r23
06/11/2012
29/09/2014
24/11/2014
- Separados os manuais em AncdWS, AppsWS e AGIWS.
- Corrigida URL de testes e URLs do serviço
- Atualizados links e e-mails do portal
XML WEBSERVICE ANCDWS
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
https://www.efacilplus.com.br/ancdws/agi.asmx
https://www.efacilplus.com.br/ancdws/agi.asmx
https://www.efacilplus.com.br/ancdws/agi.asmx?wsdl
XML WEBSERVICE ANCDWS
3. AgiWS – Modelo STur – AGI Sistemas
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.
XML WEBSERVICE ANCDWS
Método: ConsultarVenda
Consulta:
<ConsultarVenda xmlns="http://www.ancd.com.br/">
<dataemissao>string</dataemissao>
<localizador>string</localizador>
<usuario>string</usuario>
<senha>string</senha>
</ConsultarVenda>
Tag
Tamanho
Formato
Descrição
dataemissao
10
localizador
usuario
senha
0-7
1-100
6-30
String
dd/MM/yyyy
String
String
String
Data de emissão do bilhete ou do localizador.
Se não for preenchido é considerada a data atual.
Localizador da reserva
Resposta:
<ConsultarVendaResponse xmlns="http://www.ancd.com.br/">
<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>
XML WEBSERVICE ANCDWS
<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
-
-
venda
-
Array
origem
idvenda
tipoproduto
11
1-20
-
String
String
String
clasproduto
-
String
idemissor
dtemissao
1-10
10
idcliente
-
String
String
dd/MM/yyyy
String
Tag principal. Não se repete. Dentro virá uma
array venda
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.
Sempre virá “ANCORADOURO”
Id da reserva em nosso sistema
“Aereo” – Bilhere físico
“Etkt” – Bilhete eletrônico
“N” – Nacional
“I” - Internacional
Código do emissor ou do digitador
idoperador
13
String
Sempre virá em branco, pois não temos o código
do cliente da agência.
Virá sempre “Consolidadora”
XML WEBSERVICE ANCDWS
idfornecedor
formrec
2-3
0-1
String
String
vencrec
-
String
formpagto
-
String
Vencpagto
0
String
cartaocia
-
String
cartaonumero
cartaovalidade
cartaocodseguranca
titularcartao
0-20
0,7
0
0-50
String
Código da empresa aérea
Somente será preenchido se for cartão de
crédito.
“3” - Cartão de crédito
Virá sempre vazio, pois não temos a informação
de como o cliente pagou ao cliente.
“1” - Cash/À vista
“2” - Faturado
Dia do vencimento da fatura desta venda. Será
retornado sempre vazio.
“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
Número do cartão de crédito, se a venda o
contiver.
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.
String
String
Somente será preenchido se for cartão de
crédito.
“3” - Cartão de crédito
Sempre será retornado vazio.
Nome do titular, se a venda o contiver.
movimentos
-
-
aereorodoviario
-
Array
pax
3-40
String
tipo
-
String
Somente será preenchido se for cartão de
crédito.
“3” - Cartão de crédito
Não se repete. Dentro virão vários bilhetes em
tags aereorodoviario
Cada bilhete vem dentro de uma tag
aereorodoviario. Se o passageiro possuir mais de
um bilhete, virão duas tags com o mesmo
passageiro.
Nome e sobrenome do passageiro.
Exemplo: “SILVA/JOAOMR” ou “SILVA/JOSE MR”
ou “SILVA/J MR”
ADT - Adulto
CHD - Criança
XML WEBSERVICE ANCDWS
INF – Colo
basetarifaria
tarifa
8
4-15
tarifacheia
4-15
moeda
cambio
4-10
datacambio
10
taxaembarque
4-15
taxaservico
4-15
repassedu
4-15
String
###.###.##0,00
taxacartaodu
4-15
String
###.###.##0,00
bilhetes
-
-
bilhete
-
Array
numero
1-10
String
comisrecforvalor
4-15
String
###.###.##0,00
descpagclivalor
4-15
String
###.###.##0,00
observacao
0-70
String
trechos
-
-
segmento
-
Array
de
para
datasaida
3
3
10
String
String
String
dd/MM/yyyy
String
String
###.###.##0,00
String
###.###.##0,00
String
String
###.##0,00
String
dd/MM/yyyy
String
###.###.##0,00
String
###.###.##0,00
Tarifa em reais.
Tarifa normal da rota sem desconto ou repetição
da tarifa aplicada. Em reais.
Sempre será retornado “R$”
Sempre será retornado “1,00”. Em reais.
Sempre será retornado o dia da emissão.
Taxas de embarque e penalidade. Em reais.
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.
Dentro virão os números dos bilhetes e
comissões.
Bilhetes referentes à este passageiro ou forma de
pagamento. Apesar de ser uma array,
normalmente virá apenas um.
AZUL ou GOL: Virá o localizador da reserva
OUTRA: Virá o número do bilhete
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.
Caso o bilhete tenha algum desconto além da
comissão será retornada aqui. Exemplo:
“Desconto de R$100,00.”
Pertence à tag aereorodoviario.
Serão retornados os vôos do itinerário em tags
segmento.
Cada tag corresponde a um vôo que compõe o
itinerário.
Código da cidade de origem.
Código da cidade de destino.
Data de saída do vôo. Data de embarque.
XML WEBSERVICE ANCDWS
horasaida
5
datachegada
10
horachegada
5
ciaaerea
2-3
voo
4
String
#### ou OPEN
classe
localizador
1-2
1-7
String
String
status
erros
0-10
-
String
-
erro
-
Array
numero
1-3
descricao
-
String
##0
String
local
-
String
String
HH:MM
String
dd/MM/yyyy
String
HH:MM
String
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.
Horário de chegada do vôo. Horário de
desembarque.
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.
Número do vôo. Retornará a palavra “OPEN” se
o trecho for um trecho em aberto. Exemplos:
“0001” e “3454”.
Classe de reserva.
Localizador da reserva. Caso o vôo contenha o
localizador direto da companhia aérea, ele será
retornado.
Situação do vôo. Exemplo: “HK” ou “HL”
Só virá se houver algum erro. Neste caso, não
virá a tag venda, só os erros.
Cada erro encontrado e que motive a venda não
ser mostrada será colocado aqui. Caso dê erro
nenhuma venda será retornada.
Ordem do erro na lista de erros.
Descrição do erro. Não há um tamanho definido,
pois o erro de sistema vem completo.
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
XML WEBSERVICE ANCDWS
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.
XML WEBSERVICE ANCDWS
Exemplo:
<observacoes>AGT1:100,1234,,,,,,,,,,A129,23456-4,,,,,</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.
XML WEBSERVICE ANCDWS
Método: ConsultarVendaXML
Consulta:
<ConsultarVendaXML xmlns="http://www.ancd.com.br/">
<dataemissao>string</dataemissao>
<localizador>string</localizador>
<usuario>string</usuario>
<senha>string</senha>
</ConsultarVendaXML>
Tag
Tamanho
Formato
Descrição
dataemissao
10
localizador
bilhete
0-7
0-10
String
dd/MM/yyyy
String
String
Data de emissão do bilhete ou do localizador
Se não for preenchido é considerada a data atual.
Localizador da reserva
Formulário e série do bilhete de passagem sem o
número da companhia
usuario
senha
1-100
6-30
String
String
Resposta:
<ConsultarVendaXMLResponse xmlns="http://www.ancd.com.br/">
<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.
XML WEBSERVICE ANCDWS
Método: ConsultarVendas
Consulta:
<ConsultarVendas xmlns="http://www.ancd.com.br/">
<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
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.
usuario
senha
1-100
6-30
String
String
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.
XML WEBSERVICE ANCDWS
Método: ConsultarVendasXML
Consulta:
<ConsultarVendasXML xmlns="http://www.ancd.com.br/">
<datainicial>string</datainicial>
<usuario>string</usuario>
<senha>string</senha>
</ConsultarVendasXML>
Tag
Tamanho
Formato
Descrição
10
String
dd/MM/yyyy
datafinal
10
String
dd/MM/yyyy
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.
usuario
senha
1-100
6-30
String
String
data
inicial
Resposta:
<ConsultarVendasXMLResponse xmlns="http://www.ancd.com.br/">
<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.
XML WEBSERVICE ANCDWS
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.
XML WEBSERVICE ANCDWS
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:
https://webapps.efacilplus.com.br
http://www.efacilplus.com.br
Baixar o manual em PDF:
http://ancoradouroconsolidadora.com.br/arquivos/pdf/manual_xmlws-agi.pdf
Baixar a aplicação:
http://ancoradouroconsolidadora.com.br/arquivos/diversos/TesteAncdWS.zip
XML WEBSERVICE ANCDWS
6. Como obter seu acesso ao WebService
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 e-mail para:
Help Desk – [email protected]
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 e-mail (único) específico para a integração, será criado em nome do e-mail 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 e-mail específico para a integração, vinculada a outro email existente. Isto evita o inconveniente de conflitar com usuário do portal e o risco de se utilizar a mesma senha.
XML WEBSERVICE ANCDWS
7. Dúvidas, sugestões e suporte técnico
Enviar e-mail para [email protected]
Telefone: 19-2137-3224
Atenção, o suporte técnico é somente para desenvolvedores.
O suporte para as agências se dará pelo e-mail [email protected]. 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
Qualquer problema técnico deverá ser feito pelo desenvolvedor, com a descrição do problema
gerado.
XML WEBSERVICE ANCDWS
8. FAQ – Perguntas frequentes
1.
O sistema fica com alguma sessão aberta? Como funciona o logon e o logoff do
sistema?
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.
3.
Desenvolvo em Delphi, por que só me vem a resposta de que não estou passando os
dados?
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.