Linha 1:

−

s

+

==='''Conceito'''===

+

A '''[[PHSYS_API|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 <b>EndPoints de API</b>, disponível no menu lateral do ServerConf, através do botão <b>Novo EndPoint</b>. A aplicação integrada chama o endpoint pelo endereço do servidor de aplicação seguido de <b>/api/</b> 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 <b>Novo ClientSecret</b>. 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 <b>auth/token</b> e <b>auth/generate/credentials</b> são exclusivos da PHSYS API.

+

*Com '''Exige Token''' marcado, a aplicação solicita o token pelo endpoint <b>auth/token</b>, enviando o ClientID e o ClientSecret, e envia o token recebido no cabeçalho <b>Authorization</b> das chamadas ao endpoint, no formato <b>Bearer</b>.

+

*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 <b>Novo ClientSecret</b> gera uma nova chave e invalida a anterior; em seguida, a nova chave é atualizada nas aplicações que usam o endpoint.

+

==='''Cadastro'''===

+

{| class="wikitable"

+

!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 <b>/api/</b>. Ú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'''

+

{| class="wikitable"

+

!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 <b>Novo ClientSecret</b> 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.

+

{| class="wikitable"

+

!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''':

+

{| class="wikitable"

+

!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.

EndPoints de API - Histórico de revisão

Admin em 00h27min de 15 de outubro de 2026

Admin: Criou página com 's'

← Edição anterior		Edição das 00h27min de 15 de outubro de 2026
Linha 1:		Linha 1:
−	s	+	==='''Conceito'''===
		+	A '''[[PHSYS_API\|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 <b>EndPoints de API</b>, disponível no menu lateral do ServerConf, através do botão <b>Novo EndPoint</b>. A aplicação integrada chama o endpoint pelo endereço do servidor de aplicação seguido de <b>/api/</b> 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 <b>Novo ClientSecret</b>. 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 <b>auth/token</b> e <b>auth/generate/credentials</b> são exclusivos da PHSYS API.
		+	*Com '''Exige Token''' marcado, a aplicação solicita o token pelo endpoint <b>auth/token</b>, enviando o ClientID e o ClientSecret, e envia o token recebido no cabeçalho <b>Authorization</b> das chamadas ao endpoint, no formato <b>Bearer</b>.
		+	*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 <b>Novo ClientSecret</b> gera uma nova chave e invalida a anterior; em seguida, a nova chave é atualizada nas aplicações que usam o endpoint.
		+
		+	==='''Cadastro'''===
		+	{\| class="wikitable"
		+	!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 <b>/api/</b>. Ú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'''
		+	{\| class="wikitable"
		+	!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 <b>Novo ClientSecret</b> 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.
		+	{\| class="wikitable"
		+	!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''':
		+	{\| class="wikitable"
		+	!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.