UltraCard Manual de integração via WebService Página 1/13. UltraCard. Manual de integração via WebService. Versão 2.5

Transcrição

1 UltraCard Manual de integração via WebService Página 1/13 UltraCard Manual de integração via WebService Versão 2.5

2 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 () executarencerrartransacao () executarconsultartabelaconvenios () executarconsultarautorizacao ()... 12

3 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 Arquivo WSDL usado para a autorização Acesse o endereço abaixo: Requisitos para o WebService funcionar -Internet na loja para fazer a comunicação com os nossos servidores. - é necessário a instalação de nenhum programa autorizador nosso nos terminais/caixa. Dúvidas Entrar em contato com Felipe através do felipe@ultramax.com.br

4 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 Dados para os testes Nome da administradora: ULTRALINK Código do estabelecimento: 900 Senha do estabelecimento: teste Nome de cliente de teste: Maria, Jose Números de cartão de teste: , , , , Produtos para teste: Qualquer um. Endpoint do WebService do banco de dados de teste: 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: Endpoint do WebService: Para a administradora: XYZ Nome da administradora: XYZ Código do estabelecimento: 765 Senha do estabelecimento: Endpoint do WebService:

5 UltraCard Manual de integração via WebService Página 5/13 Fluxograma da autorização

6 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: codigo Código do estabelecimento na administradora. Esse código é informado pela administradora. senha Senha do estabelecimento na administradora. Essa senha é informada pela administradora. nomeadministradora Nome da administradora. 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: identificacaocliente Pode ser usado o nome, matrícula ou número o cartão do cliente. Depende da administradora. codigocliente Código único do cliente. Será explicado ao decorrer do manual. 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.

7 UltraCard Manual de integração via WebService Página 7/13 Classe ConsultaClienteResponse: codigocliente Código único do cliente no sistema interno da administradora. nomecliente Nome do cliente. matriculacliente Matrícula (chapa) do cliente na empresa. codigoconvenio Código do convênio na administradora a qual o cliente pertence. nomeconvenio Nome do convênio na administradora a qual o cliente pertence. codigofilialconvenio Código da filial do convênio no cadastro da administradora. nomefilialconvenio Nome da filial do convênio no cadastro da administradora. cnpjfilialconvenio Nome da filial do convênio no cadastro da administradora. saldodisponível Saldo em reais disponível para que o cliente possa comprar. mensagemusuario 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. Dependentes Array do tipo Dependente contendo os dependentes do cliente. A automação deve exibir uma tela para que o balconista selecione o dependente. subsidios 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). solicitarselecaonome Indica se a busca feita retornou mais de um cliente, por exemplo: Se o balconista digitou o nome Maria irá retornar diversos clientes. selecaopornome 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. selecaonomespossuimais 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. integradofidelidade Indica se o cliente possui cartão fidelidade da rede (true ou false)

8 UltraCard Manual de integração via WebService Página 8/13 cartaofidelidade Caso o cliente possua cartão fidelidade da rede, irá retornar o número do cartão. Classe Subsidio: codigo Código do subsídio. Utilizado para solicitar a autorização com a função executarsolicitarautorizacao() nome Nome do subsídio, usado para o balconista selecione o subsídio. Classe RegistroCliente: codigo Código único do cliente. Usado na função executarconsultarcliente() para buscar o cliente pelo código. nome Nome do cliente. convenio Nome da empresa conveniada a qual o cliente pertence. status Descrição do status do cliente, por exemplo: Ativo, Inativo, etc. Classe Dependente: codigo Código do dependente. Utilizado para solicitar a autorização com a função executarsolicitarautorizacao() nome Nome do dependente. 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.

