Questões frequentes sobre a Web API

1. O que é a Web API do ERP?

A Web API é uma interface RESTful que permite a integração do ERP com outras aplicações e serviços.

Expõe os recursos do ERP através de endpoints estruturados, facilitando operações como criação, leitura, atualização e eliminação de dados.  

2. Como é estruturada a arquitetura da Web API?

A arquitetura da Web API inclui uma camada de integração responsável pela ligação ao ERP, que gere os pedidos de autenticação armazenando-os em cache com base no token gerado.

A Web API expõe os métodos públicos do motor do ERP e invoca diretamente essa API, sem adicionar regras de negócio adicionais.  

Existem, no entanto, alguns métodos específicos da Web API, cuja lógica de negócio está espelhada no Controller da Web API. Por exemplo, o método CreateSalesDocument do controller das vendas. 

3. Como funciona o processo de autenticação na Web API?

A autenticação na Web API utiliza o padrão OAuth 2.0. Os pedidos devem ser precedidos por uma chamada ao endpoint/token, fornecendo credenciais como o nome de utilizador, palavra-passe, código da empresa, instância do ERP, linha de produto e uma sessionkey. A resposta inclui um access_token que deve ser utilizado nos headers dos pedidos subsequentes. 

4. O que é a sessionkey e qual a sua importância na Web API?

A sessionkey é um identificador obrigatório usado na autenticação da Web API do ERP. 

Quando não é fornecido um sessionKey no pedido de token, a Web API gera um sessionKey implícito que é associado ao token.

Este identificador representa o contexto de integração da aplicação cliente com o ERP e permite ao sistema associar os pedidos a uma sessão específica, sem necessidade de manter sessões de utilizador na camada do servidor (IIS).  

Este sessionKey é a chave para que se possam realizar vários pedidos em simultâneo, mesmo com diferentes tokens, sem que exista o risco de diferentes threads acedam a informação que diz respeito a outro contexto de integração. 

Principais características

• Obrigatória na chamada ao endpoint/token para obter o access_token;
• Pode ser qualquer valor definido pela aplicação cliente (exemplo: nome da app, GUID, etc.);
• Deve ser única por instância da aplicação cliente. Não deve ser partilhada entre utilizadores diferentes ou processos concorrentes;
• Serve para identificar e isolar o contexto de execução no ERP (empresa, instância, linha de produto, etc.). 

Boas práticas

• Definir a sessionkey de forma consistente por aplicação ou integração;
• Em ambientes multi-utilizador, utilizar valores dinâmicos (ex: nomeApp_utilizador ou GUIDs). 

5. Qual é a estrutura dos endpoints da Web API?

Os endpoints seguem a estrutura: http://localhost:2018/WebApi/{modulo}/{entidade}/{servico}/ 

Na versão 2 da Web API, os endpoints incluem o prefixo v2, ou seja: http://localhost:2018/WebApi/v2/{modulo}/{entidade}/{servico}/ 

Legenda:

• Módulo: identifica o módulo do ERP;
• Entidade: especifica a entidade de negócio;
• Serviço: determina a operação a ser executada. 

6. O que é o Swagger e como é utilizado na Web API?

O Swagger é uma ferramenta de documentação e invocação de métodos da Web API.

A partir da versão 2 da Web API v10, o Swagger torna-se a página de apresentação da Web API, permitindo aos utilizadores explorar os módulos disponíveis, visualizar detalhes dos métodos e testar chamadas diretamente através da interface.  

7. Quais são as principais novidades da versão 2 da Web API?

A versão 2 da Web API introduz as seguintes melhorias em relação à versão anterior:  

• Respostas com estrutura uniforme para todos os métodos;
• Utilização dos métodos HTTP GET, POST, PUT e DELETE;
• Bloqueio de pedidos simultâneos para o mesmo contexto de integração, configurável através da opção BlockMultipleRequestsPerContext no ficheiro web.config;
• Integração do Swagger como ferramenta principal de documentação e invocação.  

8. Como é estruturada a resposta dos pedidos na versão 2?

Na versão 2, todas as respostas seguem a estrutura: 

{ 

  "Version": "string", 

  "StatusCode": 0, 

  "ErrorMessage": "string", 

  "Results": {} 

} 

