PHSYS - Wiki

Índice

1 Conceito
2 URL Base
3 EndPoints
4 Exemplos
- 4.1 Modelo de Integração [Personalizado]
- 4.2 Modelo de Integração [PHSYS]

Conceito

A PHSYS API é uma camada de integração que permite a comunicação entre sistemas externos e o PHERP por meio de requisições REST. Diferente de uma API tradicional rígida, a PHSYS API funciona com um modelo dinâmico e configurável, onde cada endpoint é cadastrado diretamente no servidor de aplicação e associado a procedimentos internos do sistema. Esse modelo permite que novas integrações sejam criadas, bastando configurar o endpoint, a classe executada e os parâmetros envolvidos.

O funcionamento da PHSYS API consiste, portanto, em um fluxo simples: o cliente envia uma requisição REST para um endpoint cadastrado, o servidor processa a requisição conforme as regras definidas e executa o procedimento interno correspondente. Dessa forma, a API garante flexibilidade, segurança e integração direta com os recursos internos do ERP.

URL Base

A URL Base da PHSYS API corresponde ao endereço do servidor de aplicação onde o serviço está sendo executado, seguido do caminho padrão /api, que identifica o módulo de integração da plataforma. Todas as requisições enviadas ao PHSYS devem utilizar essa URL Base como ponto inicial, adicionando ao final o endpoint configurado no servidor.

A estrutura geral da URL Base é:

http://<endereço_do_servidor>:<porta>/api/<endpoint>

Exemplo em ambiente local:

http://localhost:211/api/IntegracaoScriptEspecifico

Nessa composição:

localhost: Endereço do servidor.
211: Porta onde o serviço do PH Server está sendo executado.
/api/: Indica o caminho de integração da PHSYS API.
IntegracaoScriptEspecifico: Endpoint configurado pelo administrador no servidor de aplicação.

Cada endpoint cadastrado no servidor se torna acessível adicionando seu nome ao final da URL Base, permitindo assim organizar diferentes integrações de forma clara e padronizada.

EndPoints

Os endpoints da PHSYS API são rotas configuradas no servidor de aplicação que representam os pontos de entrada das requisições enviadas pelos sistemas integrados. Cada endpoint define qual procedimento interno do PHERP será executado quando uma requisição REST for recebida, bem como suas regras de autenticação, base de dados e usuário do PHERP responsável pela execução.

Após o cadastro, o endpoint passa a responder pelo nome configurado, permitindo que a aplicação cliente envie requisições diretamente para ele. A API então identifica o endpoint chamado, executa o procedimento interno associado.

Cadastro

O cadastro do endpoint é realizado diretamente no servidor de aplicação, onde, por meio da página EndPoints de API, é possível visualizar os endpoints existentes, editar suas configurações ou criar novos conforme a necessidade da integração.

Nesse cadastro, podem ser definidos o nome do endpoint que será exposto, bem como o usuário e a senha do PHERP que serão utilizados para executar os procedimentos internos vinculados à integração. Também é possível configurar a descrição, a base de dados utilizada durante o processamento e a situação de ativação, permitindo habilitar ou desabilitar o endpoint conforme o uso desejado.

Modelo de Integração

O endpoint pode ser configurado com diferentes modelos de integração, que definem como o procedimento interno do PHERP será acionado quando a requisição for recebida.

Personalizado: Neste modelo, o administrador informa diretamente a Classe e o Procedimento que serão executados quando o endpoint for chamado. A requisição não precisa enviar no body qual procedimento será utilizado, pois tudo já está definido no cadastro do endpoint. Também é possível configurar parâmetros fixos, que serão automaticamente enviados ao procedimento interno durante a execução.

PHSYS: No modelo PHSYS, a própria requisição define qual procedimento será executado, utilizando um JSON no padrão interno da PHSYS. Nesse formato, o cliente especifica no body informações como classe, procedimento e parâmetros. O endpoint funciona como um ponto de entrada genérico, permitindo maior flexibilidade no envio das operações.

Estrutura de body PHSYS: Essa é a estrutura padrão esperada no body para requisições em que o modelo de integração é PHSYS, no qual 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.
Procedimento: Nome do procedimento a ser executado na classe, procedimento pode ser enviada no parametros também.
ID (Opcional): Identificador único associado à requisição.
Empresa (Opcional): Identificador da empresa relacionada à requisição.
Parametros (Opcional): 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").

