UltraCard – Manual de integração via WebService
Página 1/13
UltraCard
Manual de integração via WebService
Versão 2.5
UltraCard – Manual de integração via WebService
Página 2/13
Índice
O que é WebService? ............................................................................................................3
O quê é WSDL? ....................................................................................................................3
Referências ..........................................................................................................................3
Arquivo WSDL usado para a autorização ..................................................................................3
Requisitos para o WebService funcionar ...................................................................................3
Dúvidas...............................................................................................................................3
Exemplo ..............................................................................................................................4
Dados para os testes.............................................................................................................4
Configuração para o ambiente de produção ..............................................................................4
Fluxograma da autorização ....................................................................................................5
Funções do WebService .........................................................................................................6
Dados comuns a todas as funções ........................................................................................6
executarConsultarCliente() ..................................................................................................6
executarSolicitarAutorizacao() .............................................................................................8
executarConfirmarVenda () ............................................................................................... 10
executarEncerrarTransacao () ............................................................................................ 11
executarConsultarTabelaConvenios () ................................................................................. 11
executarConsultarAutorizacao () ........................................................................................ 12
UltraCard – Manual de integração via WebService
Página 3/13
O que é WebService?
Web service é uma solução utilizada na integração de sistemas e na comunicação entre aplicações
diferentes. Com esta tecnologia é possível que novas aplicações possam interagir com aquelas que já
existem e que sistemas desenvolvidos em plataformas diferentes sejam compatíveis. Os Web services
são componentes que permitem às aplicações enviar e receber dados em formato XML. Cada aplicação
pode ter a sua própria "linguagem", que é traduzida para uma linguagem universal, o formato XML.
Para as empresas, os Web services podem trazer agilidade para os processos e eficiência na
comunicação entre cadeias de produção ou de logística. Toda e qualquer comunicação entre sistemas
passa a ser dinâmica e principalmente segura, pois não há intervenção humana. 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 (o padrão não determina o protocolo de transporte). Os dados são
transferidos no formato XML, encapsulados pelo protocolo SOAP. Uma vantagem a destacar é que no
ponto de venda não é necessário instalar nenhum software para realizar a comunicação
(autorizadores, por exemplo), pois, a automação comercial acessa diretamente os nossos servidores.
O quê é WSDL?
Web Service Definition Language define um sistema para a descrição de serviços. Através dela,
descrevemos os serviços externos, ou interfaces que são oferecidos por uma determinada aplicação,
independente de sua plataforma ou linguagem de programação. O seu principal objetivo é descrever
as interfaces apresentadas e apontar a localização dos seus serviços. Por ser um documento XML, sua
leitura se torna fácil e acessível.
Referências
http://pt.wikipedia.org/wiki/WebServices
http://www.exforsys.com/tutorials/vb.net-2005/web-reference-asp.net-web-application-and-xml-webservice.html
http://www.macoratti.net/vbn5_goo.htm
Arquivo WSDL usado para a autorização
Acesse o endereço abaixo:
http://ultralink.ultramax.com.br:8080/ultracard/services/AutorizadorWS?wsdl
Requisitos para o WebService funcionar
-Internet na loja para fazer a comunicação com os nossos servidores.
-Não é necessário a instalação de nenhum programa autorizador nosso nos terminais/caixa.
Dúvidas
Entrar em contato com Felipe através do e-mail [email protected]
UltraCard – Manual de integração via WebService
Página 4/13
Exemplo
Fazendo o download do arquivo abaixo você terá um exemplo de como é feita a comunicação via
WebService em VisualBasic.NET 2005.
http://www.ultramax.com.br/ultracard/webservice/Exemplo.zip
Dados para os testes
Nome da administradora: ULTRALINK
Código do estabelecimento: 900
Senha do estabelecimento: 123456teste
Nome de cliente de teste: Maria, Jose
Números de cartão de teste: 100008, 100002, 100003, 100004, 100005
Produtos para teste: Qualquer um.
Endpoint do WebService do banco de dados de teste:
http://ultralink.ultramax.com.br:8080/ultracard/services/AutorizadorWS
Configuração para o ambiente de produção
Quando o sistema for utilizado em produção, os itens abaixo precisarão ser alterados. Então
recomendamos as SoftwareHouses a criar uma configuração para que o aplicativo de automação possa
funcionar com todas as administradoras que utilizam o sistema UltraCard.
Nome da administradora: <CONFIGURÁVEL NO APLICATIVO DE AUTOMAÇÃO>
Código do estabelecimento: <CONFIGURÁVEL NO APLICATIVO DE AUTOMAÇÃO>
Senha do estabelecimento: <CONFIGURÁVEL NO APLICATIVO DE AUTOMAÇÃO>
Endpoint do WebService: <CONFIGURÁVEL NO APLICATIVO DE AUTOMAÇÃO>
Para cada administradora, será um “Nome da administradora”, “Código do estabelecimento”, “Senha
do estabelecimento” e “Endpoint do WebService” diferente. Mas o funcionamento do sistema será
sempre o mesmo.
Por exemplo:
Para a administradora: ABC
Nome da administradora: ABC
Código do estabelecimento: 123
Senha do estabelecimento: 999888
Endpoint do WebService: http://abc.endereco.com.br:8080/ultracard/services/AutorizadorWS
Para a administradora: XYZ
Nome da administradora: XYZ
Código do estabelecimento: 765
Senha do estabelecimento: 123456
Endpoint do WebService: http://www.xyz.com.br:8080/ultracard/services/AutorizadorWS
UltraCard – Manual de integração via WebService
Fluxograma da autorização
Página 5/13
UltraCard – Manual de integração via WebService
Página 6/13
Funções do WebService
Dados comuns a todas as funções
A classe IdentificacaoEstabelecimento será utilizada em todas as funções do WebService. Ela é
utilizada para identificar o estabelecimento (loja) e contém os seguintes atributos:
Atributo
codigo
Descrição
Código do estabelecimento na administradora. Esse
código é informado pela administradora.
Obrigatório?
Sim
senha
Senha do estabelecimento na administradora. Essa
senha é informada pela administradora.
Sim
nomeAdministradora
Nome da administradora.
Sim
executarConsultarCliente()
Utilizado para procurar o cliente no sistema da administradora.
Parâmetros:
IdentificacaoEstabelecimento: Identificação do estabelecimento.
ConsultaClienteRequest: Dados usados para buscar o cliente.
Retorno:
Objeto do tipo ConsultaClienteResponse:
Exceção:
ValidacaoException: Caso o cliente não existe, esta inativo, sem limite de crédito, etc. A venda não
poderá prosseguir. A mensagem com o motivo é retornada no atributo “message”.
Classe ConsultaClienteRequest:
Atributo
identificacaoCliente
codigoCliente
Descrição
Pode ser usado o nome, matrícula ou número o cartão
do cliente. Depende da administradora.
Código único do cliente. Será explicado ao decorrer do
manual.
Obrigatório?
Não
Não
Somente um dos dois atributos deve ser informado, sendo que:
-Se informado o atributo “codigoCliente” sempre será retornado somente UM cliente ou irá ocorrer
uma exceção caso o cliente não esteja cadastrado.
-Se informado o atributo “identificacaoCliente”, poderá retorna UM ou vários clientes. Se retornar um a
automação pode prosseguir a venda, caso retorna mais de um, a automação deverá exibir uma tela
para que o balconista selecione um entre os vários clientes.
UltraCard – Manual de integração via WebService
Página 7/13
Classe ConsultaClienteResponse:
Atributo
codigoCliente
nomeCliente
matriculaCliente
codigoConvenio
nomeConvenio
codigoFilialConvenio
nomeFilialConvenio
cnpjFilialConvenio
saldoDisponível
mensagemUsuario
Dependentes
subsidios
solicitarSelecaoNome
selecaoPorNome
selecaoNomesPossuiMais
integradoFidelidade
Descrição
Código único do cliente no sistema interno da
administradora.
Nome do cliente.
Matrícula (chapa) do cliente na empresa.
Código do convênio na administradora a qual o
cliente pertence.
Nome do convênio na administradora a qual o
cliente pertence.
Código da filial do convênio no cadastro da
administradora.
Nome da filial do convênio no cadastro da
administradora.
Nome da filial do convênio no cadastro da
administradora.
Saldo em reais disponível para que o cliente possa
comprar.
Se retornado alguma mensagem, deve ser exibido
para o balconista logo que os dados do cliente
forem exibidos. Essa mensagem é somente um
aviso, a venda poderá continuar se houver
mensagem ou não.
Array do tipo “Dependente” contendo os
dependentes do cliente. A automação deve exibir
uma tela para que o balconista selecione o
dependente.
Array do tipo “Subsidio” contendo os possíveis
subsídios para esse cliente. A automação deve
exibir uma tela para que o balconista selecione o
subsídio. (Exemplo de subsídio: COM RECEITA,
SEM RECEITA, etc).
Indica se a busca feita retornou mais de um
cliente, por exemplo: Se o balconista digitou o
nome “Maria” irá retornar diversos clientes.
Array do tipo “RegistroCliente” com os registros
dos clientes encontrados como resultado da busca
do balconista. Se o campo “solicitarSelecaoNome”
for “verdadeiro”, a automação deve exibir uma tela
contendo os nomes desse array para que o
balconista selecione um cliente.
Quando a busca retorna mais de um cliente, o
WebService
irá
retorna
uma
determinada
quantidade de clientes encontrados (por exemplo,
20 clientes). Esse campo será “verdadeiro” se
ainda existe mais clientes encontrados com o
critério digitado pelo balconista. A automação
poderá exibir uma mensagem ao balconista
indicando que se ele deve digitar, por exemplo, o
nome e sobrenome do cliente para que a busca
não retorne muitos clientes.
Indica se o cliente possui cartão fidelidade da rede
(true ou false)
Obrigatório?
Não
Não
Não
Não
Não
Não
Não
Não
Não
Não
Não
Não
Sim
Não
Sim
Não
UltraCard – Manual de integração via WebService
Página 8/13
cartaoFidelidade
Caso o cliente possua cartão fidelidade da rede, irá
Não
retornar o número do cartão.
Classe Subsidio:
Atributo
codigo
nome
Descrição
Código do subsídio. Utilizado para solicitar a autorização
com a função “executarSolicitarAutorizacao()”
Nome do subsídio, usado para o balconista selecione o
subsídio.
Obrigatório?
Sim
Sim
Classe RegistroCliente:
Atributo
codigo
nome
convenio
status
Descrição
Código
único
do
cliente.
Usado
na
função
“executarConsultarCliente()” para buscar o cliente pelo
código.
Nome do cliente.
Nome da empresa conveniada a qual o cliente pertence.
Descrição do status do cliente, por exemplo: Ativo,
Inativo, etc.
Obrigatório?
Sim
Sim
Sim
Sim
Classe Dependente:
Atributo
codigo
nome
Descrição
Código do dependente. Utilizado para
autorização
com
a
“executarSolicitarAutorizacao()”
Nome do dependente.
solicitar a
função
Obrigatório?
Sim
Sim
executarSolicitarAutorizacao()
Utilizado para enviar os produtos vendidos e solicitar a autorização.
Os preços dos produtos (campos precoLiquido e subTotalLiquido) devem ser informados já com
o desconto.
Os descontos devem ser aplicados pelo sistema de automação de acordo com as regras
(percentual de desconto e grupo de produtos) estipuladas pela administradora, ou seja, o preço com
desconto não será retornando por este WebService, o desconto deve ser configurado no sistema de
automação.
Parâmetros:
IdentificacaoEstabelecimento: Identificação do estabelecimento.
AutorizacaoRequest: Dados da venda e do cliente.
Retorno:
Objeto do tipo AutorizacaoResponse:
Exceção:
ValidacaoException: Caso a autorização seja negada. A mensagem com o motivo é retornada no
atributo “message”.
UltraCard – Manual de integração via WebService
Página 9/13
Classe AutorizacaoRequest:
Atributo
codigoCliente
Descrição
Código único do cliente. Retornado
na
função
“executarConsultarCliente()”.
Código do dependente que está
comprado. Retornado na função
“executarConsultarCliente()”.
Informado somente quando não é o
titular que está comprando
Código do subsídio. Retornado na
função
“executarConsultarCliente()”.
codigoDependente
codigoSubsidio
conselhoPrescritor
numeroRegistroPrescritor
Pode ser “CRM”, “CRO” ou “CRMV”.
CRM = Medicina
CRO = Odontologia
CRMV = Veterinária
Número da matrícula do prescritor.
estadoConselhoPrescritor
Estado de registro do prescritor.
dataReceita
Data da receita médica.
produtos
Array do tipo “Produto” contendo os
produtos da venda.
Obrigatório?
Sim
Se não informado o
WebService entenderá que
o titular está comprando.
Quando retornado pelo
menos um subsídio na
função
“executarConsultarCliente()”
é obrigatório informar o
código no subsídio na
autorização.
Sim se for uma venda com
receita médica.
Sim se
receita
Sim se
receita
Sim se
receita
for uma venda com
médica.
for uma venda com
médica.
for uma venda com
médica.
Sim
Classe Produto:
Atributo
codigoBarra
Descrição
codigoFabricante
Fabricante
Medicamento
precoBruto
precoLiquido
quantidade
subTotalLiquido
Descrição
Código de barras do produto. Informa “0” (ZERO) se o
produto não possui código de barras.
Descrição do produto
Código do fabricante do produto no cadastro do
estabelecimento.
Nome do fabricante do produto.
“true” ou “false”. Sendo que “true” indica que o produto
é um medicamento e “false” indica que é, por exemplo,
uma perfumaria, etc.
Preço sem desconto praticado pelo estabelecimento.
PMC - preço máximo consumidor.
Preço com desconto praticado pelo estabelecimento.
Quantidade vendida
quantidade * precoLiquido com duas decimais.
Obrigatório?
Sim
Sim
Sim
Sim
Sim
Sim
Sim
Sim
Sim
Classe AutorizacaoResponse:
Atributo
nsuPreAutorizacao
Descrição
Código da pré-autorização. Será utilizado na função
“executarConfirmarVenda()”.
Obrigatório?
Sim
UltraCard – Manual de integração via WebService
Página 10/13
produtos
Array do tipo “Produto” contendo a confirmação dos
Sim
produtos vendidos.
executarConfirmarVenda ()
Utilizado para confirmar a pré-autorização e obter o comprovante a ser impresso no cupom fiscal.
Alguns convênios possuem pagamento antecipado pelo funcionário, nesse caso, o sistema de
automação deverá receber parte do pagamento a vista (dinheiro, cheque, cartão de crédito/débito e
etc) e outra parte será enviada no campo “valorTotalVenda” desde método.
Por exemplo: O convênio tem pagamento antecipado de 42,86%.
Em uma venda de R$ 150,00, deverá receber R$ 64,29 a vista e R$ 85,71 deverá ser enviado no
campo “valorTotalVenda” desde método.
Obs.: Esse percentual não é desconto, é um percentual que o funcionário deverá pagar a vista e não
será descontado em folha de pagamento.
Parâmetros:
IdentificacaoEstabelecimento: Identificação do estabelecimento.
ConfirmarVendaRequest: Dados da venda e do cliente.
Retorno:
Objeto do tipo ConfirmarVendaResponse:
Exceção:
ValidacaoException: Caso a confirmação da venda seja negada. A mensagem com o motivo é
retornada no atributo “message”.
Classe ConfirmarVendaRequest:
Atributo
codigoCliente
nsuPreAutorizacao
numeroCupomFiscal
valorTotalVenda
numeroParcelas
Descrição
Código único do cliente. Retornado na função
“executarConsultarCliente()”.
Código da pré-autorização retornado na função
“executarSolicitarAutorizacao()”.
Número do cupom fiscal impresso
Valor total líquido (com todos os descontos) da venda.
Número de parcelas, informar 1 quando for somente
uma parcela.
Obrigatório?
Sim
Sim
Sim
Sim
Sim
Classe ConfirmarVendaResponse:
Atributo
nsuPreAutorizacao
nsuAutorizacao
linhasComprovante
Descrição
Código da pré-autorização retornado na função
“executarSolicitarAutorizacao()”.
Código da autorização final. Esse é o código que
confirma a venda com a admistradora.
Array do tipo “string” contendo as linhas do
comprovante. Deve ser impresso como um cupom fiscal
vinculado ou relatório gerencial no ECF.
O sistema de automação deverá emitir todos os
Obrigatório?
Sim
Sim
Sim
UltraCard – Manual de integração via WebService
Página 11/13
produtos vendidos no cupom vinculado/relatório
gerencial, colocando a descrição do produto,
quantidade, valor vendido e percentual de
desconto de cada item.
executarEncerrarTransacao ()
Utilizado para finalizar a transação informando se o cupom fiscal e o comprovante foram impressos
corretamente.
Parâmetros:
IdentificacaoEstabelecimento: Identificação do estabelecimento.
EncerrarTransacaoRequest: Número da autorização e status da impressão.
Retorno:
Objeto do tipo EncerrarTransacaoResponse:
Exceção:
ValidacaoException: Caso a transação não possa ser encerrada. A mensagem com o motivo é
retornada no atributo “message”.
Classe EncerrarTransacaoRequest:
Atributo
nsuAutorizacao
impressoComSucesso
Descrição
Código
da
autorização
retornado
na
função
“executarConfirmarVenda()”.
Indica se o cupom fiscal e comprovante foram
impressos com sucesso.
Obrigatório?
Sim
Sim
Classe EncerrarTransacaoResponse:
Atributo
nsuAutorizacao
Callback somente
autorização.
Descrição
informativo com
o
número
da
Obrigatório?
Sim
executarConsultarTabelaConvenios ()
Utilizado para consulta os convênios autorizados para o estabelecimento. Esta função é opcional e
pode ser utilizada pelo sistema de automação para auxiliar o administrador do estabelecimento a
cadastrar os convênios no sistema de automação.
Parâmetros:
IdentificacaoEstabelecimento: Identificação do estabelecimento.
Retorno:
Objeto do tipo ConsultarTabelaConveniosResponse:
Exceção:
ValidacaoException: Caso a senha do estabelecimento esteja inválida ou qualquer outro motivo. A
mensagem com o motivo é retornada no atributo “message”.
UltraCard – Manual de integração via WebService
Classe ConsultarTabelaConveniosResponse:
Atributo
Convênios
Descrição
Array do tipo “Convenio” contendo
autorizados para o estabelecimento.
Página 12/13
os
convênios
Obrigatório?
Sim
Classe Convenio:
Atributo
nomeConvenio
cnpj
inscricaoEstadual
tipoPlano
bairro
cidade
estado
cep
mensagemVenda
Descrição
Nome do convênio
Informativo. Definido pela administradora.
numeroMaximoParcelas
porcentagemDescontoBalcao
diaFechamento
diaPagamento
Mensagem de aviso. Por exemplo: “vender
somente com apresentação da receita médica”,
etc.
Número máximo de parcelas que o cliente
poderá escolher.
Porcentagem de desconto mínima que o
estabelecimento deverá conceder para os
clientes desse convênio.
Dia do mês que a administradora irá executar
o fechamento desse convênio.
Dia do mês, após o dia de fechamento, que o
estabelecimento irá receber o pagamento das
vendas efetuadas para clientes desse convênio.
Obrigatório?
Sim
Sim
Não
Não
Não
Não
Não
Não
Não
Sim
Sim
Sim
Sim
executarConsultarAutorizacao ()
Utilizado para consultar autorizações enviadas pelo estabelecimento. Esta função é opcional e pode ser
utilizada pelo sistema de automação para auxiliar o administrador do estabelecimento.
Parâmetros:
IdentificacaoEstabelecimento: Identificação do estabelecimento.
consultaAutorizacao: Filtro para a busca de autorizações.
Retorno:
Objeto do tipo ConsultaAutorizacaoResponse:
Exceção:
ValidacaoException: Caso a senha do estabelecimento esteja inválida ou qualquer outro motivo. A
mensagem com o motivo é retornada no atributo “message”.
Classe ConsultaAutorizacaoRequest:
Atributo
dataInicial
dataFinal
codigoEmpresa
matricula
Descrição
Data inicial da autorização
Data final da autorização
Cödigo da empresa do funcionário
Número da matrícula do funcionário
Obrigatório?
Não
Não
Não
Não
UltraCard – Manual de integração via WebService
Página 13/13
numeroAutorizacao
Número da autorização a ser consultada
Não
numeroNota
Número do cupom fiscal
Não
Obs. 1: Apesar de nenhum atributo acima se obrigatório, pelo menos um deve ser preenchido.
Obs. 2: Se preencher a dataInicial a dataFinal será obrigatório, e vice-versa.
Obs.3: O período de datas deve ser no máximo 90 dias caso a matricula, numeroAutorizacao e
numeroNota não sejam informados.
Classe ConsultaAutorizacaoResponse:
Atributo
Autorizações
Descrição
Array do tipo “Autorizacao” contendo
autorizações com base no filtro informado.
todas
as
Obrigatório?
Sim
Classe Autorizacao:
Atributo
data
empresa
matricula
nomeFuncionario
numeroAutorizacao
numeroNota
Valor
status
Descrição
Data da autorização
Código e nome da empresa
Número da matrícula do funcionário.
Nome do funcionário
Número da autorização
Número do cupom fiscal
Valor da autorização
Pode ser:
FECHADA = Autorização está dentro de um
fechamento e já foi enviada para a empresa
NAO_FECHADA =Autorização está confirmada
mas ainda não foi enviada para a empresa
CANCELADA = Autorização foi enviada e depois
cancelada
NAO_CONFIRMADA = Autorização foi enviada
mas
pendente
de
confirmação
pelo
estabelecimento. Nesse caso o estabelecimento
precisa confirmar a autorização ou ignorar esta
e enviar outra
Obrigatório?
Sim
Sim
Sim
Sim
Sim
Sim
Sim
Sim