Esta uniformização facilita o tratamento das respostas por parte dos clientes, independentemente do método invocado. 

9. Como proceder quando o token de autenticação expira?

Quando o token expira, a Web API retorna o erro 401 – Unauthorized. Neste caso, deve ser realizado um novo pedido ao endpoint/token, utilizando o mesmo método do pedido inicial.

Para reutilizar o mesmo contexto de integração, é recomendável incluir o token expirado no header Authorization do novo pedido.  

10. Existe um método para efetuar logout e libertar recursos?

Sim. A Web API disponibiliza um endpoint de logout que permite libertar recursos associados a um determinado contexto de utilização. Este método é invocado sem parâmetros, mas requer a identificação do token no header Authorization do pedido.

A utilização deste endpoint ajuda a libertar memória do processo do IIS e a remover sessões inativas na base de dados. 

11. É possível efetuar chamadas simultâneas à Web API?

Sim. Épossível efetuar chamadas simultâneas à Web API, mas com algumas restrições que dependem da configuração do servidor e do modo como a sessionkey é utilizada. 

Por predefinição:

• a Web API permite múltiplos pedidos em simultâneo;
• todos os pedidos realizados em simultâneo devem garantir que são efetuados com diferentes tokens, que por sua vez foram solicitados com diferentes sessionkeys;
• a Web API pode bloquear pedidos concorrentes efetuados com o mesmo token (e que tenham a mesma sessionkey) para proteger a consistência dos dados e evitar conflitos. 

O comportamento é controlado pela opção < add key="BlockMultipleRequestsPerContext" value="true" / > , em que:

• true (predefinição): bloqueia chamadas simultâneas que usem o mesmo token e sessionkey;
• false: permite múltiplas chamadas simultâneas mesmo que partilhem o mesmo contexto. Não é recomendado uma vez que pode causar inconsistências.

A aplicação desta definição a false só deve ser utilizada se for garantido que as chamadas à Web API não utilizarão o BSO (motor do ERP) ou PSO (Plataforma). Por exemplo: invocação de endpoints de extensibilidade que têm uma camada própria de acesso a dados.

Boas práticas

• Em aplicações com chamadas concorrentes (exemplo: integrações assíncronas, background workers), usar sessionkeys diferentes por instância/processo;
• Se for necessário partilhar a mesma sessionkey, organizar as chamadas de forma sequencial ou ativar a gestão de concorrência no lado do cliente. 

12. O que acontece ao contexto de integração quando o token expira?

Quando o access_token expira, o contexto de integração associado não é automaticamente libertado. 

Este comportamento permite que, mesmo quando um token expira, um novo pedido de token possa ser realizado (identificando no cabeçalho o token entretanto expirado) e, desta forma, reaproveitado o contexto de integração. 

Por omissão, o contexto de integração (definido pela sessionkey, empresa, instância e linha de produto) permanece ativo mesmo após a expiração do token. Tal significa que os recursos continuam alocados na aplicação (memória, sessões de utilizador e ligação ao ERP, incluindo as conexões à base de dados), podendo afetar o desempenho do servidor se não forem libertados manualmente. 

Para libertar os recursos corretamente, é necessário:

• chamar explicitamente o endpoint de logout, que termina o contexto de integração e liberta os recursos;
• incluir no logout o token (mesmo expirado) no header Authorization, para que a Web API saiba qual contexto eliminar. 

POST /WebApi/Base/Logout 

Authorization: Bearer {access_token} 

Nota: a não libertação do contexto pode deixar sessões presas na base de dados do ERP e manter objetos em memória no IIS. Isto é especialmente relevante em sistemas com elevada carga ou múltiplas integrações. 

Boas práticas

• Sempre que possível, implementar um logout explícito após o fim de uma operação ou sessão;
• Em sistemas críticos, considerar mecanismos automáticos no cliente para encerrar o contexto ou pedir novo token quando o token estiver prestes a expirar. 

O access_token obtido através da autenticação OAuth 2.0 na Web API v10 tem, por predefinição, um tempo de expiração de 20 minutos. 

Este tempo pode ser definido no ficheiro Web.config no AppSetting TokenExpirationMinutes.  

