PHSYS - Wiki

Introdução

Este exemplo descreve como cadastrar produtos no sistema PHERP utilizando a PHSYS API. Por meio de um Script Específico, você pode integrar outro sistema, aplicativo ou serviço externo ao PHERP, facilitando o envio de dados para cadastrar novos produtos de forma automatizada.

A integração é realizada via o endpoint C_CadastrarProduto, onde você envia os dados no formato JSON e o sistema interpreta essas informações para cadastrar o produto no PHERP.

Modelo de Integração PHSys

Neste modelo de integração, o endpoint da PHSys API não possui um procedimento fixo associado. Em vez disso, ele interpreta o JSON enviado no corpo da requisição e executa exatamente o procedimento e o script informados nos parâmetros.Ou seja, o endpoint atua como um “executor genérico”: ele lê o conteúdo do JSON, identifica os campo:

PHSProcedimento → procedimento interno que será executado

PHSScriptNome → script específico registrado no PHERP e então o servidor executa o procedimento solicitado.

No exemplo apresentado, o procedimento informado é C_CadastrarProduto, responsável por realizar o cadastro de produtos dentro do PHERP. Assim, o JSON precisa incluir todos os parâmetros necessários para essa operação, como nome, referência, unidade, dimensões, etc.

Este modelo de integração foi utilizado a exigência do token de autenticação para garantir a segurança da comunicação porém o mesmo não é necessário. O processo foi dividido em duas etapas: geração do token e requisição de cadastro.

Modelo Integração

Como Realizar a Requisição do Token

Antes de realizar a requisição para o endpoint de cadastro de produtos, é necessário gerar um token de acesso. Esse token é utilizado para autenticar a requisição de cadastro e deve ser incluído nos cabeçalhos da requisição.

A URL deve seguir o padrão:

http://<servidor>:<porta>/api/auth/token

Exemplo típico:

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

Corpo da Requisição (Body)

Envia-se o client_id e client_secret para obter o token de autenticação:

{"client_id":"client_id",
 "client_secret":"client_secret"}

Exemplo de Envio utilizando Curl para Geração do Token

Para solicitar o token de autenticação, utilize o comando abaixo:

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

Resposta da Requisição

A resposta incluirá o access_token, que deverá ser usado nas requisições subsequentes para autenticação:

{
    "access_token": "token",
    "token_type": "Bearer",
    "expires_in": 900
}

Como Realizar a Requisição do EndPoit

Após gerar o token, você pode realizar a requisição para o endpoint de cadastro de produtos. O token gerado deve ser incluído no cabeçalho da requisição.

Cabeçalhos Necessários

A requisição deve incluir o cabeçalho Content-Type: application/json e o cabeçalho Authorization com o valor Bearer <token>.

Content-Type: application/json
Authorization: Bearer <token>

Estrutura da Requisição

A URL deve seguir o padrão:

http://<servidor>:<porta>/api/C_CadastrarProduto

Exemplo típico:

http://localhost:211/api/C_CadastrarProduto

Corpo da Requisição (Body)

O corpo da requisição deve conter um JSON com os parâmetros necessários para cadastrar o produto:

{ 
   "Classe":"TPHSProcScript", 
   "Procedimento":"Executar",
   "Parametros":[{
           "Nome":"PHSProcedimento",
           "Tipo":"string",
           "Valor":"C_CadastrarProduto"
       },
       {
           "Nome":"PHSScriptNome",
           "Tipo":"string",
           "Valor":"C_CadastrarProduto"
       },
       {
           "Nome":"Nome",
           "Tipo":"string",
           "Valor":"Computador"  
       },
       {
           "Nome":"Unidade",
           "Tipo":"integer",
           "Valor": 1  
       },
       {
           "Nome":"Referencia",
           "Tipo":"string",
           "Valor": "1234" 
       },
       {
           "Nome":"Comprimento",
           "Tipo":"float",
           "Valor": "30" 
       },
       {
           "Nome":"Largura",
           "Tipo":"float",
           "Valor": "15" 
       }           
   ]
}

Exemplo de Envio utilizando Curl

