Plugin de download de Boletos

DADOS GERAIS SOBRE O RECURSO

O sistema disponibiliza um plugin com o nome "Download de Boletos" para permitir o download do PDF do boleto tanto na WEB quanto no Mobile.

Esse plugin permite que seja configurada conexão com uma API que requisita no ERP ou outro local definido pelo cliente, o arquivo PDF referente ao Boleto que se deseja baixar, e faz com que esse arquivo PDF seja baixado localmente no computador ou smartphone do usuário.

É importante ressaltar que não fornecemos a api que obtém o arquivo do ERP e disponibiliza para o SFA. É necessário que haja do lado do cliente, uma API à qual nosso plugin irá se conectar e fazer a requisição de download, por essa razão, é preciso também que e essa API esteja adequada ao modelo de REQUEST e RESPONSE esperado pelo SFA para obter o arquivo PDF.

Dessa forma, quando o Plugin estiver ativo e as configurações realizadas corretamente, pela tela de Títulos na WEB ou no aplicativo, é possível baixar o arquivo PDF referente ao boleto selecionado.

Configuração do Plugin

Na tela de Plugins de integração acessado em Configuração > Integração > Plugins de Integração, o sistema disponibiliza um card de nome "Download de Boletos" para ativar o recurso.

Ao clicar no botão "Configurar", é aberta a tela de configuração. Informe cada campo conforme a configuração detalhada a seguir:

