PHSYS - Wiki

Edição das 17h30min de 27 de novembro de 2023

Índice

1 Conceito
2 Estrutura do JSON de Requisição
3 Estrutura do JSON de Resposta
4 GetSessao e GetMetodo

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 executar, é 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 a serem enviados abrangem nove tipos distintos, é importante observar a formatação esperada por cada um deles. Esses tipos são:

string
integer
largeint
stream
boolean [ true | false ]
time [ hh:mm:ss ]
date [ yyyy-mm-dd ]
datetime [ yyyy-mm-dd hh:mm:ss ]
float [ 0.00000000 ]

Sendo assim, O formato do JSON no corpo (body) da requisição deve possuir a seguinte estrutura:

{"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").

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").

GetSessao e GetMetodo

A comunicação entre o cliente e o servidor é estabelecida por meio da operação GetSessao. Esta operação é essencial para criar uma sessão dedicada ao usuário que está solicitando a requisição. A sessão é automaticamente encerrada e destruída se não houver requisições ao servidor dentro de uma hora.

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

O corpo da resposta do servidor ao GetSessao contém o código da sessão, o qual deve ser armazenado para uso futuro. Este código será posteriormente adicionado à requisição GetMetodo.

Exemplo de Requisição GetSessao:

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

Exemplo de Resposta do Servidor para o GetSessao:

{
 "SessaoID": "1234567890abcdef1234567890abcdef"
}

Por meio da operação GetMetodo, é possível acionar diversas funcionalidades do sistema, como imprimir um pedido ou liberar um pedido para aprovação. No entanto, é imperativo que esta requisição seja feita utilizando uma sessão válida, obtida previamente por meio do GetSessao. Caso contrário, uma mensagem de erro será retornada, solicitando a obtenção de uma nova sessão.

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

Exemplo de Requisição GetMetodo:

GET https://localhost:211/GetMetodo?SessaoID=1234567890abcdef1234567890abcdef

Em resumo, a operação GetSessao é o ponto inicial para estabelecer uma comunicação, criando uma sessão que é posteriormente utilizada na requisição GetMetodo para executar funcionalidades do sistema.

@@ Linha 9: / Linha 9: @@
 ==='''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.
+As requisições devem ser enviadas via método POST. Para identificação de qual processo o servidor deve executar, é 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.
+Os parâmetros a serem enviados abrangem nove tipos distintos, é importante observar a formatação esperada por cada um deles. Esses tipos são:
+*string
+*integer
+*largeint
+*stream
+*boolean '''[ true | false ]'''
+*time '''[ hh:mm:ss ]'''
+*date '''[ yyyy-mm-dd ]'''
+*datetime '''[ yyyy-mm-dd hh:mm:ss ]'''
+*float '''[ 0.00000000 ]'''
-utilizando o seguinte formato de JSON no corpo (body) da requisição:
+Sendo assim, O formato do JSON no corpo (body) da requisição deve possuir a seguinte estrutura:
   {"Classe": "TPHSPedido",
@@ Linha 24: / Linha 33: @@
        	"Tipo": "string",
        	"Valor": "Isso é um teste"
-    	},
+    	 },
      	{
           "Nome": "Numero",
        	"Tipo": "integer",
        	"Valor": 1
-        }
+         }
    ]
   }
@@ Linha 35: / Linha 44: @@
 '''Parâmetros:'''
-'''Classe:''' Nome da classe a ser invocada no servidor, classe pode ser enviada no parametros também. Exemplo  {"Parametros": [{“Classe”:”TPHSPedido”}]}.
+*'''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”}]}.
+*'''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.
+*'''ID (Opcional):''' Identificador único associado à requisição.
-'''Empresa (Opcional):''' Identificador da empresa relacionada à requisição.
+*'''Empresa (Opcional):''' Identificador da empresa relacionada à requisição.
-'''Parametros (Opcional):''' Informações adicionais resultantes do processamento.
+*'''Parametros (Opcional):''' Informações adicionais resultantes do processamento.
-'''Nome (Obrigatório quando Parametros):''' Identificação do parâmetro.
+*'''Nome (Obrigatório quando Parametros):''' Identificação do parâmetro.
-'''Tipo (Obrigatório quando Parametros):''' Tipo de dado associado ao 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").
+*'''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'''===
@@ Linha 119: / Linha 83: @@
 '''Parâmetros:'''
-'''Parametros:''' Informações adicionais resultantes do processamento.
+*'''Parametros:''' Informações adicionais resultantes do processamento.
-'''Nome:''' Identificação do parâmetro.
+*'''Nome:''' Identificação do parâmetro.
-'''Tipo:''' Tipo de dado associado ao 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").
+*'''Valor:''' Valor do parâmetro, podendo ser uma string ou um stream (no caso do parâmetro "Arquivo").
-==='''Exemplos'''===
+==='''GetSessao e GetMetodo'''===
-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:'''
+A comunicação entre o cliente e o servidor é estabelecida por meio da operação GetSessao. Esta operação é essencial para criar uma sessão dedicada ao usuário que está solicitando a requisição. A sessão é automaticamente encerrada e destruída se não houver requisições ao servidor dentro de uma hora.
-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.
- https://localhost:211/GetSessao?Usuario=usuario@BaseDados&SENHA=Senha
+O corpo da resposta do servidor ao GetSessao contém o código da sessão, o qual deve ser armazenado para uso futuro. Este código será posteriormente adicionado à requisição GetMetodo.
+'''Exemplo de Requisição GetSessao:'''
+ GET 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:'''
+''' Exemplo de Resposta do Servidor para o GetSessao:'''
+ {
-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.
+  "SessaoID": "1234567890abcdef1234567890abcdef"
+ }
-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
+Por meio da operação GetMetodo, é possível acionar diversas funcionalidades do sistema, como imprimir um pedido ou liberar um pedido para aprovação. No entanto, é imperativo que esta requisição seja feita utilizando uma sessão válida, obtida previamente por meio do GetSessao. Caso contrário, uma mensagem de erro será retornada, solicitando a obtenção de uma nova sessão.
-  {
+  https://localhost:211/GetSessao?Usuario=usuario@BaseDados&SENHA=Senha
-  "Classe":"TPHSPedidoVenda",
-  "Procedimento":"Imprimir",
-  "ID":1825,
-  "Empresa":1
- }
+'''Exemplo de Requisição GetMetodo:'''
+ GET https://localhost:211/GetMetodo?SessaoID=1234567890abcdef1234567890abcdef
-Também foi realizado a liberação do pedido, seguindo o processo abaixo:
+Em resumo, a operação GetSessao é o ponto inicial para estabelecer uma comunicação, criando uma sessão que é posteriormente utilizada na requisição GetMetodo para executar funcionalidades do sistema.

PHSYS - Wiki

Mudanças entre as edições de "PHSYS API"

Edição das 17h30min de 27 de novembro de 2023

Índice

Conceito

Estrutura do JSON de Requisição

Estrutura do JSON de Resposta

GetSessao e GetMetodo

Pesquisa

Ferramentas pessoais

Ferramentas