Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

Índice


       

Índice
exclude.*ndice
printablefalse

Objetivo


       O

...

objetivo da API de Integração do Smart View é promover uma nova e melhor forma de executar relatórios dentro do

...

ERP TOTVS, permitindo a integração através de dois modelos de uso: acesso através de um visualizador externo ou a geração dos relatórios para download em diversos formatos.


Image Added


O Smart View possui um Visualizador de PDF usado em integrações, que pode ser acessado por diferentes navegadores integrados aos produtos. Abaixo serão listadas as versões mínimas dos principais navegadores em que o componente é suportado:

Navegador

Versão Mínima

Chrome4
Edge12
Safari16.3
Firefox110
Opera95
IE11

Abaixo demonstraremos dois modelos de uso da integração, onde o primeiro direciona para o download de um arquivo e o segundo para utilização do viewer externo.

...

Download de Arquivo


Neste modelo iremos demonstrar com o fluxo onde é solicitado a geração de um relatório para o sistema.

É apresentado um cenário em que o relatório já esteja previamente cadastrado, e para prosseguirmos com o fluxo é necessário que tenhamos a informação do identificador do relatório.

Iniciaremos o fluxo buscando pelo identificador do relatório (id) na API de busca de relatório onde seguiremos nas etapas de busca de parâmetros, solicitação de geração finalizando na API de download do arquivo gerado.

Busca de Relatório


A "busca de relatório" é uma API que retorna os relatórios cadastrados no sistema, é possível buscar apenas os relatórios em que o usuário tem permissão de acesso, sejam eles de sua própria criação, compartilhados via pasta ou compartilhamento único. Assim como na interface do sistema, a busca possui a funcionalidade de filtro onde é necessário enviar no mínimo 3 caracteres para pesquisa, dessa forma, os relatórios que tiverem esses caracteres em comum em seu nome de exibição ou descrição serão retornados. 

Detalhes da implementação são encontrados no endpoint abaixo:

Image Modified

Abaixo temos um exemplo da lista de relatórios retornados pela API, utilizaremos o relatório com id: a4127383-3229-420f-bd47-c795c2af5ebd como exemplo para dar continuidade em nosso fluxo de uso na próxima etapa.

Bloco de código
themeRDark
titleResponse Body
[	
	{
        "id": "a4127383-3229-420f-bd47-c795c2af5ebd",
        "displayName": "Recibo de Fatura (JU203b) ",
        "description": "Recibo de Fatura (JU203b) - Grupo de Estudos",
        "navigationFolderId": 1
    },
    {
        "id": "cd767d3f-ec71-4c1a-8143-c6645dd8f63c",
        "displayName": "Recibo de Fatura\"",
        "description": "Recibo de Fatura\"",
        "navigationFolderId": null
    },
    {
        "id": "e30288af-6989-4a30-9792-3c7f5735db56",
        "displayName": "Relatorio sem fitro de casos",
        "description": null,
        "navigationFolderId": null
    }
]

Busca de Parâmetros 


É importante lembrar que um relatório pode conter parâmetros para sua geração, caso não tenha conhecimento da existência de parâmetros para o relatório selecionado, basta consultar a API abaixo.

Image Modified

A "busca de parâmetros" lista todos os parâmetros necessários para que o relatório posso ser executado, utilizaremos o valor do campo "name" de cada parâmetro para a próxima etapa.

Bloco de código
themeRDark
[
    {
        "name": "pCodEscr",
        "displayName": "Código do Escritório",
        "type": "string",
        "multiValue": true
    },
    {
        "name": "pCodFatura",
        "displayName": "Código da Fatura",
        "type": "

...

number",
        "multiValue": false
    },
    {
        "name": "pNomeSocio",
        "displayName": "Nome do Sócio da Fatura",
        "type": "string",
        "multiValue": false
    }
]

...

Solicitação de Geração de um Arquivo


O endpoint "Solicitar Geração de um Arquivo" é uma API utilizada para solicitar a geração de um arquivo para o relatório escolhido, desde o início do fluxo coletamos informações importantes para utilização deste endpoint. Utilizaremos o identificador do relatório id: a4127383-3229-420f-bd47-c795c2af5ebd e o valor da propriedade "name" de cada parâmetro necessário para geração "pCodEscr", "pCodFatura" e "pNomeSocio".

É importante destacar que alguns parâmetros podem ser Multivalorados, ou seja, podem receber mais de um valor. Este tipo de parâmetro é reconhecido quando sua propriedade "multiValue" está definida como "true".

No caso do exemplo, é possível perceber que o parâmetro "pCodEscr" é multi valorado "multiValue: true", ou seja, o parâmetro recebe uma lista de valores.

