New API feature: "erp-api-background" operation

[#1]

We’ve implemented a new feature that API Endpoints available at Visma.net ERP API Documentation, can be invoked in an asynchronous mode by using the new “Background API” functionality. (Version: 8.88.0) 



This can be achieved by adding an extra request header
“erp-api-background: “WebhookURL”  to your request.

• If this additional “request header” is provided in your request, our servers  will "intercept" the API request before it reaches the Endpoint.
• The request will be persisted in our backend. All our application web servers will regularly pull queued requests and process them in the background.
• This processing is not taking place in a web context, and therefore it is not prone to web exceptions like timeouts etc. 

In this way, with this new feature, potentially long-running operations can be performed more effectively. 

Once the request has been processed, the API Client will be notified with the webhook notification if “erp-api-background” request header had been provided with “webhookURL” value in your request.

This webhook notification will contain information about,

• “stateLocation” of the operation(status of the background operation) and
• “ContentLocation”  that where the response can be picked up, in other word, where the API Client can GET the result of the request that has recently been made.(if it has any content aka ResponseBody)

If the “erp-api-background” request header value set as “none”

• Webhook notification will not be invoked. 
• In any case, every queued API request will be assigned an ID that will be present in the immediate “202-Accepted” response to the client. 
• This response also contains a "stateLocation" address that the client can call at any time to check what is the status of the background operation.
•  "contentLocation" address that points to the readily formatted and stored response body of the operation if it has any content to be returned.
  

If the endpoint today is asynchronous, 
meaning that if it is immediately returning a “202-Accepted” HTTP response and starts the actual job in the background, such as “Action” based operations. (Endpoint URL: …/action/…),  

• Currently,  the new "Background API" system is also unable to receive the state of the document when the action based request invoked.
• Therefore, we’re unable to determine whether the “action” based process succeeded or the state of the document changed without making an additional GET request to see the actual status of the document.

However, this topic is already in our development plan. (Endpoint logic should be "synchronous" so that, waiting for the actual job to be done, to inform the client accordingly.)

Example request:

"Request Headers erp-api-background : yourWebhookURL"

Key	Value
ipp-application-type	Visma.net Financials
ipp-company-id	"ERP CompanyID"
Content-Type	application/json
Authorization	"yourToken"
erp-api-background	"yourWebhookURL"

1. GET: "Customer  Invoice"
   Request URL: /api/v1/customerinvoice?pageNumber=1&pageSize=100
   HTTP Response: “202-Accepted”
   Response Body:
   
   
   
2. Received Webhook Notification:
   
   
   

3. GET: "stateLocation"

   Request URL: /api/v1/background/{id}

   HTTP Response: ”200-OK”

   Response Body:
   
   
   

4. GET: "contentLocation"
   Request URL: api/v1/background/{id}/content
   HTTP Response: ” 200-OK”
   Response Body: Contains the “GET - CustomerInvoice” data.

---------------------------------------------------------------------------------------------------------------------------------------

1. POST: “Customer Invoice”
   Request URL: “/api/v2/customerinvoice”
   HTTP Response: “202-Accepted”
   Response Body: Contains request “ID” and “stateLocation”
   
   
2. Received Webhook Notification:
   
   
   
3. GET: "stateLocation"
   Request URL: /api/v1/background/{id}
   HTTP Response: ”200-OK”
   Response Body:
   
   

 ---------------------------------------------------------------------------------------------------------------------------------------

1. PUT: "Customer Invoice"
   Request URL: /api/v1/customerinvoice/{invoiceNumber}
   HTTP Response: “202-Accepted”
   Response Body: Contains request “ID” and “stateLocation”
   
   
2. Received Webhook Notification:
   
   
   
3. GET: “stateLocation”
   Request URL: /api/v1/background/{id}
   HTTP Response: ”200-OK”
   Response Body:
   

---------------------------------------------------------------------------------------------------------------------------------------

"Request Headers erp-api-background : None"

Key	Value
ipp-application-type	Visma.net Financials
ipp-company-id	"ERP CompanyID"
Content-Type	application/json
Authorization	"yourToken"
erp-api-background	"None"

 
ℹ️ Webhook notification will not be invoked, State & Content Location logic will be the same as request examples shared above. 

---------------------------------------------------------------------------------------------------------------------------------------

Please feel free to contact us (Financials ERP API Support) if you need any further information.