Autenticação OAuth2

O endpoint pode ser configurado para utilizar autenticação baseada no padrão OAuth2. Quando essa opção está habilitada, a requisição só será processada se apresentar um token Bearer válido no cabeçalho. Esse mecanismo garante maior segurança no acesso aos procedimentos internos do PHERP. A autenticação é controlada pelos seguintes parâmetros no cadastro do endpoint:

Exige Token: Quando ativado, o endpoint passa a aceitar apenas requisições que enviem um token válido no cabeçalho Authorization: Bearer <token>. Caso o token esteja ausente, expirado ou inválido, a API rejeita a requisição automaticamente.

Minutos de validade do token: Define por quanto tempo o token gerado permanecerá válido. Após esse período, será necessário solicitar um novo token para continuar realizando requisições ao endpoint protegido.

Além disso, a autenticação utiliza as credenciais de ClientID e ClientSecret, que são geradas automaticamente no momento do cadastro do endpoint e são únicas para cada integração. O ClientID identifica o cliente solicitante, enquanto o ClientSecret é a chave secreta associada a ele. É importante destacar que o ClientSecret é exibido apenas uma vez, caso seja perdido, será necessário gerar um novo. Ambos são utilizados no processo de geração do token para garantir que somente clientes autorizados tenham acesso ao endpoint.

Para solicitar o token, o cliente deve realizar uma requisição ao endpoint exclusivo de autenticação da PHSYS API, enviando o client_id e client_secret no body para obtenção de um token válido.

Exemplo de Requisição de Token:

Requisição:

curl -X POST "http://localhost:211/api/auth/token" ^
  -H "Content-Type: application/json" ^
  -d "{\"client_id\":\"MjQ2MDg2NzItQjQxOC00N0IwLUI1MUYtNzE4QjgwRUNCNDZB\",                  
       \"client_secret\":\"REYyMDA1MEItODkzOS00RjZCLTk3OEYtMDNFOUNEOEY4MEVERURGMTEzNTAtQjQwOS00OTk2LUFBN0EtMkVGNUZENTM5NUY5\"}"

Resposta:

{ "access_token": "1f0e169c1b63c34236d3dc7f6b841e5b5ac066c492eb771fdf18b357a1b4f129",   
  "token_type": "Bearer",   
  "expires_in": 900 }

Com o access_token nas proximas requisições será necessário enviar no header da reqisição com o Authorization: Bearer + <access_token>, caso não encaminhado, será retornado que não está autorizado.

curl -X GET "http://localhost:211/api/IntegracaoScriptEspecifico" -H ^
"Authorization: Bearer 1f0e169c1b63c34236d3dc7f6b841e5b5ac066c492eb771fdf18b357a1b4f129"

Caso o cabeçalho não seja enviado corretamente, a API retornará erro de autorização.

Em resumo, ao habilitar OAuth2, o endpoint passa a operar com uma camada adicional de segurança, exigindo que o cliente obtenha um token válido antes de consumir qualquer recurso da PHSYS API.

Fluxograma de autenticação OAuth2 na API

Imagem do esquema de autenticação de API

Resposta da Requisição

O parâmetro Result determina o conteúdo que será retornado ao cliente após a chamada ao endpoint. Em scripts específicos, é possível definir esse valor de retorno utilizando o comando abaixo, atribuindo qualquer texto ou JSON conforme a necessidade da integração:

ParamByName('Result').AsString := <texto ou JSON>;

Esse mecanismo permite que o endpoint responda com um JSON de sucesso, com dados processados ou com qualquer outra informação relevante, garantindo uma resposta totalmente personalizada de acordo com a lógica implementada no procedimento. Isso permite que o endpoint seja totalmente personalizado, retornando exatamente o que o integrador necessita.

GetBody

O método GetBody permite acessar o body enviado na requisição ao endpoint. Quando o modelo de integração é personalizado, o script pode ler e manipular livremente o conteúdo recebido, independentemente do formato encaminhado pelo cliente. Isso possibilita utilizar o body para validações, transformações, extrações de dados ou qualquer outro tipo de processamento necessário, oferecendo flexibilidade total para trabalhar com diferentes estruturas e requisitos de integração.