Detalhes da implementação são encontrados no endpoint abaixo:

Image Modified

Cada solicitação é exclusiva de acordo com os parâmetros necessários, neste caso serão enviados no corpo da requisição "body" os parâmetros e seus respectivos valores conforme exemplo abaixo:

Bloco de código
themeRDark
titleBody
{
  "pCodEscr": ["SP001", "

...

SP002"],
  "pCodFatura": 

...

180,
  "pNomeSocio": "Isabelle Silva"
}

Caso a requisição seja feita corretamente, será apresentado como retorno o identificador de geração "generationId"  que utilizaremos na proxima etapa.

Bloco de código
themeRDark
titleResponde Body
"3b845650-3972-49ae-9b5c-32f02423782b"

Download do Arquivo


Em nossa última etapa do fluxo utilizaremos o identificador da geração "3b845650-3972-49ae-9b5c-32f02423782b"  da etapa anterior para requerer o download do arquivo. 

Detalhes da implementação são encontrados no endpoint abaixo:

Image Modified

Este endpoint define o formato em que o arquivo será retornado. Os formatos disponíveis para download são:

FormatoDescrição
pdfPortable Document Format
xlsExcel até 2012
xlsx

Excel a partir de 2010

rftRich Text Format
docxDocumento de processamento de texto
mhtArmazenamento de um arquivo de página da web

html

Linguagem de Marcação de Hipertexto
txtArquivo de Texto
csvComma-Separated-Values
jpegArquivo de imagem comprimido
pngPortable Network Graphics
Nota

Podem acontecer situações em que o relatório solicitado ainda não tenha sido gerado, sendo assim, a retornará um erro de 'não encontrado'. Basta refazer a requisição até que o arquivo esteja disponível.

Viewer Externo


Depois que o cadastro de um relatório foi feito, para que ele seja disparado em alguma extensão do

...

ERP TOTVS, é preciso fazer a integração para ativar a geração do mesmo, sendo assim, é preciso utilizar o hyperlink que monta os links disponíveis para integração com visualizador.
Para iniciar o fluxo precisamos ter conhecimento do id de relatório que desejamos executar, caso não saiba essa informação, utilizaremos a busca de relatório para buscar essa informação.

Busca de Relatório

...


A "busca de relatório" é uma API que retorna os relatórios cadastrados no sistema, é possível buscar apenas os relatórios em que o usuário tem permissão de acesso, sejam eles de sua própria criação, compartilhados via pasta ou compartilhamento único. Assim como na interface do sistema, a busca possui a funcionalidade de filtro onde é necessário enviar no mínimo 3 caracteres para pesquisa, dessa forma, os relatórios que tiverem esses caracteres em comum em seu nome de exibição ou descrição serão retornados. 

Detalhes da implementação são encontrados no endpoint abaixo:

Image Modified

Abaixo temos um exemplo da lista de relatórios retornados pela API, utilizaremos o relatório com id: 

...

cd767d3f-

...

ec71-

...

4c1a-

...

8143-

...

c6645dd8f63c como exemplo para dar continuidade em nosso fluxo de uso na próxima etapa.

Bloco de código
themeRDark
titleResponse Body
[	
	{
        "id": "a4127383-3229-420f-bd47-c795c2af5ebd",
        "displayName": "Recibo de Fatura (JU203b) ",
        "description": "Recibo de Fatura (JU203b) - Grupo de Estudos",
        "navigationFolderId": 1
    },
    {
        "id": "cd767d3f-ec71-4c1a-8143-c6645dd8f63c",
        "displayName": "Recibo de Fatura\"",
        "description": "Recibo de Fatura\"",
        "navigationFolderId": null
    },

...

]

Hyperlinks para integração


Os links retornados na requisição de Hyperlinks são utilizados para visualização

...

de integrações feitas com o sistema, sendo uma delas a de Visualização, dessa forma

...

, é possível abrir o Smart View utilizando todos os seus recursos em um navegador.

O endpoint que utilizaremos para esse fluxo:

Image Modified

Para utilizar essa requisição vamos precisar de um ID de um relatório existente, nesse caso, utilizaremos o ID buscado na requisição de busca

...

cd767d3f-

...

ec71-

...

4c1a-

...

8143-

...

c6645dd8f63c

Os

...

parâmetros de autenticação podem ser informados por meio de QueryString ou diretamente na URL retornada. Esses

...

parâmetros de autenticação são as informações do token do usuário que irá abrir a interface da integração, essas informações são utilizadas para realizar contextualização e verificação de permissões.

Além das informações da autenticação, também devem ser enviados os parâmetros do recurso, onde serão informados os valores e a visibilidade de cada parâmetro para execução e visualização.

Informações

Os parâmetros do recurso devem ser enviados em estrutura JSON codificada como BASE64.

Bloco de código
themeRDark
titleFormato da estrutura de Parâmetros
[
	{
		"name": "nome do parâmetro",
		"value": "valor do parâmetro",
		"visibility": "Default" | "Hidden" | "Disabled" 
	},
	{
		"name": "nome do parâmetro 2",
		"value": "valor do parâmetro 2",
		"visibility": "Default" | "Hidden" | "Disabled"
	}
]

Com a URL configurada vamos acessar um browser para visualização da mesma, é apresentado o relatório informado e após a conclusão da geração podem ser utilizados os recursos da inteface para fazer, por exemplo, o download do relatório.

Image Modified

Viewer Externo com suporte a passagem de parâmetros


O endpoint de hyperlinks irá retornar os links para a integração com o visualizador, dessa forma o relatório poderá ser chamado pelo Viewer Externo.

Os parâmetros são enviados para o Viewer Externo em estrutura JSON codificada como BASE64, e devem ser informados no formato abaixo, informando o Nome, Valor e Visibilidade do Parâmetro:

Bloco de código
themeRDark
titleFormato da estrutura de Parâmetros
[
	{
		"name": "nome do parâmetro",
		"value": "valor do parâmetro",
		"visibility": "Default" | "Hidden" | "Disabled" 
	},
	{
		"name": "nome do parâmetro 2",
		"value": "valor do parâmetro 2",
		"visibility": "Default" | "Hidden" | "Disabled"
	}
]

O campo Visibilidade, possui 3 opções, sendo elas:

  • Default: Visibilidade padrão do parâmetro, onde o valor enviado pode ser alterado.
  • Hidden: Visibilidade onde o parâmetro não é exibido para o usuário, será enviado com o Valor preenchido no parâmetro.
  • Disabled: Visibilidade onde o parâmetro é exibido, mas o valor não pode ser alterado pelo usuário.

O exemplo abaixo contém o envio dos parâmetros com cada uma das visibilidades descritas:

Bloco de código
themeRDark
titleFormato da estrutura JSON de Parâmetros
[
	{
		"name": "pAplicacao",
		"value": ["TReports"],
		"visibility": "Default"
	},
	{
		"name": "pPlataforma",
		"value": ["Windows"],
		"visibility": "Hidden"
	},
	{
		"name": "pVersao",
		"value": ["0.0.0+0"],
		"visibility": "Disabled"
	}
]
Bloco de código
titleEnvio de Parâmetros em Base64
WwoJewoJCSJuYW1lIjogInBBcGxpY2FjYW8iLAoJCSJ2YWx1ZSI6IFsiVFJlcG9ydHMiXSwKCQkidmlzaWJpbGl0eSI6ICJEZWZhdWx0IgoJfSwKCXsKCQkibmFtZSI6ICJwUGxhdGFmb3JtYSIsCgkJInZhbHVlIjogWyJXaW5kb3dzIl0sCgkJInZpc2liaWxpdHkiOiAiSGlkZGVuIgoJfSwKCXsKCQkibmFtZSI6ICJwVmVyc2FvIiwKCQkidmFsdWUiOiBbIjAuMC4wKzAiXSwKCQkidmlzaWJpbGl0eSI6ICJEaXNhYmxlZCIKCX0KXQ==

Com a URL do Viewer Pdf retornada, é possível acessar o browser para visualização, onde será apresentado o relatório com os parâmetros informados, respeitando os valores e visibilidade enviados.

Image Added


Abono de licenças


Para maiores detalhes sobre o como realizar o abono de licenças durante a integração, acesse a documentação no link Consumo de Licenças (página interna).


Informações
titleInformações


As APIs publicas estão disponíveis em qualquer instalação do

...

Smart View a partir da versão 1.4 e suas operações estão documentadas via Swagger.

Informações
iconfalse
Informações
iconfalse

Produto: Framework

Informações
iconfalse

Processo: Smart View

Informações

Versão: 1.5.X

Informações
iconfalse
Informações
iconfalse

Status: Finalizado

Informações
iconfalse

Data:  

Informações
iconfalse

Autores
 Aline Cristina Braz de Oliveira 

Cesar Henrique Silva Rodrigues_ 

Diogo Damiani Ferreira

Usuário desconhecido (fernando.souza)

Usuário desconhecido (samuel.frederico) 

Wemerson Marcelo Martins Guimarães 


Page Tree