Características da Web API

A Web API da versão 10 do ERP possui algumas características próprias que deverá conhecer antes de a começar a utilizar e que serão apresentadas abaixo.

Instalação

Antes de começar, é necessário possuir o módulo da WebAPI instalado e o servidor IIS configurado e a executar. A Web API é sempre executada num servidor local, ou seja, na infraestrutura do cliente.

Outra particularidade da Web API é que esta não tem de ser necessariamente instalada na mesma máquina do ERP Primavera. Pode instalar a Web API num servidor dedicado, sendo apenas necessário modificar a chave "ERPInstalationPath" no Web.Config.

Endpoints da Web API 

A Web API disponibiliza os endpoints de serviço num formato de rotas específico. Todas as rotas estão construídas à semelhança da API, de forma a facilitar a compreensão dos vários recursos.

URL:

http://localhost:2018/WebApi/{modulo}/{entidade}/{servico}/

A rota tem sempre a mesma estrutura com os seguintes elementos variáveis:

• Módulo: identifica o módulo a que pertence a resource do pedido.
• Entidade: identifica a entidade sobre à qual se pretende aceder.
• Serviço: identifica a operação a executar.

Exemplo:

http://localhost:2018/WebApi/Base/Clientes/Actualiza

No administrador do ERP, é possível controlar o acesso aos serviços existentes na Web API, tendo em consideração as definições do perfil atribuído ao utilizador.

Autenticação

A Web API requer a autenticação de todos os pedidos efetuados. O método de autenticação utilizado é o standard OAuth 2.0.

Na prática, os pedidos à Web API devem ser precedidos por uma chamada a um endpoint que fará a autenticação do utilizador e da aplicação. Esse endpoint é o seguinte:

http://localhost:2018/WebApi/token

Os parâmetros são os seguintes:

• username: nome do utilizador utilizado do ERP.
• password: palavra-passe do utilizador do ERP.
• company: código da empresa.
• instance: instancia do ERP, tipicamente “Default”.
• line: um dos seguintes valores "evolution", "executive" ou "professional"
• grant_type: tipo de autenticação utilizada pelo framework OAuth 2. Neste caso será sempre “password”;
• sessionkey: representa uma chave única que disponibilizará um contexto de integração independente e isolado dos demais pedidos.

A resposta deste pedido fornecerá o link de redirect para o endpoint com os dados da autenticação:

• access_token: o token de autenticação com o respetivo tempo de vida.
• token_type: Bearer.
• expires_in: 1199.

Estes dados devem ser utilizados nos pedidos seguintes à Web API, acrescentando-lhes os seguintes headers:

• Authorization: Bearer {acess_token}.
• Accept: application/json.

O tempo definido para a expiração do token (expired_in) pode ser alterado no ficheiro Web.config, no setting TokenExpirationMinutes:

Renovação do Token

Quando o token expira, é retornado um erro 401 – Unauthorized com a mensagem “Authorization has been denied for this request.” Neste cenário, deve ser realizado o pedido de novo token, utilizando o mesmo método do primeiro pedido (/token).

Para que a renovação do token reutilize o mesmo contexto de integração, garantindo a otimização dos recursos e maior celeridade na resposta, deve ser indicado no header do pedido o token anterior, entretanto expirado (header Authorization).