Histórico da Página

...

1. Pré-requisitos
   
   1. Plataforma com suporte REST e autenticação Basic.
   2. Suporte a tratamento cross-domain, por conta das requisições de serviços em servidores de domínio diferente.
   3. Modelo de implementação de acordo com o documento "Guia de implementação de API" disponível no link abaixo:
      http://tdn.totvs.com/pages/viewpage.action?pageId=274849083
      
      
2. Definições gerais

   1. Os retornos dos serviços REST devem estar encapsulados dentro de um objeto JSON com a seguinte especificação:
      Mensagens de erro (códigos HTTP 4xx e 5xx)

      Mensagens de erro devem-se retornar obrigatoriamente os campos a seguir:

      {     code: "",     message: "",     detailedMessage: "" } Exemplo: POST http://totvs.com.br/api/trep/v1/dbdataproviders/testeconnection {     code: "",     message: "Erro ao testar conexão com o banco de dados",     detailedMessage: "Banco de dados oracle não disponível" }

      
      Mensagens de sucesso (código http 2xx devem)

      Mensagens de sucesso devem-se retornar diretamente a entidade que representa o objeto resultado da operação do endpoint.
      

      Exemplo: POST http://totvs.com.br/api/trep/v1/dbdataproviders/testeconnection {   testConnection: "true" }

      
      
      

   2. Todas as linhas de produto devem estabelecer uma URL base, a partir da qual os serviços REST de provedor integrado serão disponibilizados. 

   3. Como exemplo, no ERP RM foi definida a seguinte  URL base: 
      /api/trep/v1/dbdataproviders/ 
      
      

      Informações
      Com o objetivo de facilitar o entendimento do documento, a URL base do RM descrita acima será utilizada no restante do documento para definição dos endpoints.

      
      

3. Definição dos serviços
   

   Os serviços REST descritos a seguir estão divididos em:

   • Serviço de leitura de parâmetros gerais;
   • Serviço de teste de conexão;
   • Serviço de teste de sentenças sql;
   • Serviço de leitura de schema de tabelas físicas;
   • Serviço de leitura de schema de sentença sql;
   • Serviço de retorno leitura de dados;

   Na descrição de cada serviço podemos encontrar os seguintes elementos:

   • Definição da URL do serviço;
   • Detalhamento dos parâmetros de entrada (request) e saída (response);
   • Descrição do serviço com detalhes relativos ao seu funcionamento;
     
     
     
   1. Serviço de leitura de parâmetros de provedor;
      

      GET /api/trep/v1/dbdataproviders/parameters      

      Recebe	Não recebe parâmetros
      Retorna	Application/JSON

      
      

      Esse método é utilizado para obtenção dos parâmetros do provedor integrado. A necessidade e definição desses parâmetros é de responsabilidade do dono do provedor. 

      No JSON de retorno, deve constar as seguintes informações:

      
      

      • name: Nome do parâmetro;

      • description: Descrição do parâmetro;

      • name: Nome do parâmetro;

      • value: Valor do parâmetro;

      • isPassword: Define se o valor do parâmetro será gravado e mostrado de forma criptografada. Pode ser true ou false
        
        

        Informações
        title Exemplo de json de retorno
        {        “providerParams” : [{              “name” : “aliasName”,              “description” : “Nome do alias do RM”,              “value” : “CorporeRM”,              “isPassword” : false,        }] }

      
      

      Informações
      Os parâmetros retornados por esse serviço aparecerão na grid de parâmetros localizada no "cadastro de provedores de dados" do front-end do T-Reports, conforme abaixo:

      
      

      

      
      

      
      

   2. Serviço de teste de conexão do provedor

      
      POST /api/trep/v1/dbdataproviders/testconnection

      
      

      Recebe	Application/JSON
      Retorna	Application/JSON

      Esse método é utilizado para testar a conexão de um provedor integrado. 

      
      

      No Json de entrada devem ser enviados os parâmetros cadastrados na tela de "Provedores de dados". Esses parâmetros são os mesmos recuperados pelo serviço definido acima "GET /api/trep/v1/dbdataproviders/parameters".

      Informações
      title Exemplo de json de entrada
      {        “providerParams” : [{              “name” : “aliasName”,              “description” : “Nome do alias do RM”,              “value” : “CorporeRM”,              “isPassword” : false,        }] }

      
      

       No JSON de retorno, deve constar as seguintes informações:

      1. testSuccess: Informa se o teste do bem sucedido. Pode ser true ou false
         
         

         Informações
         title Exemplo de json de retorno
         {        “testSuccess” : true; }

      Esse método é utilizado no click do botão "Testar conexão" localizado no "cadastro de provedores de dados" do front-end do T-Reports, conforme abaixo:

      

      
      c) Serviço de teste de sentenças sql

      POST /api/trep/v1/dbdataproviders/testquery

   • Recebe	Application/JSON
     Retorna	Application/JSON

     
     

     Esse método é utilizado para testar a sintaxe de uma sentença sql. 
     
     

     No Json de entrada devem ser enviadas os seguintes informações: 
     
     

     • providerParams: Parâmetros do provedor de dados.
     • sqlText: Texto da sentença sql;
     • sqlParameters: Parâmetros da sentença sql;
       • paramName: Nome do parâmetro da sentença sql;
       • paramValue: Valor do parâmetro da sentença sql;
       • paramType: Tipo do parâmetro;

       
       

       Informações
       title Exemplo de json de entrada
       {             “providerParams” : [{                         “name” : “aliasName”,                         “description” : “Nome do alias do RM”,                         “value” : “CorporeRM”,                         “isPassword” : false,             }],             "sqlText": "select * from pfunc where codcoligada = :codcol",             "sqlParameters": [{                         "paramName": "codcol",                         "paramValue": "1",                         "paramType": "system.Int32"             }] }

           No JSON de retorno, deve constar as seguintes informações:

   • testSuccess: Informa se o teste do bem sucedido. Pode ser true ou false
     
     

     Informações
     title Exemplo de json de retorno
     {        “testSuccess” : true; }

     
     

     d) Serviço de leitura de schema de tabelas físicas;

     GET /api/trep/v1/dbdataproviders/schematable