Configuração da API
URL	Informe a URL em que a API para download estará sendo servida (Ex: https://IP:PORTA/rest/KFATRO03)
Usuário	Informe o Usuário da autenticação básica
Senha	Informe a senha da autenticação básica
Job	Informe o nome do serviço Pentaho que faz a comunicação com a URL fornecida
Rep	Informe o repositório onde está o Job dentro do arquivo .jar da integração
Timeout	Informe de processamento para aguardar retorno da API

Também é necessário acessar o menu Integração > Variáveis de Integração, e configurar a variável que determina se o parâmetro EMPRESA deve ser enviado na REQUEST. Esse parâmetro deve estar ativo e com valor 1 para clientes que utilizam o ERP Protheus, para os demais ERP's esse parâmetro deve estar inativo e com valor 0.

Implementação do Botão para download do PDF do Boleto

O botão para download estará visível na Listagem de Títulos quando o plugin estiver ativo.

Acessar a listagem de títulos no painel 360° do cliente, selecionar um boleto para baixar, e clicar no ícone .

Ao clicar no ícone, será feita uma requisição na API configurada e, uma vez recuperado o arquivo do boleto, ele será baixado no computador local ou smartphone do usuário.

A consulta é na API informa a nota fiscal vinculada ao título, e a API por sua vez, deve retornar todos os boletos em aberto vinculados àquela nota fiscal.

Ao clicar no Ícone do registro que pretende consultar, a aplicação exibe a janela de comunicação com o Carte e a consulta do Boleto e Download é realizada.

DADOS DE INTEGRAÇÃO COM API

Detalhamento Plugin

Pelo tools opção 5 deverá ser criado o registro:

Criar Plugin

pluginintegracao {
                      codigo: DOWNBOL,
                      descricao: API Para download Boleto (PDF),
                      idnAtivo: 0
                  }

Criar campos de configuração

					Campo "URL"
                      idpluginintegracao: select idpluginintegracao from pluginintegracao where codigo = 'DOWNBOL',
                      codigoelemento: DOWNBOL,
                      agrupador: 0,
                      sglcampo: DOWNBOL_URL
                      valor: {valor inserido no campo URL}
                    Campo "Usuário"
                      idpluginintegracao: select idpluginintegracao from pluginintegracao where codigo = 'DOWNBOL',
                      codigoelemento: DOWNBOL,
                      agrupador: 0,
                      sglcampo: DOWNBOL_USER
                      valor: {valor inserido no campo USUÁRIO}
                    
                    Campo "Senha"
                      idpluginintegracao: select idpluginintegracao from pluginintegracao where codigo = 'DOWNBOL',
                      codigoelemento: DOWNBOL,
                      agrupador: 0,
                      sglcampo: DOWNBOL_PASSWORD
                      valor: {valor inserido no campo Senha}
                    
                    Campo "Timeout Consulta"
                      idpluginintegracao: select idpluginintegracao from pluginintegracao where codigo = 'DOWNBOL',
                      codigoelemento: DOWNBOL,
                      agrupador: 0,
                      sglcampo: DOWNBOL_TIMEOUT
                      valor: {valor inserido no campo Timeout consulta}
                    
                    Campo "Rep"
                      idpluginintegracao: select idpluginintegracao from pluginintegracao where codigo = 'DOWNNF',
                      codigoelemento: DOWNBOL,
                      agrupador: 0,
                      sglcampo: DOWNNF_REP
                      valor: {COMMONS_SERVICES}
                    Campo "Job"
                      idpluginintegracao: select idpluginintegracao from pluginintegracao where codigo = 'DOWNNF',
                      codigoelemento: DOWNBOL,
                      agrupador: 0,
                      sglcampo: DOWNNF_JOB
                      valor: {DOWNLOADBOLETO}

Implementação na Listagem de Boletos

Na tela de listagem é exibido o botão .
- idnAtivo = 1: select idnAtivo from pluginintegracao where codigo = 'DOWNNF'

Ao clicar no botão de download a aplicação deverá consultar o carte;

- A url do download deve ser montada da seguinte forma: URL=${Configurações do Pentaho.URL}/kettle/executeJob/?rep={}&job={}
- No body da requisição, passar as seguintes informações:

Consulta Boleto

{
	idnotafiscal:
}

O retorno desta url será o arquivo em base64 para download:

200 - Retorno com Sucesso

	{
            "lStatus": true,
            "cMensagem": "Sucesso",
            "cBoleto": {base64}
     }

Integração da API Download de Boleto

Foi criado a variável de integração abaixo:

A variável tem uso para os plugins de download de nota fiscal e download boletos;


ERP	TODOS
CONTEXTO	API
DESCRIÇÃO	Se valor 1, a URL será no formato {URL_API_NOTA_FISCAL_CLIENTE}/{empresa}/{filial}/{documento}/{serie}; se a variável estiver inativa, então a URL montada será no formato {URL_API_NOTA_FISCAL_CLIENTE}/{filial}/{documento}/{serie}.
TABELA	WSCONFIGINTEGRACAO
CAMPO	VALOR
VALOR	1
IDNATIVO	1
CODIGOERP	API_DOWNNF

Criar para Pentaho-Carte o Job DOWNLOADBOLETO no repositório COMMONS_SERVICES;
URL de consulta deve ser montada no seguinte padrão:

GET: {URL_API_BOLETO_CLIENTE}/{empresa}/{filial}/{documento}/{serie}

HEADERS: Authorization: Basic {TOKEN}

- Informações da request serão obtidas a partir das consultas abaixo;
- Se o campo EMPRESA estiver como NULL, então o parâmetro EMPRESA não deve ser repassado na URL da request. Dessa forma {URL_API_BOLETO_CLIENTE}/{filial}/{documento}/{serie}:

Consulta dados Boleto

SELECT n.numeronotafiscal AS DOCUMENTO,
       n.serie            AS SERIE,
       l.numeromatricula  AS FILIAL,
       CASE
         WHEN Cast(w.valor AS VARCHAR) = '1' THEN
         Split_part(n.codigoerp, '#', 1)
         ELSE NULL END    AS EMPRESA
FROM   notafiscal n
       INNER JOIN local l
               ON l.idlocal = n.idlocalfilialfaturamento
       LEFT JOIN wsconfigintegracao w
              ON w.codigoerp = 'API_DOWNNF'
                 AND w.idnativo = 1
WHERE  n.idnotafiscal = :IDNOTAFISCAL;


SELECT ( CASE
           WHEN sglcampo = 'DOWNNF_PASSWORD' THEN valor
         END ) AS SENHA,
       ( CASE
           WHEN sglcampo = 'DOWNNF_USER' THEN valor
         END ) AS USUARIO,
       ( CASE
           WHEN sglcampo = 'DOWNNF_URL' THEN valor
         END ) AS URL
FROM   pluginintconfig
WHERE  codigoelemento = 'DOWNNF'
       AND sglcampo IN ( 'DOWNNF_PASSWORD', 'DOWNNF_USER', 'DOWNNF_URL' );

O retorno recebido será no formato base64, e deve ser retornado para aplicação sem transformações dentro do XML do RESPONSE:

200 - Retorno com Sucesso

{
            "lStatus": true,
            "cMensagem": "Sucesso",
            "cBoleto": {base64}
 }

API - Boletos

Retornos:

500 - Internal Server Error

{"code":500,"detailedMessage":"","message":"Internal Server Error"}

404 - Títulos não encontrado

{
    "lStatus": false,
    "cMensagem": " Não foi encontrado o título referente ao boleto.",
    "cBoleto": ""
 }

200 - Ok

{
            "lStatus": true,
            "cMensagem": "Sucesso",
            "cBoleto": {base64}
}

Árvore de páginas