...
O TReports conta com sua interface para listar, buscar, gerar e fazer o download dos relatórios produzidos, agora com a introdução às APIs de Integração, será possível que os produtos que precisarem se integrarem com o sistema tenham novas formas de executar relatórios dentro do produto, tendo acesso a um visualizador e/ou ao relatório gerado em diversos formatos. Promovendo uma nova e melhor experiência para o usuário da linha de produto ao precisar acessar suas informações por meio de relatórios.
ABaixo A Baixo demonstramos dois cenários de uso dessa integração:
...
...
...
No primeiro modelo iremos demonstrar com o fluxo onde é solicitado a geração de um relatório para o sistema. As premissas a serem seguidas são: É preciso pesquisar o relatorio a ser gerado, posteriormente aplicaremos um filtro nessa busca de relatórios.
...
...
A busca é utilizada para encontrar o relatório desejado, sendo possível buscar aqueles que o usuário tem permissão de acesso, sejam eles criados pelo próprio usuário, compartilhados via pasta ou via compartilhamento único. Assim como é feito na interface, a busca já pode ser realizada ao enviar no mínimo 3 caracteres para pesquisa, todos os relatórios que tiverem esses caracteres em comum serão retornados.
Para detalhes procure pelo endpoint abaixo:
O retorno apresentado lista os relatórios do sistema.
Bloco de código | ||||
---|---|---|---|---|
| ||||
[ { "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 } ] |
Para seguirmos o fluxo apresentado iremos utilizar o relatório de ID: a4127383-3229-420f-bd47-c795c2af5ebd.
...
...
...
É importante
...
lembrar que um relatório pode conter parâmetros para sua geração, caso não tenha
...
ciência se o relatório possui um parâmetro, basta consultar o
...
endpoint:
A requisição
...
irá retornar os parâmetros necessários para fazer a solicitação do relatório.
...
Bloco de código |
---|
[ { "name": "pCodEscr", "displayName": "Código do Escritório", "type": "string", "multiValue": true }, { "name": "pCodFatura", "displayName": "Código da Fatura", "type": "string", "multiValue": false }, { "name": "pNomeSocio", "displayName": "Nome do Sócio da Fatura", "type": "string", "multiValue": false } ] |
Utilizaremos a resposta para o campo "Name" para fazer a associação ao valor exigido.
...
Neste momento temos o
...
ID do relatório e o name do parâmetros necessários para geração (pCodEscr,
...
pCodFatura e pNomeSocio). Podemos perceber que o parâmetro "pCodEscr" é multi valorado (multiValue: true), isso significa que o parâmetro recebe uma lista de valores.
Para solicitar a geração utilizamos o endpoint abaixo:
Nesta requisição, como mencionado anteriormente, utilizaremos todos os dados reunidos até o momento. Cada solicitação é exclusiva de acordo com os parâmetros necessários, neste caso apresentamos a forma em que os parâmetros serão enviados no
...
corpo (body) da requisição conforme o cenário apresentado.
Bloco de código | ||
---|---|---|
| ||
{ "pCodEscr": ["SP001", "SP001"], "pCodFatura": "000000180", "pNomeSocio": "FulanoIsabelle de TalSilva" } |
O retorno dessa requisição é o ID de geração que nós guiara na proxima etapa.
Bloco de código | ||||
---|---|---|---|---|
| ||||
"3b845650-3972-49ae-9b5c-32f02423782b" |
...
Com o
...
Id de geração
...
retornado na etapa anterior, basta requisitar o download no endpoint abaixo
...
:
...
Formatos disponíveis para Download:
Formato | descriçãoDescrição | |
---|---|---|
portable document format | ||
Portable Document Format | ||
XLS | xlsExcel até 2012 | xlsx|
XLSX | Excel a partir de 2010 |
...
RFT | Rich Text Format |
DOCX | Documento de processamento de texto |
MHT | Armazenamento de um arquivo de página da web |
HTML | Linguagem de Marcação de Hipertexto |
TXT | Arquivo de Texto |
CSV | Comma-Separated-Values |
JPEG | Arquivo de imagem comprimido |
PNG | Portable Network Graphics |
Informações |
---|
Pode acontecer situações em que o relatório ainda não tenha sido gerado e a API não retornará o documento gerado, informando um erro de não encontrado. Basta refazer a requisição. |
----------------------------------------------------------------------
As APIs publicas estão disponíveis em qualquer instalação do TReports e suas operações estão documentadas via Swagger.
Informações |
---|
Documentação no swagger: Api publica para integração; Para realizar testes é necessário o uso de alguma aplicação que simule requisições http; |
...
...
...
Depois que o cadastro de um relatório foi feito, para que ele seja disparado em alguma extensão do produto é 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, definindo qual a rota será utilizada e nela, a geraçãodo relatório, que é indicado pelo seu ID na rota, é mostrado na interface do TReports, com essa interface, além definir os parâmetrosque são necessários para fazer essa geração, é possível visualizar o relatório e fazer o seu download.
...
...
O filtro de Pastas é passado dessa forma ao final da URL:
?NavigationFolderId={ID-da-Pasta}
Informações |
---|
O filtro funciona assim como a própria busca via interface, ou seja, digitando no mínimo 3 caracteres já é possível buscar o nome de relatórios baseados naquilo que foi escrito. |
...
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
[
{
"id": "1aa11111-1aa1-1aaa-1a1a-aa1aa1a11a11",
"displayName": "Relatorio",
"description": "Relatório utilizado para exemplificar",
"navigationFolderId": 1
}
] |
Nessa requisição é possivel visualizar os parâmetros necessários para a execução de um relatório.
OPTIONS: /api/reports/v1/resources/{id-do-relatório}/generate
...
Bloco de código | ||||
---|---|---|---|---|
| ||||
[
{
"name": "parametro",
"displayName": "parametro",
"type": "string",
"multiValue": true
}
] |
Para fazer a geração é necessário informar o ID do Relatório, o tempo que a geração ficara disponível para consultas e seu parâmetro, caso já tenha sido previamente cadastrado.
POST: /api/reports/v1/resources/{id-do-relatório}/generate?ttl=1440
...
Caso o relatório possua parâmetros cadastrados é necessário informar no body da requisição:
Bloco de código | ||||
---|---|---|---|---|
| ||||
{
"nome-do-parâmetro":"valor-desejado-do-parâmetro"
} |
...
Bloco de código | ||||
---|---|---|---|---|
| ||||
"3b845650-3972-49ae-9b5c-32f02423782b" |
O download nada mais é do que uma forma de salvar o relatório gerado localmente em um formato especifico desejado, para fazer o download será preciso informar o ID da geração do relatório e o formato para download desejado.
GET: /api/reports/v1/generated/{id-da-geração}/{formato}
Formatos disponíveis: PDF, XLS, XLSX, RTF, DOCX, MHT, HTML, TXT, CSV, JPEG e PNG.
Ao fim da requisição será possível visualizar o relatório no formato escolhido e fazer o seu download.
O Hyperlink permite que o produto integrador tenha acesso a um template de rota para acesso ao visualizador de um relatório sem utilizar o sistema como um todo.
GET: /api/reports/v1/hyperlinks
...
Exemplo de resposta:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"viewer": "http://localhost:7017/reportsV2/myreports/document-view/{reportId}?access_token={accessToken}&refresh_token={refreshToken}&scope={scope}&token_type={tokenType}&expires_in={expiresIn}&hidemenus=true"
}
|
Os parâmetros do template podem ser inseridos de acordo com a necessidade do produto, sendo preenchido via QueryString, dessa forma, as URLs retornadas no hyperlink já virão com os parâmetros preenchidos de acordo com as informações colocadas.
Exemplo de URL enviando QueryString:
...
o endpoint utilizado será:
As APIs publicas estão disponíveis em qualquer instalação do TReports e suas operações estão documentadas via Swagger.
Informações |
---|
Documentação no swagger: Api publica para integração; Para realizar testes é necessário o uso de alguma aplicação que simule requisições http; |