...

• • 
    GET /api/trep/v1/dbdataproviders/schemasql

    Recebe	Application/JSON
    Retorna	Application/JSON

    Esse método é utilizado para retornar o schema (estrutura) de uma sentença sql disparada em um determinado provedor de dados. 
    
    

    No Json de entrada devem ser enviadas os seguintes informações: 
    
    

    • providerParams: Parâmetros do provedor de dados.
    • sentencesqlText: Sentença sql cadastrada na fonte de dados do relatório;

    • schemaSqlParameterssqlParameters: Lista de objeto contendo informações dos parâmetros da sentença sql:

      • paramName: Nome do parâmetro da sentença sql;

      • paramValue: Valor do parâmetro da sentença sql;
      • paramType: Tipo do parâmetro;

      
      

      Informações
      title Exemplo de json de entrada
      {             “providerParams” : [{             “description” : “Nome do alias do RM”,             “value” : “CorporeRM”,             “isPassword” : false,             }],             "sqlText": "select * from pfunc where codcoligada = :codcol",             "sqlParameters": [{                         "paramName": "codcol",                         "paramValue": "1",                         "paramType": "system.Int32"             }] }

            No JSON de retorno, deve constar as seguintes informações:

    • schemaSql: objeto contendo as seguinte informações:

      • columns: lista contendo as seguinte informações:
        • columnName: Nome da coluna;
        • columnType: tipo da coluna;

      Informações
      Esse método não contêm informações de relacionamento, visto que, trata-se de uma sentença sql. Nesse caso, as informações de relacionamento não poderão ser recuperadas automaticamente de dicionários de dados.

Esse método é utilizado na tela de cadastro de entidade do tront-end do reports, ao escolher uma fonte de dados ligada a uma sentença sql:

Image Added

f) - Serviço de leitura de dados;

• • 
    GET /api/trep/v1/dbdataproviders/data

    Recebe	Application/JSON
    Retorna	Application/JSON

    Esse método é utilizado para retornar os dados do relatórios. 
    
    

    No Json de entrada devem ser enviadas as seguintes informações: 
    
    

    • providerParams: Parâmetros do provedor de dados.
    • sentenceMember: Objeto contendo as seguinte informações:

      • entityName: Nome da entidade cadastrada no reports que receberá os dados.

      • sqlText: sentença sql a ser disparada no banco de dados;

      • sqlParameters: Lista de objeto contendo informações dos parâmetros da sentença sql:

        • paramName: Nome do parâmetro da sentença sql;

        • paramValue: Valor do parâmetro da sentença sql;
        • paramType: Tipo do parâmetro;
      • maxRecords: número máximo de registros a serem retornados. Se o valor for < 0 (default), serão retornados todos os registros.

      Informações
      title Exemplo de json de entrada
      {             “providerParams” : [{             “description” : “Nome do alias do RM”,             “value” : “CorporeRM”,             “isPassword” : false,             }],             "sentenceMember": {                         "entityName": "Funcionarios",                         "sqlText": "select * from pfunc where codcoligada = :codcol",                         "sqlParameters": [{                                     "paramName": "codcol",                                     "paramValue": "1",                                     "paramType": "system.Int32"                         }],                         maxRecords: 10} }

            No JSON de retorno, deve constar as seguintes informações:

    • entityName: Nome da entidade enviada no parâmetros "entityName" do objeto de request;

    • data: Dados recuperadas no banco de dados através da execução da sentença sql enviada no objeto de request:
    
    

    • Informações
      Esse método não contêm informações de relacionamento, visto que, trata-se de uma sentença sql. Nesse caso, as informações de relacionamento não poderão ser recuperadas automaticamente de dicionários de dados.

...