13. O que acontece se desativar a opção BlockMultipleRequestsPerContext e fizer pedidos simultâneos com o mesmo token e sessionkey?

Se desativar a opção BlockMultipleRequestsPerContext no ficheiro web.config, a Web API deixa de impedir que sejam efetuadas chamadas simultâneas com o mesmo token e a mesma sessionkey. 

Ao desativar esta opção, existem diversos riscos:

• O contexto de integração (memória, objetos, transações em curso) é partilhado entre os pedidos concorrentes;
• Como a Web API não implementa isolamento interno entre chamadas com a mesma sessionkey, podem ocorrer conflitos de dados, corrupção de estado ou comportamentos imprevisíveis;
  1. Exemplo 1: ao gravar dois documentos de vendam pode ser retornado o mesmo número de documento para os dois pedidos; 
  2. Exemplo 2: pode gerar erros de vários tipos - object reference not set to an instance of an object, parameter count mismatch, etc.;
• Tal é especialmente perigoso em operações que alterem dados ou que envolvam múltiplas etapas (exemplo: inserções, atualizações, processos de negócio complexos). 

É recomendável:

• Manter BlockMultipleRequestsPerContext = true;
• Se forem necessárias chamadas em paralelo, usar sessionkeys distintos por pedido ou processo para garantir isolamento de contexto;
• Monitorizar o impacto e comportamento da API caso decida alterar esta configuração. 

14. É possível ter mais do que uma instância da Web API v10 no IIS? E em múltiplos servidores IIS?

Sim. É totalmente possível ter mais do que uma instância da Web API v10, tanto no mesmo servidor IIS como em vários servidores diferentes. 

No mesmo IIS: 

• Pode criar várias aplicações Web separadas no IIS, cada uma com o seu próprio diretório virtual e configuração da Web API;
• Partindo do pressuposto que as diferentes aplicações apontam para a mesma diretoria física Apl\WebAPI, não há necessidade de qualquer alteração nos ficheiros de configuração;
• Cada aplicação Web pode ter uma application pool distinta e desta forma garantir gestão de recursos separada;
• Deve garantir que as portas e os bindings HTTP usados são diferentes para evitar conflitos. 

Em múltiplos servidores IIS: 

• Pode instalar a Web API v10 nos servidores pretendidos. É especialmente útil nos cenários de alta disponibilidade, load balancin ou separação por cliente;
• O acesso ao ERP é efetuado via API de produto, portanto o requisito principal é que o servidor da Web API tenha acesso ao ERP;
• Atualmente, esta instalação não é realizada via Deployment Center, mas pode ser realizada pelo cliente. Os binários da Web API estão na pasta Apl/WebAPI. 

Boas práticas

• Usar nomes distintos para os diretórios/app pools das Web APIs no IIS;
• Em ambientes com múltiplas instâncias, documentar os endpoints e configurações para evitar confusões;
• Monitorizar o consumo de recursos (RAM, CPU, ligações à BD) por instância. 

15. A Web API v10 gera logs? Onde posso consultá-los e configurar?

Sim. A Web API v10 utiliza o NLog como mecanismo de logging para registar atividades, erros e eventos internos. Estes logs são essenciais para o diagnóstico de problemas e análise de comportamento da API.  

Por predefinição, os logs são gravados na pasta Apl\WebAPI.

 Nos logs, são registados:

• erros internos da Web API (exceptions, falhas de autenticação, problemas de acesso ao ERP);
• detalhes dos pedidos recebidos (endpoints, tempo de resposta, códigos de estado);
• eventos críticos como falhas de login, chamadas não autorizadas, ou problemas de comunicação com a base de dados. 

O nível de verbosidade dos logs e os targets pode ser ajustado no ficheiro web.config, na secção de logging. Pode definir níveis como: 

• Error 
• Warning 
• Info 
• Debug (mais detalhado, sendo útil para desenvolvimento) 

  Boas práticas

• Em produção, usar níveis de log mais restritivos (Error ou Warning) para evitar ficheiros demasiado grandes;
• Em desenvolvimento ou em caso de erro, ativat o nível Debug temporariamente para obter mais detalhes;
• Monitorizar o espaço em disco da pasta de logs, especialmente em ambientes com elevada carga de pedidos.