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

(Criou página com '==='''Conceito'''=== O sistema PHSYS é baseado em um modelo de requisições REST, permitindo receber requisições de diversas formas. Ele foi desenvolvido utilizando sessõ...')
 
Linha 9: Linha 9:
  
 
==='''Estrutura do JSON de Requisição'''===
 
==='''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",
 
  {"Classe": "TPHSPedido",
Linha 24: Linha 33:
 
       "Tipo": "string",
 
       "Tipo": "string",
 
       "Valor": "Isso é um teste"
 
       "Valor": "Isso é um teste"
    },
+
    },
 
     {
 
     {
 
         "Nome": "Numero",
 
         "Nome": "Numero",
 
       "Tipo": "integer",
 
       "Tipo": "integer",
 
       "Valor": 1
 
       "Valor": 1
        }
+
        }
 
   ]
 
   ]
 
  }
 
  }
Linha 35: Linha 44:
 
'''Parâmetros:'''
 
'''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'''===
 
==='''Estrutura do JSON de Resposta'''===
Linha 119: Linha 83:
 
'''Parâmetros:'''
 
'''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.

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

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.