Integração com a Rodobank
A partir da versão 2.0.2401.1000 o Petroshow conta com a integração com a Rodobank.
Nesta integração é possível:
Gerar TrocoPay em troco de vendas.
Validar e usar Voucher no pagamento de vendas
Gerar TrocoPay em troco das trocas de numerários.
Validar e usar Voucher no pagamento de troca de numerários
Liberação do Módulo
Para que a integração seja habilitada, é necessário ter o módulo “PS - Integração Rodobank” habilitado para o cliente em questão. Com ele habilitado será possível seguir para o próximo passo de configuração, habilitando então outros menus na aplicação.
Quando o módulo não estiver habilitado, no PSGerencial, menu “Cadastros Específicos » Estabelecimento » Conf. PDV » Configurações PDV”, será apresentada uma mensagem indicando tal situação:
...
Configurações Necessárias
Com o módulo “PS - Integração Rodobank” licenciado, serão habilitados os campos para informar os dados de comunicação com a Rodobank nas configurações do PDV:
URL Servidor: URL Fornecida pela Rodobank para comunicação.
Usuário: Usuário para autenticação no servidor da Rodobank.
Senha: Senha/Token fornecido pela Rodobank para integração.
Usuário Cancelamento: Usuário que será utilizado para autorizar cancelamento das operações.
Senha Cancelamento: Senha do usuário de cancelamento, conforme cadastro na Rodobank.
Com essas configurações informadas, o Petroshow irá habilitar alguns menus a mais para que as operações da integração possam ser efetuadas.
Configurações no Cadastro de Pessoas
Depois que as configurações da Rodobank foram informadas nas configurações do PDV, no menu “Cadastros Gerais » Pessoas » Dados Complementares” será habilitada uma aba chamada “Rodobank”.
Nessa aba será possível informar os dados do contratado e os motoristas vinculados com aquele CNPJ, bem como outras configurações de pagamento.
...
Com relação ao contratado, é possível configurar o seguintes campos:
Telefone: Telefone do contratado, sendo que não permite informar um telefone já vinculado a outro contratado.
Dias p/ Pagamento: Indica quando o pagamento será efetuado. Caso informado zero irá considerar a mesma data da venda/troca de numerários.
E-mail: E-mail do contratado, sendo que não permite informar um e-mail já vinculado a outro contratado.
Tipo do TrocoPay: Campo com opções conforme API da Rodobank, informando qual é o tipo do TrocoPay que será emitido.
⚠️ Os campos Dias p/ Pagamento e Tipo do TrocoPay não impactam em nada na operação do Petroshow, sendo apenas enviados para a Rodobank onde serão submetidos às validações deles.
Já para o grid de motoristas, podemos informar os seguintes dados:
Nome: Nome para identificação do motorista.
CPF: Documento do motorista, sendo que não podem ser informados dois motoristas com o mesmo CPF dentro do cadastro da mesma pessoa.
Nascimento: Data de nascimento do motorista.
Telefone: Telefone do motorista, sendo que não podem ser informados dois motoristas com o mesmo telefone dentro do cadastro da mesma pessoa.
Cód. Ativação Cartão: Código para vínculo do motorista com o cartão da Rodobank.
Cobrar Cartão?: Indica se deverá ser cobrado a taxa de emissão de cartão para o motorista. O padrão é “Sim”.
Os dados aqui informados serão enviados ao PDV para que possam ser utilizados nas operações que envolvem a Rodobank.
Por controles da sincronização, não será possível excluir os motoristas, para que sempre haja esse espelhamento entre PDV e Retaguarda.
Esses dados também podem ser editados pelo PDV, com exceção do campo “Dias p/ Pagamento” e “Tipo do TrocoPay”.
Para o cadastro dos motoristas, a alteração do campo “Cobrar Cartão?” para “Não” precisará de autorização de um usuário com configuração de gerente.
Configurações no Cadastro de Outros e Cartões
No PDV, as operações vinculadas à Rodobank serão feitas através de acertos em Vale/Outros. Para isso, foi criado um campo no cadastro de outros do PSFinanceiro, no menu “Cadastros Específicos » Pagamento em Outros”, chamado “Integra Rodobank?”. Somente os pagamentos em Vale/Outros marcados com essa opção irão ativar as rotinas de integração.
...
Da mesma forma, no cadastro de cartões também foi criado essa configuração, para que no futuro possamos considerar em operações de conciliação.
...
Configuração de Troco em Vale/Outros
Para emissão de TrocoPay pela Rodobank é necessário utilizar troco em outros. Essa operação já existia no Petroshow, sendo ativada através de uma configuração. Ela se encontra no PSFinanceiro, no menu “Cadastros Específicos » Configurações Financeiras”, seção “Configurações Gerais » Vales/Cartas Frete/Outros”, no campo “Permite troco em vale?”. Ao marcar com “Sim” será habilitada essa opção de troco.
...
Essas são as configurações necessárias para que a integração ocorra. Com isso realizado, é possível realizar a sincronização para o PDV para que então sejam utilizadas nos processos afetados.
Operação de TrocoPay no PDV - Cadastros
Tanto na venda como na troca de numerários, quando existir a possibilidade de troco, ao utilizar a opção de troco em vale/outros será aberta a possibilidade de geração do TrocoPay. Para isso, basta informar um código de vale que foi configurado com a opção “Integra Rodobank?” igual a sim.
...
Ao informar o Vale que integra com a Rodobank, será aberta esta tela:
...
Por padrão, já serão carregados os dados do contratado, caso existam. Nessa mesma tela, ao lado do campo “E-mail” existem botões para inclusão e edição dos dados do contratado. As mesmas regras que são aplicadas no cadastro da retaguarda serão aplicados aqui também, e todos os dados lançados serão sincronizados com a retaguarda também.
Para os motoristas, o sistema não carrega nenhuma informação por default, para garantir que o usuário faça a seleção que realmente deseja.
Também existem as funcionalidades de inclusão e edição dos dados que, assim como os contratados, serão sincronizados com a retaguarda.
Na inclusão de motoristas, o campo “Cobrar Cartão?” sempre será preenchido com “Sim”, sendo que é possível solicitar a autorização de um usuário configurado como gerente do posto para que essa configuração seja alterada.
...
Distribuição dos Valores do TrocoPay
Cientes das configurações, é possível que façamos a definição dos valores que serão distribuídos entre o contratado e o motorista.
Para isso, na tela de lançamento do TrocoPay podemos definir separadamente esses valores, sendo que o total não pode ultrapassar o “Valor Pendente” apresentado no rodapé da tela.
...
Após fazer a distribuição dos valores, basta clicar em confirmar que o troco será adicionado na venda/troca de numerários. Mas atenção, nesse momento apenas a definição foi feita, sendo que não houve nenhuma comunicação com os servidores da Rodobank.
Ao informar os demais acertos e então finalizar a venda/troca de numerários é que os dados serão transmitidos para a Rodobank. Quando a venda/troca de numerários estiver no processo de finalização, será apresentado uma mensagem ao usuário informando que os dados estão sendo enviados para a Rodobank.
O PDV tem um comportamento de segurança nesse momento, onde antes de iniciar qualquer comunicação com a Rodobank os dados são todos gravados em banco de dados, e somente após a confirmação dessa gravação o processo é iniciado. Dessa forma garantimos que em uma eventual falha de internet, por exemplo, os dados estão devidamente salvos, podendo serem transmitidos para o retaguarda.
Com isso pronto, o PDV irá enviar os dados para a Rodobank. Com o retorno dado pela API, irá atualizar a transação no banco de dados com as informações obtidas na integração. Caso a Rodobank recuse a transação ou ocorra alguma outra falha inesperada no processo, será exibida uma mensagem em tela para que o usuário fique ciente da situação. Isso não impedirá que a venda/troca de numerários seja finalizada, sendo que o sistema orientará o usuário a tentar novamente pela retaguarda.
Se a transação ocorrer sem nenhum problema, nenhuma mensagem será apresentada e a venda/troca de numerários será finalizada com sucesso.
Ao obter o retorno de sucesso da Rodobank, será atualizado o evento de envio no Petroshow adicionando os campos recebidos da API.
Montagem do JSON para Integração do TrocoPay
A API da Rodobank disponibiliza vários campos para integração. O Petroshow envia alguns deles, e abaixo segue de onde as informações são coletadas:
URL: {{baseUrl}}/trocopay
1 - Dados Gerais:
type: Campo “Tipo do TrocoPay” do cadastro do contratado.
payment_date: Caso o campo “Dias p/ Pagamento” do cadastro do contratado seja 0, será enviado null. Caso tenha valor preenchido, será adicionado essa quantidade de dias à data da venda/troca de numerários.
terminal_fiscal_number: CNPJ do estabelecimento.
2 - Objeto “hired”:
fiscal_number: CNPJ do cadastro da pessoa.
mobile_phone: Telefone informado nos dados do contratado.
car_plate: Placa informada na venda/troca de numerários.
name: Razão social social do cadastro da pessoa.
fantasy_name: Nome fantasia do cadastro da pessoa. Quando não existir envia a razão social.
email: E-mail informado nos dados do contratado.
3 - Objeto “driver”:
mobile_phone: Telefone informado no cadastro do motorista.
cpf: CPF informado no cadastro do motorista.
name: Nome informado no cadastro do motorista.
4 - Objeto “received_payment”:
⚠️Quando citado informações sobre “Pagamento”, será considerado o pagamento de maior valor existente na venda/troca de numerários.
issuer: Fará as validações na seguinte ordem:
Se pagamento em Carta Frete: CNPJ da transportadora.
Se pagamento em Cheque: CNPJ do emitente do cheque.
Se pagamento em Cartão: CNPJ da administradora do cartão, conforme cadastro no PSFinanceiro.
Se existir motorista: CPF do motorista.
Senão: CNPJ conforme cadastro da pessoa.
number: “TV” + Estab + PDV + COO + Seq. Troco. Ex: “TV|1000|5|159332|2”
type: Dinheiro, Cheque, Cartão de Crédito, Cartão de Débito, Carta Frete, Vale/Outros, Conta Pessoal, Duplicata, PIX, Carteira Digital, Bonificação, Brinde ou Nenhum
transaction: Identificação interna da venda/troca de numerários no PDV
Se pagamento em Dinheiro: “DIN” + Estab + PDV + COO + Seq. Pag.
Se pagamento em Cheque: “CHE” + Estab + PDV + COO + Seq. Pag. + Série do Cheque + Número do Cheque.
Se pagamento em Cartão de Crédito: “CRE” + Estab + PDV + COO + Seq. Pag.
Se pagamento em Cartão de Débito: “DEB” + Estab + PDV + COO + Seq. Pag.
Se pagamento em Carta Frete: “CTF” + Estab + PDV + COO + Seq. Pag + Número da Carta Frete
Se pagamento em Vale/Outros: “OUT” + Estab + PDV + COO + Seq. Pag.+ Identificação do Vale/Outros.
Se pagamento em Conta Pessoal: “CMV” + Estab + PDV + COO + Seq. Pag.
Se pagamento em Duplicata: “DUP” + Estab + PDV + COO + Seq. Pag. + Número da Duplicata.
Se pagamento em PIX: “PIX” + Estab + PDV + COO + Seq. Pag.
Se pagamento em Carteira Digital: “CDG” + Estab + PDV + COO + Seq. Pag.
Se pagamento em Bonificação: “BON” + Estab + PDV + COO + Seq. Pag.
Se pagamento em Brinde: “BRI” + Estab + PDV + COO + Seq. Pag.
Senão: “NIF” + Estab + PDV + COO + Seq. Pag.
amount: Soma de todos os pagamentos da venda/troca de numerários.
card_discount: Caso o campo “Cobrar Cartão?” do cadastro do motorista seja “Sim”, envia true, senão envia false.
5 - Objeto “payment_split”:
...
driver_card_identifier: Código de ativação do cartão do cadastro do motorista.
...
hired_change: Valor informado para troco ao contratado.
...
driver_change: Valor informado para troco ao motorista.
...
cash: Valor do pagamento em dinheiro da venda/troca de numerários.
⚠️ Os demais campos e objetos não citados serão enviados com null.
Cancelamento de TrocoPay
Ao cancelar uma venda ou troca de numerários que teve TrocoPay, a operação também será cancelada na Rodobank.
Esse processo é automático, não dependendo de nenhuma ação do usuário. Após concluir o cancelamento no Petroshow, o sistema irá levantar as informações dos acertos e, caso identificado que houve TrocoPay na operação, fará o cancelamento. Ao realizar estorno de vendas no PDV esse processo também é feito.
O procedimento de segurança adotado é o mesmo que no envio do TrocoPay, ou seja, primeiro grava os dados em banco para só depois comunicar com a Rodobank, e então obter os devidos retornos.
Caso ocorram falhas no processo, a operação não será bloqueada, sendo que apenas será apresentada mensagem ao usuário solicitando que tente novamente pela retaguarda.
Ao obter o retorno de sucesso da Rodobank, será atualizado o evento de cancelamento no Petroshow adicionando os campos recebidos da API.
⚠️ O cancelamento só será transmitido para a Rodobank caso a transação de envio do TrocoPay esteja com o status de sucesso, pois é necessário o trocopay_id retornado para realizar o cancelamento.
Montagem do JSON para Cancelamento do TrocoPay
URL: {{baseUrl}}/trocopay/cancel
O JSON de cancelamento do TrocoPay é mais simples, onde enviamos as seguintes informações:
trocopay_id: Código do TrocoPay recebido no momento do envio.
is_total: Sempre será enviado True.
cancelled_by: Operador que solicitou o cancelamento.
login: Usuário de cancelamento definido nas configurações do PDV.
password: Senha de cancelamento definido nas configurações do PDV.
Validação de Voucher/Token do Motorista
Em alguns casos, será possível que o motorista gere um voucher pelo aplicativo para efetuar um pagamento no posto, descontando o saldo da conta dele.
Essa operação também será feita com Vale/Outros. Para isso, na tela de pagamentos do PDV, ao informar um Vale/Outros que integra com a Rodobank, o PDV terá o seguinte comportamento:
Será zerado e bloqueado o campo “Valor”, pois será utilizado o valor retornado pela Rodobank.
Será valorizado com 1 e bloqueado o campo “Qtd. Parcelas”.
O campo “Identificação” passará a se chamar “Voucher”, e será de preenchimento obrigatório.
Será habilitado um botão chamado “Validar Voucher”.
...
Ao clicar em “Validar Voucher” o sistema irá chamar a API da Rodobank para validar se o voucher é válido e também obter o valor, atualizando o campo “Valor”. Depois de validar não será possível alterar o número do voucher, pois é ele quem identifica a operação e justifica o valor informado.
Feito isso, pode ser adicionado o pagamento na venda, mas neste momento ele ainda não foi descontado da conta do motorista.
Montagem do JSON para Validação do Voucher
URL: {{baseUrl}}/GetVoucher
token_code: Voucher informado na tela de pagamento, gerado pelo motorista.
Geração de Vendas com Voucher
Ao finalizar vendas/trocas de numerários onde for identificado o pagamento em voucher da Rodobank, será feita a comunicação com a API da Rodobank nos mesmos moldes da geração do TrocoPay, onde será enviado o Voucher para que seja de fato descontado do motorista.
Como mencionado para outras transações, esse ponto também conta com controles de segurança e registro de todas as operações em banco de dados para posterior consulta e manutenção.
Montagem do JSON para Registro de Venda na Rodobank.
URL: {{baseUrl}}/NewSale
token_code: Voucher informado na tela de pagamento, gerado pelo motorista.
total_products_amount: Total dos produtos da venda ou total dos pagamentos da troca de numerários.
cash_change_amount: Total de troco em dinheiro
terminal_fiscal_number: CNPJ do estabelecimento.
Sincronização e Manutenção na Retaguarda
Toda operação de integração realizada no PDV é sincronizada para o retaguarda.
A estrutura conta com duas tabelas principais, onde uma armazena todas as informações necessárias para a montagem dos JSON’s de integração, e a outra armazena eventos de cada comunicação/falha com a API da Rodobank. Para manutenção desses dados, foi criado no PSGerencial o menu “Cadastros Específicos » Transações Rodobank”.
Ao abrir a tela é apresentado a possibilidade de alguns filtros, e na sequência um grid com as principais informações. Abrindo o cadastro, serão apresentadas todas as informações utilizadas para a integração, bem como todos os eventos de comunicação com a rodobank.
Quando a transação for de TrocoPay, serão habilitadas as abas com informações do Contratado, Motorista, Recebimentos, e também informações sobre o próprio TrocoPay. No caso de operações de pagamento com Voucher, apenas a aba de Eventos e “Vendas (Voucher)” serão apresentadas.
Nessa rotina, além de consultar os dados é possível realizar operações de envio e cancelamento, de acordo com cada operação. Diante disso, em casos de falha nas operações do PDV, através desse cadastro é possível ajustar o que está faltando e fazer o novo envio.
Outras Informações Importantes
No PDV, cada comunicação feita com os servidores da Rodobank vão gravar logs de envio e retorno. Para não gerar muitos arquivos, o PDV criará uma pasta chamada “Rodobank” dentro da pasta de log padrão, a LogPDV. Dentro dela, criará um arquivo por dia contendo as transações realizadas, gravando dados de qual URL foi chamada, o que foi enviado e o que foi retornado.
...
Para mais informações, consulte as tarefas envolvidas no processo:
Epic PS-5600 - Integração com a Rodobank
PS-5607 - Rodobank - Criação de Estrutura para Integração
PS-5609 - Rodobank - Campos no Retaguarda para Configurações da Integração
PS-5613 - Rodobank - Realizar a Integração de Troco em Outros
PS-5614 - Rodobank - Realizar a Integração de Acerto em Outros
PS-5615 - Rodobank - Habilitar Troco em Outros na Troca de Numerários
PS-5618 - Rodobank - Rotina para Monitoramento e Ações sobre Transações