Índice

Objetivo

       O objetivo da API de Importação de Recursos do TReports é promover uma forma de importar recursos existentes através ERP TOTVS. Com isso, o ERP TOTVS pode injetar no TReports um conjunto de recursos padrões, como por exemplo relatórios administrativos e financeiros.

API

A Importação é uma API que recebe um arquivo ZIP contendo os recursos exportados no TReports, realiza a importação na instância atual e retorna as informações dos recursos importados. É possível também realizar a importação de um arquivo único de um recurso (ver limitação abaixo).

Atualmente a API suporta a importação dos tipos de recurso abaixo:

• Relatórios;
• Tabelas Dinâmicas;
• Visões de Dados;

O formato de retorno da API para as informações dos recursos importados é:

• {fileName}: Nome do arquivo do recurso importado contido no arquivo ZIP enviado*
• {resourceType}: Tipo do recurso importado
  • Valores possíveis
    • report: Relatórios;
    • pivot-table: Tabelas Dinâmicas;
    • data-grid: Visões de Dados;
• {resourceId}: Id do recurso importado na instância atual do TReports

*Obs: Caso seja enviado um arquivo simples contendo um recurso, o campo fileName irá retornar como null.

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

Erros na Importação

A importação não será realizada caso ocorra um erro durante a chamada à API. Nesses casos a API irá retornar um código e uma mensagem com mais detalhes do erro. As possíveis causas de erro e os respectivos códigos de erro retornado são:

O formato de retorno da API em caso de erro é:

• {code}: Código de erro
• {message}: Mensagem de erro
• {detailMessage}: Mensagem detalhada de erro
• {helpUrl}: Url para ajuda sobre o erro (caso disponível)
• {details}: Lista contendo os erros encontrados para cada arquivo importado.

Abaixo um exemplo de retorno de erro para um arquivo ZIP contendo um arquivo corrompido de nome "corrupted.treports" :

{
    "code": "core.imports.zip-contains-corrupted-files",
    "message": "O arquivo enviado contem um ou mais arquivos corrompidos que não podem ser lidos pelo treports",
    "detailedMessage": null,
    "helpUrl": null,
    "details": [
        {
            "code": "core.imports.corrupted-file-in-zip",
            "message": "O arquivo \"corrupted.treports\" esta corrompido ou não é um arquivo do treports válido",
            "detailedMessage": "core.imports.corrupted-file-in-zip\r\n\r\nO arquivo \"corrupted.treports\" esta corrompido ou não é um arquivo do treports válido\r\n"
        }
    ]
}

Exemplo de uso da API

Abaixo será exemplificando um caso em que que o ERP necessita importar no TReports alguns recursos previamente desenvolvidos.

Considerando que previamente foram criados e exportados no TReports os recursos abaixo:

Relatórios

• Relatório de Banco de Horas;
• Relatório de Depreciação;

Tabelas Dinâmicas

• Total de Funcionários;
• Média de Vendas;

Visões de Dados

• Vendas por filial;
• Funcionários por departamento;

Os nomes dos arquivos exportados desses recursos foram editados e incluídos em um arquivo ZIP de nome "Recursos ERP" conforme figura abaixo:

Obs.: Não é necessário que os arquivos simples dos recursos tenham a extensão ".treports". Essa extensão é utilizada apenas para identificar o tipo do arquivo.

Ao enviar o arquivo ZIP contendo os arquivos acima via API de importação, serão retornadas as seguintes informações:

[
    {
        "fileName": "Funcionarios por departamento.treports",
        "resourceType": "data-grid",
        "resourceId": "922b0080-c30c-4972-a174-cff5e3ef2bf3"
    },
    {
        "fileName": "Media de Vendas.treports",
        "resourceType": "pivot-table",
        "resourceId": "c5befab1-1d7f-47b5-880c-8f76c91ab8c0"
    },
    {
        "fileName": "Relatorio de Banco de Horas.treports",
        "resourceType": "report",
        "resourceId": "27f87e71-e0ab-453a-9f3a-52623075f06c"
    },
    {
        "fileName": "Relatorio de Depreciacao.treports",
        "resourceType": "report",
        "resourceId": "94032928-1aad-4336-ab0d-ec7836819307"
    },
    {
        "fileName": "Total de Funcionarios.treports",
        "resourceType": "pivot-table",
        "resourceId": "b48f25a5-8f1f-42b5-83ea-d106b9dd28df"
    },
    {
        "fileName": "Vendas por filial.treports",
        "resourceType": "data-grid",
        "resourceId": "7eeff9bb-0c73-447e-8f90-4307d7c712e1"
    }
]

De posse dos Ids, é possível realizar as consultas através das APIs Públicas de cada tipo de recurso. Ver:

• Integrando Relatórios com ERP TOTVS
• Integrando Tabelas Dinâmicas com ERP TOTVS
• Integrando Visão de Dados com ERP TOTVS