PHSYS - Wiki

Conceito

Este processo documenta como consumir um endpoint protegido da PHSYS API com OAuth2.

O fluxo possui 2 etapas:

• Obter o access_token em /api/auth/token usando client_id e client_secret.
• Enviar o token no cabeçalho Authorization: Bearer para consumir o endpoint de negócio.

Pré-Requisitos

No cadastro do endpoint no PHServerConf:

• Exige Token: Sim
• ClientID: gerado no cadastro do endpoint
• ClientSecret: gerado no cadastro do endpoint
• Minutos de validade do token: conforme política de segurança da integração

Etapa 1 - Obter Token

URL de autenticação:

http://localhost:211/api/auth/token

Método HTTP:

POST

Cabeçalho:

• Content-Type: application/json

Body:

{
  "client_id": "SEU_CLIENT_ID",
  "client_secret": "SEU_CLIENT_SECRET"
}

Resposta esperada (exemplo):

{
  "access_token": "abc123...",
  "token_type": "Bearer",
  "expires_in": 900
}

Etapa 2 - Consumir Endpoint Protegido

URL do endpoint de negócio:

http://localhost:211/api/pherp/solicitacoes

Método HTTP:

POST

Cabeçalhos:

• Content-Type: application/json
• Authorization: Bearer <access_token>

Body (exemplo):

{
  "MetodoScript": "Cadastrar",
  "Cliente": "2",
  "Solicitante": "2",
  "TiposSolicitacao": "3",
  "Requisito": "2",
  "Prioridade": "2",
  "DescricaoResumida": "Solicitacao de exemplo para teste da API",
  "Descricao": "Descricao detalhada da solicitacao de exemplo."
}

Exemplo em Script

procedure ExecutarRequisicao;
var
  Requisicao: TPHConexaoREST;
  Token: String;
begin
  Token := ObterToken;

  Requisicao := NewPHConexaoREST;
  try
    Requisicao.URL := 'http://localhost:211/api/pherp/solicitacoes';
    Requisicao.ContentType := 'application/json';
    Requisicao.AddHeader('Authorization', 'Bearer ' + Token);
    Requisicao.Metodo := 'POST';
    Requisicao.Body :=
      '{' +
        '"MetodoScript":"Cadastrar",' +
        '"Cliente":"2",' +
        '"Solicitante":"2",' +
        '"TiposSolicitacao":"3",' +
        '"Requisito":"2",' +
        '"Prioridade":"2",' +
        '"DescricaoResumida":"Solicitacao de exemplo para teste da API",' +
        '"Descricao":"Descricao detalhada da solicitacao de exemplo."' +
      '}';
    Requisicao.Executar;

    Informacao(Requisicao.Retorno);
  finally
    Requisicao.Free;
  end;
end;

function ObterToken: String;
var
  Requisicao: TPHConexaoSSLREST;
  JSON: TPHJson;
begin
  Requisicao := NewPHConexaoSSLREST;
  try
    Requisicao.URL := 'http://localhost:211/api/auth/token';
    Requisicao.ContentType := 'application/json';
    Requisicao.Body :=
      '{' +
        '"client_id":"' + ClientID + '",' +
        '"client_secret":"' + ClientSecret + '"' +
      '}';
    Requisicao.Post;

    JSON := TPHJson.Create;
    try
      JSON.LerJson(Requisicao.Retorno);
      Result := JSON.ElementoDoNome('access_token').Texto;
    finally
      JSON.Free;
    end;
  finally
    Requisicao.Free;
  end;
end;

begin
  ExecutarRequisicao;
end.

Exemplo de Requisições cURL

Obter token:

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

Consumir endpoint protegido:

curl -X POST "http://localhost:211/api/pherp/solicitacoes" ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer <access_token>" ^
  -d "{\"MetodoScript\":\"Cadastrar\",\"Cliente\":\"2\",\"Solicitante\":\"2\",\"TiposSolicitacao\":\"3\",\"Requisito\":\"2\",\"Prioridade\":\"2\",\"DescricaoResumida\":\"Solicitacao de exemplo para teste da API\",\"Descricao\":\"Descricao detalhada da solicitacao de exemplo.\"}"

Boas Práticas

• Tratar retorno de erro da autenticação antes de chamar o endpoint de negócio.
• Centralizar a função ObterToken para reutilização em outras integrações.

Conclusão

A autenticação por OAuth2 permite proteger os endpoints da PHSYS API, garantindo que somente aplicações previamente autorizadas possam realizar requisições.

O fluxo de consumo é simples e padronizado: primeiro, a aplicação obtém um access_token utilizando o client_id e o client_secret configurados no endpoint. Em seguida, o token obtido é enviado no cabeçalho Authorization, no formato Bearer, para autenticar as requisições aos endpoints protegidos.

Dessa forma, o mesmo mecanismo de autenticação pode ser utilizado por diferentes aplicações e integrações, mantendo as credenciais de acesso separadas da operação de negócio e permitindo o controle da validade dos tokens conforme a política de segurança definida para cada endpoint.