Para testar a requisição usando curl, o comando seria o seguinte:

curl -X POST "http://localhost:211/api/C_CadastrarProduto" ^
     -H "Content-Type: application/json" ^
     -H "Authorization: Bearer <token>" ^
     -d "{
           \"Classe\": \"TPHSProcScript\",
           \"Procedimento\": \"Executar\",
           \"Parametros\": [
             {\"Nome\": \"PHSProcedimento\", \"Tipo\": \"string\", \"Valor\": \"C_CadastrarProduto\"},
             {\"Nome\": \"PHSScriptNome\", \"Tipo\": \"string\", \"Valor\": \"C_CadastrarProduto\"},
             {\"Nome\": \"Nome\", \"Tipo\": \"string\", \"Valor\": \"Computador\"},
             {\"Nome\": \"Unidade\", \"Tipo\": \"integer\", \"Valor\": 1},
             {\"Nome\": \"Referencia\", \"Tipo\": \"string\", \"Valor\": \"1234\"},
             {\"Nome\": \"Comprimento\", \"Tipo\": \"float\", \"Valor\": 30},
             {\"Nome\": \"Largura\", \"Tipo\": \"float\", \"Valor\": 15}
           ]
         }"

Resposta da Requisição

A resposta da requisição dependerá do sucesso ou falha do procedimento. Se o cadastro for bem-sucedido, o ID do produto recém-cadastrado será retornado:

Resposta de Sucesso

{
  "ID_Produto": "159"
}

Resposta de Erro

{
  "Erro": "Produto com referência 1234 já cadastrado"
}

Exemplo de Script

Aqui está o script de exemplo que será executado no PHERP para realizar o cadastro do produto:

procedure C_CadastrarProduto;
var
  ProdutoObj:TPHServerClass;
  Q:TPHQuery;    
begin
  IniciarTransacao;
  try
    Q := NewPHQuery;                                                  
    try
      { Verifica se o Produto já Está Cadastrado }
      Q.Add('SELECT ID '+
            'FROM PRODUTOS '+
            'WHERE CODIGOREFERENCIA = :REF');
      Q.ParamByName('REF').AsString := ParamByName('Referencia').AsString;
      Q.Open;
  
      if (Q.Vazia) then
      begin                    
        ProdutoObj := NewPHServerClass('PRODUTOS');
        try
          ProdutoObj.NovoRegistro;
  
          { Preenchidos Através dos Parâmetros Presentes no Body da Requisição }            
          ProdutoObj.CampoDoNome('NOME').AsString             := ParamByName('NOME').AsString;
          ProdutoObj.CampoDoNome('CODIGOREFERENCIA').AsString := ParamByName('REFERENCIA').AsString;
          ProdutoObj.CampoDoNome('UNIDADEVENDA').AsInteger    := ParamByName('UNIDADE').AsInteger;
          ProdutoObj.CampoDoNome('UNIDADECOMPRA').AsInteger   := ParamByName('UNIDADE').AsInteger;          
          ProdutoObj.CampoDoNome('COMPRIMENTO').AsFloat       := ParamByName('COMPRIMENTO').AsFloat;
          ProdutoObj.CampoDoNome('LARGURA').AsFloat           := ParamByName('LARGURA').AsFloat;        
  
          { Preenchimento de Forma Fixa }  
          ProdutoObj.CampoDoNome('PERFILESTOQUE').AsInteger       := 11;
          ProdutoObj.CampoDoNome('NCM').AsInteger                 := 9875;
          ProdutoObj.CampoDoNome('CLASSIFICACAOORIGEM').AsInteger := 1;
  
          ProdutoObj.Salvar;
  
          ParamByName('Result').AsString := '{"ID_Produto":"'+IntToStr(ProdutoObj.CampoDoNome('ID').AsLargeInt)+'"}';                
        finally
          ProdutoObj.Free;
        end;                  
      end;

      ConfirmarTransacao;
    finally
      Q.Free;                  
    end;      
  except
    CancelarTransacao;

    ParamByName('Result').AsString := '{"Erro":"'+MensagemErro+'"}';
  end;          
end;

begin

end.