Frequently asked questions about the Web API

1. What is the ERP Web API?

The Web API is a RESTful interface that allows the ERP to be integrated with other applications and services.

It exposes ERP resources through structured endpoints, making operations such as creating, reading, updating and deleting data easier.

2. How is the Web API architecture structured?

The Web API architecture includes an integration layer responsible for the connection to the ERP, which manages authentication requests by storing them in a cache based on the token generated.

The Web API exposes the public methods of the ERP engine and invokes this API directly, without adding additional business rules.

There are, however, some specific Web API methods whose business logic is mirrored in the Web API Controller. For example, the CreateSalesDocument method of the sales controller.

3. How does the Web API authentication process work?

Authentication in the Web API uses the OAuth 2.0 standard. Requests must be preceded by a call to the endpoint/token, providing credentials such as username, password, company code, ERP instance, product line and a sessionkey. The response includes an access_token which must be used in the headers of subsequent requests.

4. What is the sessionkey and what is its importance in the Web API?

The sessionkey is a required identifier used to authenticate the ERP Web API.

When no sessionKey is provided in the token request, the Web API generates an implicit sessionKey that is associated with the token.

This identifier represents the integration context of the client application with the ERP and allows the system to associate requests to a specific session, without the need to maintain user sessions on the server layer (IIS).

This sessionKey is the key to being able to make several requests simultaneously, even with different tokens, without the risk of different threads accessing information that concerns another integration context.

Main features

• Required when calling the endpoint/token to get the access_token;
• It can be any value defined by the client application (e.g. app name, GUID, etc.);
• It must be unique per instance of the client application. It must not be shared between different users or concurrent processes;
• It serves to identify and isolate the execution context in the ERP (company, instance, product line, etc.).

Best practices

• Define the sessionkey consistently by application or integration;
• In multi-user environments, use dynamic values (e.g. userApp_name or GUIDs).

5. What is the structure of the Web API endpoints?

The endpoints follow this structure: http://localhost:2018/WebApi/{modulo}/{entidade}/{servico}/ 

In version 2 of the Web API, endpoints include the v2 prefix, i.e: http://localhost:2018/WebApi/v2/{modulo}/{entidade}/{servico}/ 

Caption:

• Module: identifies the ERP module;
• Entity: specifies the business entity;
• Service: determines the operation to be performed. 

6. What is Swagger and how is it used in the Web API?

Swagger is a tool for documenting and invoking Web API methods.

As of version 2 of Web API v10, Swagger becomes the presentation page for the Web API, allowing users to explore the available modules, view method details and test calls directly through the interface.

7. What are the main news in version 2 of the Web API?

Version 2 of the Web API introduces the following improvements over the previous version:

• Answers with a uniform structure for all methods;
• Use of the HTTP GET, POST, PUT and DELETE methods;
• Blocking simultaneous requests for the same integration context, configurable through the BlockMultipleRequestsPerContext option in the web.config file;
• Integration of Swagger as the main documentation and invoking tool.

8. How is the response to requests structured in version 2?

In version 2, all the answers follow the structure:

{ 

  "Version": "string", 

  "StatusCode": 0, 

  "ErrorMessage": "string", 

  "Results": {} 

} 

This standardization makes it easier for customers to process responses, regardless of the method used.

9. How to proceed when the authentication token expires?

When the token expires, the Web API returns error 401 - Unauthorized. In this case, a new request must be made to the endpoint/token, using the same method as the initial request.

To reuse the same integration context, it is recommended to include the expired token in the Authorization header of the new request.

10. Is there a method to log out and free up resources?

Yes, there is. The Web API provides a logout endpoint that allows resources associated with a given context of use to be released. This method is invoked without parameters, but requires the token to be identified in the Authorization header of the request.

Using this endpoint helps free up memory in the IIS process and remove inactive sessions in the database.

11. Is it possible to make simultaneous calls to the Web API?

Yes. It is possible to make simultaneous calls to the Web API, but with some restrictions that depend on the server configuration and the way the sessionkey is used.

By default:

• the Web API allows multiple requests simultaneously;
• all requests made simultaneously must ensure that they are made with different tokens, which in turn have been requested with different sessionkeys;;
• the Web API can block concurrent requests made with the same token (and having the same sessionkey) to protect data consistency and avoid conflicts.

Behavior is controlled by option < add key="BlockMultipleRequestsPerContext" value="true" / > , where:

• true (default): blocks simultaneous calls using the same token and sessionkey;
• false: allows multiple simultaneous calls even if they share the same context. This is not recommended as it can cause inconsistencies.

The application of this definition to false should only be used if it is guaranteed that calls to the Web API will not use the BSO (ERP engine) or PSO (Platform). For example: invoking extensibility endpoints that have their own data access layer.

