Objetivo

Esta API tem como objetivo realizar a comunicação e tratamento dos dados das APIs do portal da Conformidade Fácil. Essas APIs são referentes a cadastros do sistema como códigos de crédito presumido, código de classificação tributária entre outros.

Requisitos

Para execução correta do programa é necessário realizar as configurações na tela html.mcd.govApiParams. Se o programa for executado e não existir nenhum parâmetro a execução será encerrada e uma mensagem será gravada nos logs informando a inexistência do cadastro.

Funcionamento

A API recebe dois parâmetros: um parâmetro do tipo RAW com os dados de uma tabela temporária usados como parâmetros para execução do programa e uma tabela temporária com um campo do tipo RAW. Em resumo, são os parâmetros padrões de execução de um programa Progress a partir de uma tela, por exemplo.

Devido ao uso deste formato, é possível para o usuário criar um pedido para execução do programa em servidor RPW. 

Exemplo de uso:  

DEFINE VARIABLE raw-param AS RAW NO-UNDO.

DEFINE TEMP-TABLE tt-raw-digita
   FIELD raw-digita  AS RAW.

CREATE tt-param. // Definição da tt-param na seção Temp-Tables ao final deste documento.
ASSIGN tt-param.destino = 2
	   tt-param.arquivo = "consumoApiGov.json"
       tt-param.usuario = "super"
       tt-param.data-exec = TODAY
       tt-param.hora-exec = ?
       tt-param.cod-endpoint = "credPresumido" // Endpoint pode ser consultado no portal da Conformidade Fácil, aba Serviços
       tt-param.cod-programa-area = "cdp/consumoApiGovCredPresMOF.p" // Precisa ser o caminho completo do programa
       tt-param.l-sobrescreve = FALSE.

FOR FIRST tt-param:
	RAW-TRANSFER tt-param TO raw_param.
END.

RUN cdp/consumoApiGov.p (INPUT raw_param, INPUT TABLE tt-raw-digita).

O campo arquivo indica em qual arquivo será salvo a resposta da requisição efetuada para o portal da Conformidade Fácil. Esse arquivo serve apenas para conferência dos registros que foram retornados pela API.
O campo cod-endpoint indica qual dos serviços da API do portal da Conformidade Fácil será consumido. Os serviços disponíveis podem ser consultados por meio deste link.
O campo cod-programa-area indica qual o programa que será executado para realizar o tratamento dos dados retornados pela requisição feita pelo programa principal consumoApiGov.p. Ao final da execução do programa consumoApiGov.p, será executado o programa que foi informado no campo cod-programa-area.
O campo l-sobrescreve é apenas um utilitário para indicar se o programa específico da área deve sobrescrever os dados ou apenas considerar códigos novos. Atenção! A lógica para sobrescrever ou não os códigos é responsabilidade do programa específico da área, o programa consumoApiGov.p apenas realiza a comunicação com o portal da Conformidade Fácil.

As APIs do portal da Conformidade Fácil utilizam de certificados digitais para realizar a autorização de acesso ao recurso. O certificado digital pode ser do tipo PEM ou PFX, no entanto, se for o tipo PFX, o programa irá automaticamente converter o certificado para o tipo PEM, gerando dois arquivos de certificado digital com as extensões .pem e .key. Esse processo é feito utilizando a biblioteca OpenSSL disponível a partir dos arquivos de instalação do Progress da sessão. Em caso de erros durante o processo de conversão, é necessário consultar os logs do servidor RPW procurando no arquivo pela chave AppError. Os comandos utilizados durante a conversão são gravados nos logs buscando pela chave AppLog.

Para realizar as requisições para o portal da Conformidade Fácil, o programa utiliza da biblioteca cURL para realizar requisições a partir da linha de comando usando o sistema operacional. O uso do cURL em detrimento das bibliotecas próprias do Progress para realizar a requisição se deve a necessidade de uso de certificado digital na requisição e esta funcionalidade não é suportada pelo Progress em versões mais antigas como a 12.2. 

