PHSYS - Wiki

Conceito

O sistema PHSYS é baseado em um modelo de requisições REST, permitindo receber requisições de diversas formas. Ele foi desenvolvido utilizando sessões, o que significa que é necessário fornecer um identificador de sessão (semelhante a um token ou secret key) para cada requisição direta ao sistema.

Uma integração REST é uma forma de comunicação entre sistemas que segue os princípios arquiteturais da web. Ela permite que diferentes sistemas se conectem e troquem informações de forma eficiente e padronizada.

Portanto, para enviar requisições ao servidor, é necessário primeiro solicitar um ID de sessão. Com esse ID de sessão, será possível realizar solicitações e enviar dados para o servidor.

A comunicação é baseada em requisições utilizando um formato JSON padronizado.

Estrutura do JSON de Requisição

As requisições devem ser enviadas via método POST. Para identificação de qual processo o servidor deve rodar, é necessário informar qual a classe e qual o procedimento será executado. Dados como ID, empresa e parâmetros são opcionais, mas devem ser informados dependendo do processo que será executado pelo servidor.

Os parâmetros que serão enviados, atualmente possui 9 tipos, sendo eles: string, integer, largeint, stream, boolean, time, date, datetime e float.

utilizando o seguinte formato de JSON no corpo (body) da requisição:

{"Classe": "TPHSPedido",
 "Procedimento": "Imprimir",
 "ID": 20,
 "Empresa": 1,
 “Parametros”:[
        {
        "Nome": "Texto",
     	"Tipo": "string",
     	"Valor": "Isso é um teste"
   	},
   	{
        "Nome": "Numero",
     	"Tipo": "integer",
     	"Valor": 1
       }
 ]
}

Parâmetros:

Classe: Nome da classe a ser invocada no servidor, classe pode ser enviada no parametros também. Exemplo {"Parametros": [{“Classe”:”TPHSPedido”}]}.

Procedimento: Nome do procedimento a ser executado na classe, procedimento pode ser enviada no parametros também. Exemplo {"Parametros": [{“Procedimento”:”Imprimir”}]}.

ID (Opcional): Identificador único associado à requisição.

Empresa (Opcional): Identificador da empresa relacionada à requisição.

Parametros (Opcional): Informações adicionais resultantes do processamento.

Nome (Obrigatório quando Parametros): Identificação do parâmetro.

Tipo (Obrigatório quando Parametros): Tipo de dado associado ao parâmetro.

Valor (Obrigatório quando Parametros): Valor do parâmetro, podendo ser uma string ou um stream (no caso do parâmetro "Arquivo").

FALAR SOBRE CADA TIPO DE PARAMETRO E A FORMATAÇÃO:

    vJson.AddPair('Nome', FParametros.Itens[I].Nome);
       if (FParametros.Itens[I].Tipo in [ptFloat]) then
       begin
         vJson.AddPair('Tipo', 'float');
         vJson.AddPair('Valor', FormatFloat('0.00000000',FParametros.Itens[I].AsFloat));
       end else
       if (FParametros.Itens[I].Tipo in [ptDateTime]) then
       begin
         vJson.AddPair('Tipo', 'datetime');
         vJson.AddPair('Valor', FormatDateTime('yyyy-mm-dd hh:mm:ss',FParametros.Itens[I].AsDateTime));
       end else
       if (FParametros.Itens[I].Tipo in [ptDate]) then
       begin
         vJson.AddPair('Tipo', 'date');
         vJson.AddPair('Valor', FormatDateTime('yyyy-mm-dd',FParametros.Itens[I].AsDate));
       end else
       if (FParametros.Itens[I].Tipo in [ptTime]) then
       begin
         vJson.AddPair('Tipo', 'time');
         vJson.AddPair('Valor', FormatDateTime('hh:mm:ss',FParametros.Itens[I].AsTime));
       end else
       if (FParametros.Itens[I].Tipo in [ptInteger]) then
       begin
         vJson.AddPair('Tipo', 'integer');
         vJson.AddPair('Valor', FParametros.Itens[I].AsInteger);
       end else
       if (FParametros.Itens[I].Tipo in [ptLargeint]) then
       begin
         vJson.AddPair('Tipo', 'largeint');
         vJson.AddPair('Valor', FParametros.Itens[I].AsLargeInt);
       end else
       if (FParametros.Itens[I].Tipo in [ptBoolean]) then
       begin
         vJson.AddPair('Tipo', 'boolean');
         if (FParametros.Itens[I].AsBoolean) then
           vJson.AddPair('Valor', 'true')
         else
           vJson.AddPair('Valor', 'false');
       end else
       begin
         vJson.AddPair('Tipo', 'string');
         vJson.AddPair('Valor', FParametros.Itens[I].AsString);
       end;

Estrutura do JSON de Resposta

O servidor responderá com um JSON, contendo todos os parâmetros processados, caso seja solicitado um arquivo como PDF, o servidor responderá com um parâmetro STREAM, contendo em Base64 todo o conteúdo do PDF. O JSON segue a seguinte estrutura:

{"Parametros": [
   {
     "Nome": "Parametros",
     "Tipo": "string",
     "Valor": ""
   },
   {
     "Nome": "Filtro",
     "Tipo": "string",
     "Valor": ""
   },
   {
     "Nome": "Arquivo",
     "Tipo": "stream",
     "Valor": "JVBERi0xLjcNCiXi48/....."
   }
 ]
}

Parâmetros:

Parametros: Informações adicionais resultantes do processamento.

Nome: Identificação do parâmetro.

Tipo: Tipo de dado associado ao parâmetro.

Valor: Valor do parâmetro, podendo ser uma string ou um stream (no caso do parâmetro "Arquivo").

Exemplos

Como exemplo, foi realizada a emissão de uma nota fiscal, para isso, utilizou-se o método POST, passando no parâmetro a sessaoid e no body, enviando o nome da classe, procedimento de emissão e o ID da nota que será emitida.

GetSessao:

GetSessao é necessário devido a comunicação entre cliente e servidor, criar uma sessão para o usuário que está solicitando a requisição, essa comunicação é encerrada e a sessão é destruída caso não haja requisições ao servidor dentro de 1 hora. A sessão será utilizada posteriormente ao requisitar o GetMetodo.

https://localhost:211/GetSessao?Usuario=usuario@BaseDados&SENHA=Senha

No body retornado pelo servidor, conterá o código da sessão, que deverá ser guardado e adicionado junto a requisição GetMetodo.

GetMetodo:

Após solicitar a sessão, será possível através de requisições utilizando o evento GetMetodo, acionar funcionalidades do sistema, como por exemplo: Imprimir um pedidom, liberar um Pedido para aprovação.

A Requisição GetMetodo, é obrigatória o uso de uma sessão válida, caso contrário será apresentado uma mensagem de erro solicitando uma sessão nova.

http://localhost:211/GetMetodo?SessaoID=000000000000000000000000

{
 "Classe":"TPHSPedidoVenda",
 "Procedimento":"Imprimir",
 "ID":1825,
 "Empresa":1
}

Também foi realizado a liberação do pedido, seguindo o processo abaixo: