...
...
...
| default | true |
|---|
| label | Escopo Funcional / Manual |
|---|
Cadastro de plugin de integração "TOTVS Pagamento Instantâneo"
...
...
Image Removed
Ao clicar no botão "Configurar", é aberto a tela de configurações, contendo os as informações:
Image Removed
- Título "TOTVS Pagamento Instantâneo"
- Grupo de elementos "Configurações do TPI"
- Tenant URL: campo de texto, para receber a URL em que a API do TOTVS Pagamento Instantâneo (TPI) estará sendo servida (Ex: https://produtosfa.rac.staging.totvs.app)
- Usuário: campo de texto, para receber o usuário da autenticação básica do TPI
- Senha: campo de texto, com máscara de password, para receber a senha da autenticação básica do TPI
- Client ID: campo de texto, para receber o identificador do sistema solicitante da requisição
- Cliente secret: campo de texto, com máscara de password, para receber o a senha do sistema solicitante da requisição
- Carteira: campo de texto, para receber o código da carteira digital. Para o pix, terá o identificador "pix"
- Business Unid ID: campo de texto, para receber o identificador da unidade de negócio geradora de transações de pagamento
- POS ID: campo de texto, para receber o identificador do ponto de venda cadastrado
- Grupo de elementos "Configurações do SFA"
- Tipos de Cobrança: Campo pesquisa multipla escolha, buscando todos os tipos de cobrança ativos. Esse campo receberá os tipos de cobrança que, ao selecionados no cabeçalho do pedido, dispararão a requisição da transação de pagamento.
- Timeout ao gerar transação: Campo numérico para determinar a quantidade de segundos que o sistema aguardará o retorno da criação da transação
- Timeout consulta pagamento: Campo numérico para determinar quantos segundos o sistema irá aguardar para a consulta de pagamento.
Configuração de envio de e-mail para contexto "Plugin TOTVS Pagamento Instantâneo"
Neste momento, o cliente pode receber as informações do processo de pagamento por Cartão de crédito e PIX por e-mail disparado pelo próprio Totvs CRM SFA através da conta de e-mail configurada na ferramenta. Nos tópicos a seguir, iremos detalhar como será o comportamento para cada modelo.
Estas configurações são acessadas somente por usuários administradores e deve estar localizada em: Configuração > Email > Configuração de envio.
Image Removed
Campo que permite selecionar o contexto “Plugin TOTVS Pagamento instantâneo”. Este contexto permitirá que seja configurado um envio de e-mail que tem relação com o processo de pagamento com pix.
O contexto “Plugin TOTVS Pagamento instantâneo ” somente será apresentado quando a configuração do plugin TOTVS Pagamento Instantâneo também estiver ativo (pluginintegracao.idnativo = 1)
Campo que permite selecionar o registro chamado “Envio de QR Code PIX - sob demanda”. O propósito desta configuração é enviar o link de pagamento gerado pela TOTVS Pagamento instantâneo conforme a solicitação do usuário responsável pelo pedido. Ou seja, é necessário que o usuário acione o botão de enviar na tela de QR Code para que essa configuração seja executada. E com isso a aplicação encaminha um e-mail ao(s) destinatário(s) conforme as configurações informadas.
Campo que permita anexar um modelo de relatório nos e-mails enviados. Podendo ser o espelho do pedido, ou um resumo do pedido entre outras possibilidades de relatório no formato PRPT.
Campo que permite definir quem receberá o e-mail:
- Cliente
- Profissional logado
- Profissional selecionado no cabeçalho
- Profissional supervisor do selecionado no cabeçalho
É possível também selecionar o campo check-box de "Exibir tela de confirmação/edição de e-mail" com label de "Permitir editar e-mails de contexto na tela de confirmação de e-mail".
...
| Deck of Cards |
|---|
|
| Card |
|---|
| default | true |
|---|
| label | Escopo Funcional / Manual |
|---|
| Configuração do PluginNa tela de Plugins de integração acessado em Configuração > Integração, o sistema disponibiliza um card de nome "TOTVS Pagamento Instantâneo" para ativar o recurso. Ao clicar no botão "Configurar", é aberto a Tela de configurações do TOTVS Pagamento instantâneo. Informe cada campo conforme a configuração detalhada a seguir: | Configuração do TPI |
|---|
| Tenant | Informe a URL em que a API do TOTVS Pagamento Instantâneo (TPI) estará sendo servida (Ex: https://produtosfa.rac.staging.totvs.app) | | Usuário | Informe o Usuário da autenticação básica do TPI | | Senha | Informe a senha da autenticação básica do TPI | | Client ID | Informe o identificador do sistema solicitante da requisição | | Client secret | Informe a senha do sistema solicitante da requisição | | Carteira | Informe o código da carteira digital. Para o pix, terá o identificador "pix" | | Business unit ID | Informe o identificador da unidade de negócio geradora de transações de pagamento | | POS ID | Informe o identificador do ponto de venda cadastrado |
| Configuração do SFA |
|---|
| Tipos de cobrança | Selecione os Tipos de cobrança que serão utilizados para disparar a requisição da transação de pagamento. | | Timeout ao gerar transação | Campo que determina a quantidade de segundos que o sistema aguardará o retorno da criação da transação | | Timeout consulta pagamento | Campo que determina quantos segundos o sistema irá aguardar para a consulta de pagamento. |
Após essa configuração, o Plugin já está passível de utilização na Aplicação. Configuração de envio de e-mail para contexto "Plugin TOTVS Pagamento Instantâneo"É importante que o usuário realize a configuração de e-mail para envio do QRCode, assim o cliente do Pedido poderá receber as informações do processo de pagamento por PIX por e-mail disparado pelo próprio Totvs CRM SFA através da conta de e-mail configurada na ferramenta. Nos tópicos a seguir, é detalhar como será o comportamento para cada modelo. Estas configurações são acessadas somente por usuários administradores e deve estar localizada em: Configuração > Email > Configuração de envio. Image Added
ContextoCampo que permite selecionar o contexto “Plugin TOTVS Pagamento instantâneo”. Este contexto permitirá que seja configurado um envio de e-mail que tem relação com o processo de pagamento com pix. O contexto “Plugin TOTVS Pagamento instantâneo ” somente será apresentado quando a configuração do plugin TOTVS Pagamento Instantâneo também estiver ativo (pluginintegracao.idnativo = 1) Condição para envio Campo que permite selecionar o registro chamado “Envio de QR Code PIX - sob demanda”. O propósito desta configuração é enviar o link de pagamento gerado pela TOTVS Pagamento instantâneo conforme a solicitação do usuário responsável pelo pedido. Ou seja, é necessário que o usuário acione o botão de enviar na tela de QR Code para que essa configuração seja executada. E com isso a aplicação encaminha um e-mail ao(s) destinatário(s) conforme as configurações informadas. Arquivo do relatórioCampo que permita anexar um modelo de relatório nos e-mails enviados. Podendo ser o espelho do pedido, ou um resumo do pedido entre outras possibilidades de relatório no formato PRPT. Enviar para (Contexto)Campo que permite definir quem receberá o e-mail: - Cliente
- Profissional logado
- Profissional selecionado no cabeçalho
- Profissional supervisor do selecionado no cabeçalho
É possível também selecionar o campo check-box de "Exibir tela de confirmação/edição de e-mail" com label de "Permitir editar e-mails de contexto na tela de confirmação de e-mail". - Caso o parâmetro estiver marcado, os e-mails selecionados no contexto não poderão ser editados na tela de confirmação de envio.
- Caso o parâmetro estiver desmarcado, os e-mails selecionados no contexto serão pré-preenchidos como sugestão, e podem ser editados na tela de confirmação de envio.
- Deverá ser persistida em campo configuracaoenvio.idneditaemail, byte default 0, que deverá ser criado pelo tools, opção 3.
Assunto Será adicionado este campo que deve permitir configurar um assunto padrão de envio nos e-mails que tratam deste processo de pagamento com cartão de crédito. Também será possível adicionar uma TAG dentro deste assunto, que irá fazer com que a aplicação troque a TAG do assunto pelo número do pedido referente ao processo de pagamento de cartão de crédito. Desta forma, o cliente quando receber o e-mail, já irá conseguir ver através do assunto qual a numeração que se trata. |
|
...
Configuração do corpo do e-mail Neste campo é possível configurar um corpo do e-mail personalizado para este tipo de situação. Onde o usuário cria um template de e-mail para que fique alinhado com o cliente e dar mais credibilidade ao processo. A seguir um protótipo de como ficará essa parte da configuração: Neste campo é exibido as tags: - "NÚMERO DO PEDIDO” - Se o usuário incluir essa tag no corpo, ao enviar o e-mail será substituído pelo número do pedido em questão.
- “IMAGEM QR CODE” - Se o usuário incluir essa tag no corpo, ao enviar o e-mail será substituído pela imagem do QR Code gerada pela TPI (pedidopagamento.imagem)
- "PIX COPIA E COLA" - Se o usuário incluir essa tag no corpo, ao enviar o e-mail será substituído pelo código do QR Code gerado pela TPI. (pedidopagamento.codigotransacao)
Pagamento instantâneo por PIX no |
|
...
Pedido de Venda
Após a configuração realizada nos pontos acima, o Pedido de venda já estará pronto para realizar o processo gerando essa forma de pagamento em QRCode. Assim, ao confeccionar um pedido de venda no SFA, contanto que o campo "Tipo de cobrança" do cabeçalho do pedido esteja vinculado com o plugin de integração "TOTVS Pagamento Instantâneo |
|
...
", o sistema irá disparar a seguinte lógica de funcionamento; Ao finalizar um pedido, contato que não haja aprovações pendentes para o pedido, o sistema |
|
...
realiza a solicitação do QR code para pagamento junto à TOTVS Pagamento Instantâneo, respeitando o tempo do campo "Timeout ao gerar transação". Quando a requisição for bem sucedida, o sistema |
|
...
exibe em tela o QR Code (pedidopagamento.imagem), juntamente com o código do "PIX copia e cola"(pedidopagamento.codigopagamento), armazenando a informação vinculado ao pedido de venda (processorTransactionId) (pedidopagamento.tokentransacao). Caberá ao usuário vendedor compartilhar a informação para pagamento. |
|
...
Por exemplo, ao finalizar o pedido normalmente: Image Modified
|
|
...
Logo em seguida é exibido em tela o tempo de requisição do Plugin TOTVSPagamento Instantâneo para gerar o QRCode do pagamento: Image Modified
Assim que o pagamento é gerado, é exibido em tela a as opções de leitura do QRCode, |
|
...
Cancelar o pagamento, Enviar via email e Finalizar o pagamento: Image Modified
Quando o pagamento é realizado no tempo dentro do tempo determinado nas configurações, é exibido em tela a mensagem de |
|
...
"Pagamento aprovado": Image Modified
O mesmo processo é realizado no Android, e ocorre da seguinte forma: |
|
Image Removed
Image Removed
Image Removed
Image Removed
Caso a geração do QR Code não seja bem sucedida, por qualquer que seja o motivo, o sistema exibe a mensagem:
Image Removed
...
Image Added Image Added Image Added Image Added
Enviando o QR Code por E-mailSe a configuração de envio de e-mail de contexto "Plugin TOTVS Pagamento Instantâneo" estiver ativa, o sistema exibirá botão "Enviar" com ícone de envelope, para enviar o QR Code por e-mail ao cliente. Na web: Image Added Image Added Image Added
No Android: Image Added Image Added Image Added
Ao clicar no botão enviar, o sistema |
|
...
exibe os e-mails trazidos pelo contexto da configuração de e-mail, respeitando o que foi definido na flag "Não permitir editar e-mails de contexto na tela de confirmação de envio", porém |
|
...
também da a possibilidade de o usuário adicionar novos e-mails para receber o QR Code. Dessa forma, ainda que o e-mail do cadastro não esteja correto, o usuário tem a oportunidade de colocar o e-mail correto para recebimento do QR Code. |
|
...
Nestes casos que o envio do QR Code é realizado por e-mail, o sistema seguirá realizando a consulta de pagamento de 10 em 10 segundos no servidor, até que obtenha um resultado diferente de PENDENTE do servidor de pagamentos da TPI. E assim como no exemplo anterior, o servidor responde |
|
Image Removed ou
Image Removed
- Se a flag "Não permitir editar e-mails de contexto na tela de confirmação de envio" estiver marcada, o ícone de "X para excluir e-mail" não deve ser exibido para e-mails que vieram do cadastro da configuração de envio.
- Caso contrário, o sistema deverá exibir o ícone de "X para excluir e-mail" em todos os e-mails da tela
O sistema deverá realizar a consulta de pagamento de 10 em 10 segundos no servidor, até que obtenha um resultado diferente de PENDENTE do servidor de pagamentos da TPI.
...
que o pagamento está aprovado, o sistema |
|
...
exibe a mensagem de "Pagamento aprovado. Pedido finalizado com sucesso." |
|
...
Dessa forma, o pedido será finalizado e o status de pagamento (pedidopagamento.idtiposituacaopagamento, onde sgltiposituacaopagamento="APR") será atualizado para APROVADO. |
|
...
Mensagens de alerta ao gerar o PagamentoNos casos de alguma inconsistência no processo, é sempre alertado ao usuário em tela sobre o procedimento, por exemplo: Caso a geração do QR Code não seja bem sucedida, por qualquer que seja o motivo, o sistema exibe a mensagem: Image Added
Caso o servidor responda que o pagamento está expirado ou cancelado, o sistema irá |
|
...
exibe a mensagem de "Pagamento expirado/cancelado. Finalize o pedido novamente para gerar um novo pagamento". Dessa forma, o pedido não será finalizado, e o status de pagamento |
|
...
é atualizado para o código de retorno (cancelado (sgl CAN)/expirado (sgl EXP)). O sistema |
|
...
respeita o tempo máximo de consulta de status de pagamento, segundo o parâmetro "Timeout consulta pagamento". Quando o tempo de requisição de pagamento ultrapassar o tempo definido no campo de timeout, o usuário será notificado: "Pedido finalizado com sucesso! Entretanto, o pagamento precisa ser aprovado para que o pedido seja devidamente encaminhado para faturamento". Dessa forma, o pedido |
|
...
é finalizado e o status de pagamento permanecerá como PENDENTE. Caso a resposta não seja bem sucedida, por qualquer motivo o sistema |
|
...
notificado o usuário. Botão CancelarComo visto no exemplo anterior, o sistema também disponibiliza |
|
...
o botão "Cancelar", que, ao clicado, |
|
...
exibe uma mensagem de confirmação para o usuário: "A ação irá cancelar o QR Code, que não poderá mais ser pago. Deseja prosseguir?" Sim/não. Image Added
Se sim, |
|
...
é disparado uma requisição de cancelamento do QR Code para o servidor do TPI. Caso a resposta seja bem sucedida, o sistema |
|
...
irá notificar o usuário: "Pagamento cancelado com sucesso. Finalize o pedido novamente para gerar um novo pagamento". Dessa forma, o pedido não será finalizado, e o status de pagamento deverá ser atualizado para cancelado(sgl CAN). Image Added
Caso a resposta não seja bem sucedida, o sistema deverá notificar o usuário: "Pagamento não pode ser cancelado |
|
...
. Tente novamente mais tarde ou entre em contato com o suporte técnico" |
|
...
Botão FinalizarComo visto no exemplo anterior, o sistema também disponibiliza |
|
...
o botão "Finalizar", que, ao clicado, |
|
...
notifica o usuário: "Pedido finalizado com ressalva! O pedido precisa ter seu pagamento aprovado para ser encaminhado para faturamento. Você será notificado automaticamente das atualizações, porém pode consultar instantaneamente o status do pagamento pela tela de pagamentos do pedido". Dessa forma, o pedido será finalizado e o status de pagamento permanecerá como PENDENTE (sgl PEND). |
|
...
Image Added
Acompanhamento |
|
...
das Operações de pagamento após a finalização do pedidoApós a finalização do pedido, o sistema |
|
...
...
Status de pagamento" na listagem de pedidos, e também no "Roda teto" do pedido, exibindo o status do último registro de pagamento vinculado ao pedido. Os status possíveis são: - PENDENTE: com ícone de "alerta amarelo", o status representa o pagamento gerado mas com pagamento ainda pendente de aprovação
- APROVADO: com ícone de "check verde", o status representa o pagamento já validado no servidor como aprovado.
- CANCELADO: com ícone "X vermelho", o status representa o pagamento que foi cancelado pelo operador.
- EXPIRADO: com ícone de "ampulheta", o status representa o pagamento que não foi pago a tempo, e teve seu registro expirado pelo servidor de pagamento.
- REEMBOLSADO: com ícone de "dinheiro amarelo", o status representa o pagamento que tinha sido aprovado, mas foi reembolsado ao pagador.
Ao clicar no ícone de "Pagamentos" |
|
...
relacionado ao pedido, o sistema |
|
...
...
Image Removed
Image Removed
Image Removed
Image Removed
Image Removed
Image Removed
Image Added
Também exibido na aplicação Mobile. No Android, a consulta dos registros será online, para garantir que os dados sempre estejam atualizados. Caso não seja possível realizar a conexão online, o sistema deverá mostrar a data de atualização como a data da ultima sincronização. Image Added Image Added
Os campos |
|
...
de informações disponíveis no card, são: - Identificador transação: identificador do token que será o mesmo identificador exibido na plataforma da TOTVS Pagamento Instantâneo.
|
|
...
- Ao clicar sobre o conteúdo, o sistema
|
|
...
- copia o identificador para a área de transferência do dispositivo, e disparar uma mensagem toast: "Copiado para área de transferência"
- Status pagamento: além do ícone,
|
|
...
- exibe o nome do status de pagamento conforme possibilidades supracitadas.
- Data criação: Data de criação da transação no servidor de pagamento.
- Data última atualização: Data referente à última observação do pagamento
Botões de ação Image Added
Botão Histórico do pagamento |
|
...
...
exibe tela conforme o protótipo a seguir, exibindo o conteúdo textual da tabela de observações de pagamento, para acompanhamento do histórico. |
|
...
Image Added
|
|
Image Removed
...
Ícone que, ao clicado, consultará no banco para retornar a imagem e conteúdo do QR code para pagamento. Nessa tela, as opções de "Cancelar" e "Cobrar depois" não serão exibidas, somente a função "Enviar e-mail". O timer de consulta de pagamento também não será disparado. Caso a resposta não seja bem sucedida, por qualquer motivo o sistema deverá notificar o usuário: "Pagamento não pôde ser criado no servidor do {nome do plugin}, cuja resposta foi: ${resposta da requisição}. ". Caso não houver mensagem de retorno, o sistema deverá exibir: "Pagamento não pôde ser criado no servidor do {nome do plugin}. Tente novamente mais tarde ou entre em contato com o suporte técnico" Image Added
Botão Consultar pagamento |
|
...
Ícone que, ao clicado, fará uma requisição ao servidor do TPI para retornar o status atual do pagamento. Image Added Caso o servidor responda que o pagamento está aprovado, o sistema irá exibir mensagem toast de "Pagamento aprovado" Dessa forma, o status do pagamento será atualizado para APROVADO. Caso o servidor responda que o pagamento está expirado, o sistema irá exibir mensagem toast de "Pagamento expirado" Dessa forma, o status do pagamento será atualizado para EXPIRADO. Caso o servidor responda que o pagamento está cancelado, o sistema irá exibir mensagem toast de "Pagamento cancelado" Dessa forma, o status do pagamento será atualizado para CANCELADO. Caso o servidor responda que o pagamento está reembolsado, o sistema irá exibir mensagem toast de "Pagamento reembolsado" Dessa forma, o status do pagamento será atualizado para REEMBOLSADO. Caso o servidor responda que o pagamento está pendente, o sistema irá exibir a mensagem toast de "Pagamento pendente" Caso a resposta não seja bem sucedida, por qualquer motivo, o sistema deverá notificar o usuário: "Pagamento não pôde ser consultado no servidor do {nome do plugin}, cuja resposta foi: ${resposta da requisição}.". Caso não houver mensagem de retorno, o sistema deverá exibir: "Pagamento não pôde ser consultado no servidor do {nome do plugin}. Tente novamente mais tarde ou entre em contato com o suporte técnico" Botão Cancelar pagamento |
|
...
Ícone que, ao clicado, deverá exibir mensagem de confirmação para o usuário: "A ação irá cancelar o QR Code, que não poderá mais ser pago. Deseja prosseguir?" Sim/não. Se sim, fará uma requisição ao servidor do TPI para cancelar o pagamento. Image Added
Caso a resposta seja bem sucedida, o sistema |
|
...
irá notificar o usuário: "Pagamento cancelado com sucesso. Finalize o pedido novamente para gerar um novo pagamento". Dessa forma, o status do pedido será atualizado para Não finalizado, e o status de pagamento deverá ser atualizado para |
|
...
cancelado(sgl CAN). Image Added Caso a resposta não seja bem sucedida, o sistema deverá notificar o usuário: "Pagamento não pode ser cancelado no servidor do {nome do plugin}, cuja resposta foi: ${resposta da requisição}. ". Caso não houver mensagem de retorno, o sistema deverá exibir: "Pagamento não pôde ser criado no servidor do {nome do plugin}. Tente novamente mais tarde ou entre em contato com o suporte técnico" |
|
...
...
É exibido sempre que não houver a presença de nenhum pagamento com status APROVADO ou PENDENTE, para pedidos de origem Web/Android, sem numeropedidoerp, de status PENDENTE.
Esse botão, quando clicado, fará a criação de nova transação junto à TPI, e exibir o conteúdo do QR code, em tela semelhante ao resultado do ícone "Exibir QR code"
|
|
...
Este botão "Novo pagamento" foi refatorado e não faz mais parte do processo. Agora sempre que o pagamento PIX for CANCELADO, o pedido volta para não finalizado e o usuário precisa finalizar novamente para que comunique com a API e gere um novo QRCode. Essa prática foi vista como mellhor aderida ao processo e impede possíveis erros de geração de QRcode, mesmo da API quanto do usuário.
Fluxo de pagamento quando há aprovações de pedidosAo finalizar um pedido com tipos de cobrança vinculados com o plugin de integração TPI, em que o mesmo seja encaminhado para aprovação, qualquer que seja, o sistema não |
|
...
realiza a criação do pagamento. Ao invés, |
|
...
informa o usuário com a seguinte mensagem: "A geração do pagamento do pedido deverá ser gerada após a aprovação do pedido, para que seja devidamente encaminhado para faturamento." Nesse cenário, o pedido |
|
...
passa pelo fluxo de aprovação padrão, onde os usuários determinarão a situação das aprovações do pedido |
|
...
PENDENTE
APROVADO
REPROVADO
CONTESTADO
CANCELADO
...
. Um pedido é declarado totalmente aprovado quando apenas possui aprovações vinculadas nos status de APROVADO ou CANCELADO. |
|
Além dos filtros definidos no ponto 3, o botão "Novo pagamento" na tela de "Pagamento do pedido" somente deve ser exibido para pedidos com as situações acima, ou não contendo aprovações vinculadas.
Isso para permitir que, após aprovado, o usuário tenha que clicar no botão "Novo pagamento" para gerar um QR Code, compartilhar ao seu cliente, e posteriormente consultar pagamento pelo ícone "Consultar pagamento".
Na notificação que é gerada pela aplicação quando o pedido é aprovado, o sistema deve consultar se o plugin "TOTVS Pagamento instantâneo" está ativo e o pedido está vinculado com um dos tipos de cobrança configurados no plugin. Se positivo, o sistema deverá adicionar a mensagem "Será necessário gerar um pagamento para o pedido X através da tela de "Pagamentos do pedido""
...
Na notificação que é gerada pela aplicação quando o pedido é aprovado, o sistema deve consultar se o plugin "TOTVS Pagamento instantâneo" está ativo e o pedido está vinculado com um dos tipos de cobrança configurados no plugin. Se positivo, o sistema deverá adicionar a mensagem "Será necessário gerar um pagamento para o pedido X através da tela de "Pagamentos do pedido"" Image Added
Após aprovação do pedido, é então exibido o ícone de Pendente para pagamentos e permitirá a finaliza'xão do pedido gerando um novo QrCode. Desta forma o pagamento vai ser gerado também para pedidos que passam pelo fluxo de Aprovação Persistência e integração de dados de pagamentoA presente documentação apenas define que os tokens de pagamento serão armazenados em banco de dados do SFA, vinculados com os pedidos de venda. A integração de dados de pagamento com o ERP deverá ocorrer sob demanda, de maneira configurável ou customizada, mediante identificação dos campos de destino pelo cliente que utiliza o plugin de integração.
|
| Card |
|---|
| Detalhamento técnico - Comportamento - Pelo tools, opção 5 é inserido um registro na tabela "pluginintegracao" com código "TOTVS_PAG".
- Pelo tools, opção 3, o sistema
|
|
...
- cria a tabela pedidopagamento, com os seguintes campos:
- idpedidopagamento: PK
- idpedido: FK para tabela pedido, not-null
- datahoracriacao: timestamp, not-null
- datahoraultatualizacao: timestamp, nullable
- tokentransacao: varchar(200), not-null
- idtiposituacaopagamento: FK para tabela tiposituacaopagamento, not null
- valor: decimal (18,6), not-null
- imagem: bytea, nullable
- link: varchar(200), nullable
- codigopagamento: varchar(200), nullable
- codigoerp: varchar(80), nullable
- Pelo tools, opção 3, o sistema
|
|
...
- cria a tabela tiposituacaopagamento, com os seguintes campos:
- idtiposituacaopagamento: PK
- sgltiposituacaopagamento: varchar(10), not-null
- descricao: varchar(80), not-null
- idnativo, byte, not null, default 1
- codigoerp: varchar(80), nullable
- Pelo tools, opção 3, o sistema
|
|
...
- cria a tabela observacaopagamento, com os seguintes campos:
- idobservacaopagamento,
- observacao: varchar(4000) not null
- idpedidopagamento: FK para tabela pedidopagamento, not-null
- idtiposituacaopagamento: FK para tabela tiposituacaopagamento, not-null
- idusuario: FK para tabela usuário, not-null
- datahora: timestamp, not-null
- codigoerp: varchar(80), nullable
- Pelo tools, opção 5, o sistema
|
|
...
- cria os seguintes registros na tabela tiposituacaopagamento:
- sgltiposituacaopagamento: "PEND"
- descricao: "Pendente"
- idnativo: 1
|
|
...
- sgltiposituacaopagamento: "APR"
- descricao: "Aprovado"
- idnativo: 1
|
|
...
- sgltiposituacaopagamento: "EXP"
- descricao: "Expirado"
- idnativo: 1
|
|
...
- sgltiposituacaopagamento: "REEMB"
- descricao: "Reembolsado"
- idnativo: 1
- sgltiposituacaopagamento: "CAN"
- descricao: "Cancelado"
- idnativo: 1
- Ao finalizar o pedido, a aplicação
|
|
...
- realiza uma requisição GET para a rota ${"Cadastro de plugin TPI"."Configurações do Pentaho"."URL"}/kettle/executeJob?rep=COMMON_SERVICES&job=COMMONS_Bloco_TPIGENERATEPAYMENT&idpedido=${pedido.idpedido}
- Autenticação básica com {"Cadastro de plugin TPI"."Configurações do Pentaho"."Usuário"} e {"Cadastro de plugin TPI"."Configurações do Pentaho"."Senha"}
- O retorno da rota será:
- codigotransacao
- imagempagamento
- codigopagamento
- valor
- Enquanto o retorno da request estiver sendo aguardado, na tela,
|
|
...
- exibe um timer segundo o que foi configurado em ${"Cadastro de plugin TPI"."Configurações do SFA"."Timeout ao gerar transação"}
- Após o timer zerar, o sistema
|
|
...
- notifica o usuário que "Pagamento não pôde ser criado no servidor do {nome do plugin}. Tente novamente em breve ou entre em contato com o suporte"
- Ao receber o QR Code de maneira bem sucedida, o sistema
|
|
...
- realiza a persistência da tabela pedidopagamento, segundo o de-para a seguir:
- idpedidopagamento: PK sequencial
- datahoracriacao: current_timestamp
- datahoraultatualizacao: current_timestamp
- tokentransacao: retorno.codigotransacao
- idtiposituacaopagamento: id de sgl "PEND"
- valor: retorno.valor
- imagem: retorno.imagempagamento
- link: null
- codigopagamento: retorno.codigopagamento
|
|
...
- Persiste também, registro na tabela observacaopagamento, com os campos:
- observacao: Pagamento de ID ${pedidopagamento.tokentransacao} criado.
Código do pix copia e cola: ${retorno.codigopagamento} - idpedidopagamento: id do registro persistido acima
- idtiposituacaopagamento: id de sgl "PEND"
- idusuario: id do usuário logado
- datahora: current_timestamp
Após a consulta do QR code, o sistema |
|
...
realiza a consulta de pagamento de 10 em 10 segundos no servidor, até que obtenha um resultado diferente de PENDENTE do servidor de pagamentos da TPI. - Requisição GET para a rota ${"Cadastro de plugin TPI"."Configurações do Pentaho"."URL"}/kettle/executeJob?rep=COMMON_SERVICES&job=COMMONS_Bloco_TPIGETSTATUS&codigotransacao=${pedidopagamento.tokentransacao}
- Autenticação básica com {"Cadastro de plugin TPI"."Configurações do Pentaho"."Usuário"} e {"Cadastro de plugin TPI"."Configurações do Pentaho"."Senha"}
- O retorno da rota será:
- status: retorno.status
- Os possíveis valores da resposta serão:
|
|
...
pendente de aprovação approved:
|
|
...
aprovado pagamento expired:
|
|
...
...
...
- Enquanto o status de pagamento estiver sendo retornado como pendente, na tela, deverá ser exibido um timer segundo o que foi configurado em ${"Cadastro de plugin TPI"."Configurações do SFA"."Timeout consulta pagamento"}
- Após o timer zerar, o sistema deverá
- Substituir a label "PIX aguardando pagamento" por "Pagamento não confirmado"
- O texto "O pedido será finalizado quando o pagamento for confirmado" para "Clique em finalizar para pagamento posterior"
Caso o servidor responda que o pagamento está aprovado, o sistema irá exibir mensagem de "Pagamento aprovado. Pedido finalizado com sucesso.". Dessa forma, o pedido será finalizado e o status de pagamento (pedidopagamento.idtiposituacaopagamento,
|
|
...
onde sgltiposituacaopagamento="APR") será atualizado para APROVADO. - Deverá ser alterado o campo pedidopagamento.datahoraultatualizacao
- Deverá ser persistido um registro em observacaopagamento, com a mensagem: "Pagamento aprovado", e idtiposituacaopagamento de sgl "APR"
Caso o servidor responda que o pagamento está expirado ou cancelado, o sistema irá exibir a mensagem de "Pagamento expirado/cancelado. Finalize o pedido novamente para gerar um novo pagamento". Dessa forma, o pedido não será finalizado, e o status de pagamento deverá ser atualizado para o código de retorno (cancelado (sgl CAN)/expirado (sgl EXP)). - Deverá ser alterado o campo pedidopagamento.datahoraultatualizacao
- Deverá ser persistido um registro em observacaopagamento, com a mensagem: "Pagamento expirado/cancelado", e idtiposituacaopagamento de sgl "CAN" ou "REEMB", dependendo do retorno
O sistema
|
|
...
- Requisição GET para a rota ${"Cadastro de plugin TPI"."Configurações do Pentaho"."URL"}/kettle/executeJob?rep=COMMON_SERVICES&job=COMMONS_Bloco_TPICANCELPAYMENT&codigotransacao=${pedidopagamento.tokentransacao}
- Autenticação básica com {"Cadastro de plugin TPI"."Configurações do Pentaho"."Usuário"} e {"Cadastro de plugin TPI"."Configurações do Pentaho"."Senha"}
- O retorno da rota será:
- status: retorno.status
- Os possíveis valores da resposta serão:
Sincronização de pedido instantaneamente durante operações de pagamento
Para que não exista risco de um pedido já pago permaneça no android sem ser sincronizado, o sistema disponibilizará função de "Sincronização instantânea" via função de "envio de dados" da Sincronização para processos online como o processo de geração de pagamento.
O envio de dados aconteceria de maneira síncrona nos gatilhos abaixo, enviando apenas os dados (DATS) de pedido e suas dependências.
A sincronização instantânea aconteceria nas etapas de:
- Inicio do processo de finalização, enviando o pedido gravado, antes da chamada da criação do pagamento.
- Após recebimento do QR Code, enviando o registro da tabela de pagamentos do pedido.
- Após recebimento da atualização do status de pagamento, enviando o registro da tabela de pagamentos do pedido.
- Após recebimento da confirmação do cancelamento do pedido, enviando o registro da tabela de pagamentos do pedido
- Após a finalização do pedido, sendo ele pago, ou selecionado para cobrança posterior, atualizando o registro de status do pedido para PENDENTE.
- Geração de novo pagamento, enviando o registro da tabela de pagamentos do pedido
Dessa forma, o pedido devidamente pago, seja atualizado pela integração, de maneira, agendada, ou seja atualizado instantaneamente, via consulta de pagamentos, fará com que o pedido esteja em condições de ser exportado na próxima execução da integração.
...
deverá respeitar o tempo máximo de consulta de status de pagamento, segundo o parâmetro "Timeout consulta pagamento". Quando o tempo de requisição de pagamento ultrapassar o tempo definido no campo de timeout, o usuário será notificado: "Pedido finalizado com sucesso! Entretanto, o pagamento precisa ser aprovado para que o pedido seja devidamente encaminhado para faturamento". Dessa forma, o pedido será finalizado e o status de pagamento permanecerá como PENDENTE. Caso a resposta não seja bem sucedida, por qualquer motivo o sistema deverá notificar o usuário: "Pagamento não pôde ser criado no servidor do {nome do plugin}, cuja resposta foi: ${resposta da requisição}." Caso não houver mensagem, o sistema deverá exibir: "Pagamento não pôde ser consultado no servidor do {nome do plugin}." Após a mensagem, o sistema deverá: - Substituir a label "PIX aguardando pagamento" por "Pagamento não confirmado"
- O texto "O pedido será finalizado quando o pagamento for confirmado" para "Clique em finalizar para pagamento posterior"
O sistema exibirá o botão "Cancelar", que, ao clicado, deverá exibir mensagem de confirmação para o usuário: "A ação irá cancelar o QR Code, que não poderá mais ser pago. Deseja prosseguir?" Sim/não. Se sim, disparar uma requisição de cancelamento do QR Code para o servidor do TPI. - Requisição GET para a rota ${"Cadastro de plugin TPI"."Configurações do Pentaho"."URL"}/kettle/executeJob?rep=COMMON_SERVICES&job=COMMONS_Bloco_TPICANCELPAYMENT&codigotransacao=${pedidopagamento.tokentransacao}
- Autenticação básica com {"Cadastro de plugin TPI"."Configurações do Pentaho"."Usuário"} e {"Cadastro de plugin TPI"."Configurações do Pentaho"."Senha"}
- O retorno da rota será:
- status: retorno.status
- Os possíveis valores da resposta serão:
Caso a resposta seja bem sucedida, o sistema deverá notificar o usuário: "Pagamento cancelado com sucesso. Finalize o pedido novamente para gerar um novo pagamento". Dessa forma, o pedido não será finalizado, e o status de pagamento deverá ser atualizado para cancelado(sgl CAN). Caso a resposta não seja bem sucedida, o sistema deverá notificar o usuário: "Pagamento não pode ser cancelado no servidor do {nome do plugin}, cuja resposta foi: ${resposta da requisição}.". Caso não houver mensagem de retorno, o sistema deverá exibir: "Pagamento não pode ser cancelado no servidor do {nome do plugin}. Tente novamente mais tarde ou entre em contato com o suporte técnico" O sistema exibirá o botão "Finalizar", que, ao clicado, deverá notificar o usuário: "Pedido finalizado com ressalva! O pedido precisa ter seu pagamento aprovado para ser encaminhado para faturamento. Você será notificado automaticamente das atualizações, porém pode consultar instantaneamente o status do pagamento pela tela de pagamentos do pedido". Dessa forma, o pedido será finalizado e o status de pagamento permanecerá como PENDENTE (sgl PEND).
Consulta de status de pagamento de maneira agendadaPara evitar que pedidos fiquem travados no fluxo de integração com o ERP por falta de consulta do usuário, mesmo tendo sido pagos, o serviço de integração deverá consultar, com frequência definida baseado no recurso infra estrutural do servidor, os status dos pagamentos de transações com status de PENDENTE, para que, ao aprovado, o sistema possa atualizar os status dos pagamentos de maneira ativa, e quando o fizer, notificar o usuário, via notificação PUSH, que o pagamento do pedido foi aprovado/cancelado/expirado. Portanto, o sistema de integração deve consultar os pagamentos que estão com status pendente de pagamento através da consulta a seguir: /* CONSULTA_PAGAMENTOS_PENDENTES
select pp.tokentransacao from pedido p
inner join pedidopagamento pp on pp.idpedido = p.idpedido
inner join tiposituacaopagamento tsp on tsp.idstiposituacaopagamento = pp.idstiposituacaopagamento
where tsp.sgltiposituacaopagamento = 'PEND'
*/
|
Com os tokens retornados, o sistema de integração deverá consultar na api da transformação COMMONS_Bloco_TPIGETSTATUS, e verificar qual é o status atualizado do pagamento a partir do retorno "status". Com o status do pagamento em memória, o sistema de integração deverá atualizar a coluna pedidopagamento.idstiposituacaopagamento, conforme o seguinte de-para: Status do retorno | sgltiposituacaopagamento |
|---|
| pending | PEND | | approved | APR | | expired | EXP | | refunded | REEMB | | cancelled | CAN |
Se houve alteração de status, o sistema de integração deverá inserir novo registro na tabela observacaopagamento, segundo o seguinte de-para: PARA | DE |
|---|
PARA | DE |
|---|
| idobservacaopagamento | nextval('seqpkobservacaopagamento') | | observacao | "O status do pagamento foi atualizado para ${retorno.status > tiposituacaopagamento.descricao}" | | idpedidopagamento | CONSULTA_PAGAMENTOS_PENDENTES.tokentransacao | | idtiposituacaopagamento | retorno.status > tiposituacaopagamento.idtiposituacaopagamento | | idusuario | lookup para tabela usuario where login = 'admin' | | datahora | current_timestamp |
Sincronização de pedido instantaneamente durante operações de pagamentoPara que não exista risco de um pedido já pago permaneça no android sem ser sincronizado, o sistema disponibiliza função de "Sincronização instantânea" via função de "envio de dados" da Sincronização para processos online como o processo de geração de pagamento. O envio de dados acontecerá de maneira síncrona nos gatilhos abaixo, enviando apenas os dados (DATS) de pedido e suas dependências. A sincronização instantânea será realizada nas etapas de: - Inicio do processo de finalização, enviando o pedido gravado, antes da chamada da criação do pagamento.
- Após recebimento do QR Code, enviando o registro da tabela de pagamentos do pedido.
- Após recebimento da atualização do status de pagamento, enviando o registro da tabela de pagamentos do pedido.
- Após recebimento da confirmação do cancelamento do pedido, enviando o registro da tabela de pagamentos do pedido
- Após a finalização do pedido, sendo ele pago, ou selecionado para cobrança posterior, atualizando o registro de status do pedido para PENDENTE.
- Geração de novo pagamento, enviando o registro da tabela de pagamentos do pedido
Dessa forma, o pedido devidamente pago, seja atualizado pela integração, de maneira, agendada, ou seja atualizado instantaneamente, via consulta de pagamentos, fará com que o pedido esteja em condições de ser exportado na próxima execução da integração. Filtragem de exportação de pedidos sem pagamento aprovado com tipos de cobrança associados ao pluginCaso o plugin de integração da TPI estiver ativo, a integração padrão deverá aguardar o envio do pedido pedido para o ERP segundo as restrições a seguir: - Pedido estar associado à tipos de cobrança que estão configurados no plugin de integração, pelo campo "Tipos de cobrança"
- Pedido precisa conter 1 pagamento com status APROVADO
OBS: Anteriormente, no Android, pedidos que haviam sido finalizados ainda continuavam editáveis até a sincronização. Agora, esses pedidos que já foram transmitidos ao servidor não serão mais editáveis, como acontece na Web, por exemplo. |
| Card |
|---|
| label | Configuração Integração |
|---|
| Integração TechFin Pagamentos – Configuração de URLsAmbientes disponíveis
Variáveis de ambiente inseridas automaticamenteNa primeira execução da integração, as seguintes variáveis são inseridas automaticamente no banco de dados, mesmo não estando visíveis na interface do SFA: ⚠️ Importante: essas variáveis não são visíveis em tela no SFA. Se não forem definidas manualmente antes da primeira execução, os valores padrão de Staging serão utilizados automaticamente.
Como configurar para ProduçãoPara evitar que os valores padrão de homologação sejam utilizados, é necessário definir as variáveis no arquivo kettle.properties do Pentaho antes da execução inicial: | Bloco de código |
|---|
| language | text |
|---|
| title | kettle.properties |
|---|
| # TechFin Pagamentos – URLs de Produção
TPI_TENANT_URL=https://api-techfinpagamentos.totvs.app/payments-transacting/api/v2/payment/link
TPI_TOKEN_URL=https://{tenant}.totvs.app/totvs.rac/connect/token
TPI_REFUND_URL=https://api-techfinpagamentos.totvs.app/payments-transacting/api/v3/payment/refund |
Atualização manual via banco de dadosCaso a execução já tenha ocorrido com os valores padrão ou seja necessário alterar os valores posteriormente, é necessário atualizar diretamente via banco de dados: | Bloco de código |
|---|
| -- Atualiza URL de geração de link de pagamento
UPDATE PLUGININTCONFIG
SET VALOR = 'https://api-techfinpagamentos.totvs.app/payments-transacting/api/v2/payment/link'
WHERE CODIGOELEMENTO = 'TPI' AND SGLCAMPO = 'TPI_TENANT_URL';
-- Atualiza URL de autenticação
UPDATE PLUGININTCONFIG
SET VALOR = 'https://{tenant}.totvs.app/totvs.rac/connect/token'
WHERE CODIGOELEMENTO = 'TPI' AND SGLCAMPO = 'TPI_TOKEN_URL';
-- Atualiza URL de estorno
UPDATE PLUGININTCONFIG
SET VALOR = 'https://api-techfinpagamentos.totvs.app/payments-transacting/api/v3/payment/refund'
WHERE CODIGOELEMENTO = 'TPI' AND SGLCAMPO = 'TPI_REFUND_URL'; |
Documentação relacionada |
|