Histórico da Página

ESCOPO FUNCIONAL/MANUAL

Detalhamento da utilização do Recurso

Para que esse fluxo funcione na Aplicação SFA, o cliente precisa disponibilizar a API nos moldes propostos nesta documentação, seja por meio de desenvolvimento interno/próprio ou por uma empresa que ofereça esse serviço para clientes Protheus. Caso opte pelo serviço da unidade TOTVS, a negociação será feita diretamente com a unidade.

Após disponibilizar essa API, o cliente deve informar à equipe/Consultor do TOTVS CRM SFA a URL da API e as credenciais, considerando que a API segue o modelo de request e response detalhado no card ESCOPO FUNCIONAL desta documentação.

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:

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.

ESCOPO TÉCNICO DA API DE DOWNLOAD DE BOLETOS

Detalhamento Plugin

• Pelo tools opção 5, o registro é criado:

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

					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, o botão é exibido.

• idnAtivo = 1: select idnAtivo from pluginintegracao where codigo = 'DOWNNF'

• Ao clicar no botão de download, a aplicação consulta o carte.

• A URL de download é montada da seguinte forma:
  URL=${Configurações do Pentaho.URL}/kettle/executeJob/?rep={}&job={}

No body da requisição, as seguintes informações são enviadas:

{
	idnotafiscal:
}

O retorno dessa URL é o arquivo em base64 para download:

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

Integração da API Download de Boleto

A variável de integração abaixo é criada:

A variável é usada nos plugins de download de nota fiscal e download de boletos.

Detalhes de Job DOWNLOADBOLETO

O Job DOWNLOADBOLETO é criado no Pentaho-Carte no repositório COMMONS_SERVICES.

URL de consulta é 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}:

Bloco de código
language sql firstline 1 title Consulta de dados Boleto linenumbers true
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:

Bloco de código
language js firstline 1 title 200 - Retorno com Sucesso linenumbers true
{ "lStatus": true, "cMensagem": "Sucesso", "cBoleto": {base64} }

Painel
title Retornos da API
Bloco de código firstline 1 title 500 - Internal Server Error linenumbers true {"code":500,"detailedMessage":"","message":"Internal Server Error"} Bloco de código firstline 1 title 404 - Títulos não encontrado linenumbers true { "lStatus": false, "cMensagem": " Não foi encontrado o título referente ao boleto.", "cBoleto": "" } Bloco de código firstline 1 title 200 - Ok linenumbers true { "lStatus": true, "cMensagem": "Sucesso", "cBoleto": {base64} }