Best practices

• In applications with concurrent calls (e.g. asynchronous integrations, background workers), use different sessionkeys per instance/process;
• If it is necessary to share the same sessionkey, organize calls sequentially or activate concurrency management on the client side.

12. What happens to the integration context when the token expires?

When the access_token expires, the associated integration context is not automatically freed.

This behavior allows that, even when a token expires, a new token request can be made (identifying in the header the token that has since expired) and, therefore, the integration context reused.

By default, the integration context (defined by sessionkey, company, instance and product line) remains active even after the token expires. This means that resources remain allocated in the application (memory, user sessions and connection to the ERP, including connections to the database) and can affect the server's performance if they are not manually freed.

To free up resources properly, it is necessary to:

• explicitly call the logout endpoint, which terminates the integration context and frees the resources;
• include the token (even if expired) in the Authorization header when logging out, so that the Web API knows which context to delete.

POST /WebApi/Base/Logout 

Authorization: Bearer {access_token} 

Note: failure to free the context can leave sessions stuck in the ERP database and keep objects in memory in IIS. This is especially relevant in systems with high loads or multiple integrations.

Best practices

• Whenever possible, implement an explicit logout after the end of an operation or session;
• In critical systems, consider automatic mechanisms on the client to terminate the context or request a new token when the token is about to expire.

The access_token obtained through OAuth 2.0 authentication in the Web API v10 has an expiration time of 20 minutes by default.

This time can be set in the Web.config file in AppSetting TokenExpirationMinutes.

13. What happens if you disable the BlockMultipleRequestsPerContext option and make simultaneous requests with the same token and sessionkey?

If you disable the BlockMultipleRequestsPerContext option in the web.config file, the Web API no longer prevents simultaneous calls with the same token and sessionkey.

Disabling this option poses a number of risks:

• The integration context (memory, objects, ongoing transactions) is shared between the concurrent requests;
• Since the Web API does not implement internal isolation between calls with the same sessionkey, data conflicts, state corruption or unpredictable behavior can occur;
  1. Example 1: when saving two sales documents, the same document number can be returned for both requests; 
  2. Example 2: it can generate errors of various kinds - object reference not set to an instance of an object, parameter count mismatch, etc.;
• This is especially dangerous in operations that change data or involve multiple steps (e.g. inserts, updates, complex business processes).

It is recommended to:

• Keep BlockMultipleRequestsPerContext = true;
• If parallel calls are necessary, use different sessionkeys per request or process to ensure context isolation;
• Monitor the impact and behavior of the API if you decide to change this configuration.

14. Is it possible to have more than one Web API v10 instance on IIS? And on multiple IIS servers?

Yes. It is entirely possible to have more than one Web API v10 instance, both on the same IIS server and on several different servers. 

On the same IIS:

• You can create several separate Web applications on IIS, each with its own virtual directory and Web API configuration;
• Assuming that the different applications point to the same AplWebAPI physical directory, there is no need to make any changes to the configuration files;
• Each web application can have a different application pool and thus ensure separate resource management;
• You must ensure that the ports and HTTP bindings used are different to avoid conflicts.

On multiple IIS servers:

• You can install the Web API v10 on the servers you want. This is especially useful in high availability scenarios, load balancing or separation by client;
• Access to the ERP is via the product API, so the main requirement is that the Web API server has access to the ERP;
• Currently, this installation is not done via the Deployment Center, but can be done by the client. The Web API binaries are in the Apl/WebAPI folder.

Best practices

• Use different names for the directories/app pools of the Web APIs on IIS;
• In environments with multiple instances, document the endpoints and configurations to avoid confusion;
• Monitor resource consumption (RAM, CPU, DB connections) per instance.

15. Does Web API v10 generate logs? Where can I consult and configure them?

Yes. Web API v10 uses NLog as a logging mechanism to record activities, errors and internal events. These logs are essential for diagnosing problems and analyzing API behavior.

By default, the logs are saved in the AplWebAPI folder.

In the logs, the following are recorded:

• internal Web API errors (exceptions, authentication failures, ERP access problems);
• details of requests received (endpoints, response time, status codes)
• critical events such as login failures, unauthorized calls, or communication problems with the database.

The verbosity level of the logs and the targets can be adjusted in the web.config file, in the logging section. You can set levels such as:

• Error 
• Warning 
• Info 
• Debug (more detailed, useful for development) 

  Best practices

• In production, use more restrictive log levels (Error or Warning) to avoid files that are too large;
• In development or in the event of an error, activate the Debug level temporarily for more details;
• Monitor the disk space of the logs folder, especially in environments with a high request load.