PHSYS API
Índice
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/GetMetodo?SessaoID=1234567890abcdef1234567890abcdef
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.
Exemplos
1 - Liberação de Pedido de Venda
2 - Emissão de NF-e