Em caso de sucesso na requisição, o programa recebe os dados em formato JSON e realiza os tratamentos para enviar o JSON de retorno para a API da área, além disso, é gerado um arquivo JSON no diretório de spool do servidor RPW com o nome inserido no campo tt-param.arquivo, sendo útil para verificar qual a estrutura do objeto JSON recebido. Em caso de falha na requisição, o resultado do comando cURL será salvo em um arquivo chamado api_gov_response.txt no diretório temporário da sessão. Outros erros durante a execução do programa serão gravados nos logs da sessão com o código AppError. 

Para realizar testes neste programa é necessário possuir um certificado digital válido para autorização de uso das APIs do Portal da Conformidade. O caminho do arquivo do certificado digital deve ser inserido por completo no programa html.mcd.govApiParams, incluindo a sua extensão para que o programa encontre o arquivo correto. Além de informar o caminho completo, é necessário que o arquivo esteja em um diretório que possa ser acessado pelo servidor RPW que será utilizado para realização dos testes.

Ainda, se o sistema operacional do ambiente do servidor RPW for Windows, é necessário colocar o executável do cURL também em um diretório que possa ser acessado pelo servidor RPW. Segue um exemplo de estrutura de pastas utilizada para realização de testes no programa:

cURL no diretório testes:

Dentro da pasta Exemplo_caminho_cURL deve ser colocada a pasta lib, que é onde estão armazenados os arquivos da biblioteca do cURL para uso do executável:

O conteúdo da pasta lib deve ser uma pasta chamada curl com os arquivos de instalação do executável.

Importante: O servidor RPW deve ter acesso a esses diretórios. Para testes internos, é possível colocar o programa nos diretórios de testes de programa que estão no PROPATH do servidor RPW.

Para descobrir os caminhos das possíveis instalações do cURL na máquina no Windows, é possível utilizar seguinte comando: where curl.

Para descobrir se o cURL instalado no Windows possui suporte a SSL, é possível verificar a partir de linha de comando utilizando o seguinte comando: curl --version.

Neste caso, o cURL tem suporte ao SSL por causa presença do LibreSSL/4.0.0 nesta instalação.

A máquina virtual Windows usada para desenvolvimento já possui o cURL instalado com suporte a SSL, dessa forma, é possível buscar os arquivos de instalação e executável usando o comando where curl para encontrar os diretórios. 

Para Linux, o programa assume que o cURL instalado nativamente no sistema operacional possui o suporte a SSL, desconsiderando o que estiver no campo Caminho cURL na tela html.mcd.govApiParams.

Após realizar a requisição, o programa salva um registro dessa requisição gravando na tabela requisicao-api-gov o serviço, status, data e hora da requisição. Esta tabela armazena um registro por serviço do portal da Conformidade Fácil, dessa forma, toda vez que uma nova requisição é realizada para determinado serviço este registro é atualizado com os dados da última requisição. Ainda, nesta tabela é persistido um indicador de sucesso da requisição e o erro ocorrido durante a manipulação do JSON, se houver algum erro. Se a requisição for finalizada com sucesso, o status da requisição é gravado com 200, caso ocorra erro é gravado como 400.

Execução do programa da área

Para a execução do programa da área, isto é, o programa informado no campo cod-programa-area, o programa principal envia dois parâmetros para o programa da área: o nome do endpoint para o qual foi realizada a requisição e um objeto JSON com as informações retornadas pela API do portal da Conformidade Fácil.

A estrutura desse objeto JSON depende do tipo de retorno que foi feito pela API do portal da Conformidade Fácil. Se for um objeto JSON, a estrutura será a de um objeto JSON comum, mas se o retorno for uma lista de objetos será criado um objeto JSON para encapsular essa resposta e manter o parâmetro sempre do tipo objeto JSON.

Dessa forma, a estrutura de um programa de área seria:

DEFINE INPUT PARAMETER cEndpoint AS CHARACTER  NO-UNDO.
DEFINE INPUT PARAMETER oJson	 AS JsonObject NO-UNDO.

IF cEndpoint <> "credPresumido" THEN
    RETURN "NOK".

// Se a resposta for um JsonArray
IF oJson:has("response") THEN DO:
  // Restante da lógica do programa para persistência dos dados  
END.

Temp-Tables