9 UltraCard Manual de integração via WebService Página 9/13 Classe AutorizacaoRequest: codigocliente Código único do cliente. Retornado na função executarconsultarcliente(). codigodependente Código do dependente que está comprado. Retornado na função executarconsultarcliente(). Informado somente quando não é o titular que está comprando Se não informado o WebService entenderá que o titular está comprando. codigosubsidio Código do subsídio. Retornado na função executarconsultarcliente(). conselhoprescritor Pode ser CRM, CRO ou CRMV. CRM = Medicina CRO = Odontologia CRMV = Veterinária numeroregistroprescritor Número da matrícula do prescritor. Quando retornado pelo menos um subsídio na função executarconsultarcliente() é obrigatório informar o código no subsídio na autorização. se for uma venda com receita médica. se for uma venda com receita médica. estadoconselhoprescritor Estado de registro do prescritor. se for uma venda com receita médica. datareceita Data da receita médica. se for uma venda com receita médica. produtos Array do tipo Produto contendo os produtos da venda. Classe Produto: codigobarra Código de barras do produto. Informa 0 (ZERO) se o produto não possui código de barras. Descrição Descrição do produto codigofabricante Código do fabricante do produto no cadastro do estabelecimento. Fabricante Nome do fabricante do produto. Medicamento true ou false. Sendo que true indica que o produto é um medicamento e false indica que é, por exemplo, uma perfumaria, etc. precobruto Preço sem desconto praticado pelo estabelecimento. PMC - preço máximo consumidor. precoliquido Preço com desconto praticado pelo estabelecimento. quantidade Quantidade vendida subtotalliquido quantidade * precoliquido com duas decimais. Classe AutorizacaoResponse: nsupreautorizacao Código da pré-autorização. Será utilizado na função executarconfirmarvenda().

10 UltraCard Manual de integração via WebService Página 10/13 produtos Array do tipo Produto contendo a confirmação dos 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: codigocliente Código único do cliente. Retornado na função executarconsultarcliente(). nsupreautorizacao Código da pré-autorização retornado na função executarsolicitarautorizacao(). numerocupomfiscal Número do cupom fiscal impresso valortotalvenda Valor total líquido (com todos os descontos) da venda. numeroparcelas Número de parcelas, informar 1 quando for somente uma parcela. Classe ConfirmarVendaResponse: nsupreautorizacao Código da pré-autorização retornado na função executarsolicitarautorizacao(). nsuautorizacao Código da autorização final. Esse é o código que confirma a venda com a admistradora. linhascomprovante 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

11 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: nsuautorizacao Código da autorização retornado na função executarconfirmarvenda(). impressocomsucesso Indica se o cupom fiscal e comprovante foram impressos com sucesso. Classe EncerrarTransacaoResponse: nsuautorizacao Callback somente informativo com o número da autorização. 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.

12 UltraCard Manual de integração via WebService Página 12/13 Classe ConsultarTabelaConveniosResponse: Convênios Array do tipo Convenio contendo os convênios autorizados para o estabelecimento. Classe Convenio: nomeconvenio Nome do convênio cnpj inscricaoestadual tipoplano Informativo. Definido pela administradora. bairro cidade estado cep mensagemvenda Mensagem de aviso. Por exemplo: vender somente com apresentação da receita médica, etc. numeromaximoparcelas Número máximo de parcelas que o cliente poderá escolher. porcentagemdescontobalcao Porcentagem de desconto mínima que o estabelecimento deverá conceder para os clientes desse convênio. diafechamento Dia do mês que a administradora irá executar o fechamento desse convênio. diapagamento 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. 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: datainicial Data inicial da autorização datafinal Data final da autorização codigoempresa Cödigo da empresa do funcionário matricula Número da matrícula do funcionário

13 UltraCard Manual de integração via WebService Página 13/13 numeroautorizacao Número da autorização a ser consultada numeronota Número do cupom fiscal 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: Autorizações Array do tipo Autorizacao contendo todas as autorizações com base no filtro informado. Classe Autorizacao: data Data da autorização empresa Código e nome da empresa matricula Número da matrícula do funcionário. nomefuncionario Nome do funcionário numeroautorizacao Número da autorização numeronota Número do cupom fiscal Valor Valor da autorização status 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