PHSYS - Wiki

Conceito

A PHSYS API suporta a criação de endpoints, cadastrados no ServerConf para a realização de integrações com o sistema. Cada endpoint define um endereço que outra aplicação chama para executar um procedimento do sistema em uma base de dados.

O que é

É o cadastro dos endpoints da PHSYS API, realizado na tela EndPoints de API, disponível no menu lateral do ServerConf, através do botão Novo EndPoint. A aplicação integrada chama o endpoint pelo endereço do servidor de aplicação seguido de /api/ e do caminho cadastrado no campo EndPoint.

Para que serve

Serve para liberar integrações com o sistema de forma controlada: cada endpoint indica a base de dados, o usuário do ERP que executa a requisição, o procedimento executado e se a chamada exige autenticação por token.

Quais os benefícios e/ou ganhos de uso

• Integra outras aplicações ao sistema sem acesso direto ao banco de dados.
• Define por endpoint o que pode ser executado e em qual base de dados.
• Protege as integrações com autenticação OAuth2 e token com validade.
• Permite desativar um endpoint sem excluir o cadastro.
• Guarda o ClientSecret somente em forma cifrada, sem possibilidade de leitura posterior.

Regras de funcionamento

• Na inclusão, o ClientID e o ClientSecret são gerados automaticamente, e a validade do token inicia com 15 minutos.
• O ClientSecret é exibido somente no momento em que é gerado: na inclusão, no próprio campo, antes de salvar; depois, pelo botão Novo ClientSecret. Ele precisa ser copiado nesse momento, pois o sistema guarda apenas a forma cifrada.
• O caminho do campo EndPoint é único: não é possível cadastrar dois endpoints com o mesmo caminho. Os caminhos auth/token e auth/generate/credentials são exclusivos da PHSYS API.
• Com Exige Token marcado, a aplicação solicita o token pelo endpoint auth/token, enviando o ClientID e o ClientSecret, e envia o token recebido no cabeçalho Authorization das chamadas ao endpoint, no formato Bearer.
• O endpoint inativo responde como não encontrado e não gera token.
• Ao escolher o modelo PHSYS, a classe, o procedimento e os parâmetros do modelo Personalizado são apagados ao salvar.

Exemplos

• Pedidos vindos de uma loja virtual: um endpoint Personalizado com a classe e o procedimento que incluem o pedido, com Exige Token marcado. A loja solicita o token com o ClientID e o ClientSecret e envia cada pedido para o endpoint.
• Consulta de saldo por um parceiro: um endpoint Personalizado com o procedimento de consulta e um parâmetro fixo, por exemplo a empresa, informado em Parâmetros.
• Integração que precisa chamar procedimentos diferentes: um endpoint no modelo PHSYS, em que a aplicação informa no corpo da requisição o procedimento a executar, no padrão JSON da PHSYS.
• ClientSecret exposto: o botão Novo ClientSecret gera uma nova chave e invalida a anterior; em seguida, a nova chave é atualizada nas aplicações que usam o endpoint.

Cadastro

Campo	Finalidade
Descrição	Texto de identificação do endpoint.
Ativo	Situação do endpoint. Inativo, o endpoint não executa o procedimento definido e não gera token.
Base de dados	Base de dados em que o procedimento é executado quando a requisição é recebida.
EndPoint	Caminho do endpoint utilizado na integração, chamado no endereço do servidor de aplicação após /api/. Único entre os endpoints cadastrados.
Usuário	Usuário do ERP responsável pela execução da requisição.
Senha	Senha do usuário do ERP responsável pela execução do procedimento definido pela requisição. Na edição, o campo fica em branco e mantém a senha atual; para alterá-la, basta informar a nova senha.

Credenciais

Campo	Finalidade
ClientID	Identificador do cliente utilizado quando o modelo de autenticação OAuth2 está habilitado. Serve como parte do processo de geração do token. Gerado automaticamente na inclusão.
ClientSecret	Chave secreta utilizada em conjunto com o ClientID para autenticação OAuth2 e geração de tokens válidos. Em um endpoint já cadastrado, o botão Novo ClientSecret gera uma nova chave, que é exibida para cópia; a chave atual é invalidada permanentemente, sendo necessário atualizar todas as aplicações que a utilizam.
Minutos de validade do token	Tempo de expiração do token gerado. Após esse período, é necessário solicitar um novo token para continuar utilizando o endpoint, quando a autenticação é exigida.
Exige Token	Indica se o endpoint requer o envio de token válido no cabeçalho da requisição. Marcado, a requisição sem token, com token inválido ou com token expirado é recusada.

Modelo de Integração

Define a forma como o endpoint interage com o sistema. Cada modelo determina uma forma específica de execução da requisição.

Modelo	Finalidade
Personalizado	Modelo que permite informar previamente a classe e o procedimento a serem executados, dispensando o envio, no corpo da requisição, do procedimento a ser chamado.
PHSYS	Modelo no qual é necessário encaminhar, no corpo da requisição, o JSON no padrão da PHSYS. Esse formato permite executar procedimentos internos informando a estrutura diretamente no corpo da requisição.

Campos do modelo Personalizado:

Campo	Finalidade
Classe	Nome da classe onde o procedimento é executado.
Procedimento	Método da classe executado quando o endpoint é acionado. É responsável por realizar a lógica da integração.
Parâmetros	Lista de parâmetros enviados ao procedimento. Cada parâmetro representa uma informação necessária para a execução do método, com Nome, o nome do parâmetro esperado pelo procedimento, e Valor, o valor atribuído ao parâmetro, enviado de forma fixa pelo endpoint.

Conclusão

Os EndPoints de API definem, para cada integração, a base de dados, o usuário, o procedimento executado e a forma de autenticação. Com o token exigido e o ClientSecret guardado em sigilo, a aplicação integrada acessa somente o que o endpoint libera.