News in Developers Visma.net

Throughout the years, our Visma Net Integration (VNI as some say) has been used by you to solve many business problems customers have encountered. We are announcing the end of VNI, read more about the deadlines below. We want all clients still using our Visma NET API to follow the technical changes noted at the bottom of this article.

Why is this happening?

These changes are necessary to improve the overall experience by using our ecosystem. This change will naturally enhance the performance and increase the capabilities of our API. Migrating is an important step to keep your integrations and our customers' business cases a step ahead.

How will this affect you?

Once migrated, you should experience improved API performance, which will translate into faster operations, greater reliability, and the ability to implement more complex business solutions. By adopting the updated API base URL, customers ensure their integrations remain compatible with Visma's ecosystem and leverage ongoing enhancements. 

In most cases, this change should be relatively straightforward to implement. However, for more complex integrations, the process may require additional time and thorough testing to ensure everything functions as expected.

What should you do next?

Contact your vendor of the integration or Partner to clarify the necessary steps that need to be taken for your instance.

Still have questions?

Contact details for technical support: cloud.api.support@visma.com

We will also arrange a webinar if there is enough interest in this topic. Fill out this form to sign up for the webinar. Update: If you missed the webinar 13.03.2025, you can watch the recording here: https://vimeo.com/1065464044/f9523bb9b3 

Let´s take a look at the changes

There are breaking changes when moving to the new base URL. These changes require updates to your existing code and configuration.

Change base URL for all API requests (Deadline: 10.06.2025)

The new base URL is now available. 

• New URL: https://api.finance.visma.net

• Example: GET https://api.finance.visma.net/v1/account (Note the lack of “API/controller/api/”). Make sure code is not denying https://api.finance.visma.net as a base url, in case you have code that “follows” a location header on a response. When changing to API Management we will change the base URL. In the first period we will have support for the current URL. We want all integrations to start using the new base URL. 

• The new documentation can be found here: https://finance.visma.net/swaggerui 

API requests to v1 and v2 that take more than 4 minutes (Deadline: 30.04.2025)

The new API Management has a 4-minute timeout restriction. This means that API requests taking more than 4 minutes will respond with a web timeout error. To circumvent such situations, all API requests that spend more than 4 minutes can be refactored into being “background-api” calls. If you are not sure what “background-api” calls are please check out this link.

• Add a webhook subscription in Developer Portal for the event. With the value “none” in the header, there will be no notification when the call is done executing. With the value “subscription”, a webhook notification will be sent to the webhook subscriber that is set up in Developer Portal for the “Visma net” application event named “BACKGROUND_API_RESPONSE”. The <custom-headers> part is optional. It supports name/value pairs in the format <headername_1>=<value_1>,..,<headername_n>=<value_n>. When specified, the keys will end up as custom headers in the webhook notification with the corresponding values. Here you can typically specify your own reference ids to be able to recognize custom state for the operation in your webhook listener. One can at any time the next 24 hours GET /api/v1/background/{id} to poll the status of a background-api operation.

• BACKGROUND_API_RESPONSE from application Visma net (vismanetfinancials). The webhook listener is triggered when a response is ready from the background job and code here can check the result and fetch the actual response payload, if any, and process it as desired. The code logic regarding this response should normally be put in this webhook listener.

• Tothe request, add the header erp_api_background with the value “subscription” (without quotes and with any optional custom headers for the webhook request).

• Alternatively,  if you cannot change the architecture to add an http listener for webhook notifications, you may call the api with the erp-api-background header value “none” to still utilize an asynchronous api call to queue a task and get an immediate response, but not trigger a webhook when work is finalized. If your client needs the “real” result before moving on, you can request GET ..v1/background/{id} to poll if work is done or not, and if done, you may GET ..v1/background/{id}/content to get any response payload for the finished task.

Current Webhook subscriptions where the url is http//: (Deadline 30.04.2025)

• Change to https:// and make sure your listener supports that, or remove it. The new webhook dispatcher only supports https, all others will not be migrated automatically.

• All webhook events of type data-changed and action-triggered) will be automatically migrated to the new system in Developer Portal as they are currently handled in VNI. All future creation, updates and deletion of webhook subscriptions must happen in Developer Portal. 

• If you already have an application in Developer Portal, the subscriptions will appear there under the appropriate application (client). For integration clients that are not in Developer Portal, the webhook subscriptions will be placed under a common “VNI webhook migration” application. To maintain these later, contact with our support is necessary.

• After the migration of webhook subscriptions from VNI is done, its resources/event and resources/subscription api endpoints to list events and create or maintain webhook subscriptions, will not work anymore.

API endpoints that will be removed on 30.04.2025 and no longer supported - refactor clients

• GET /resources/v1/event
• GET/POST/PUT/DELETE /resources/v1/subscription/*
• Maintenance of Webhook subscriptions from this time can only be done in Developer Portal UI.

Background-API Webhooks where erp-api-background header contains a url

• Refactor the url value to “subscription” and set up a subscription in Developer Portal on the Webhook event BACKGROUND_API_RESPONSE from Visma NET (vismanetfinancials).

• If you today pass any values as part of the url path, like querystring arguments, these must be refactored into custom webhook headers using the following format for the erp-api-background header:
  subscription[:<headername_1>=<value_1>,..,<headername_n>=<value_n>]
  These name/value pairs will come as headers on the Webhook request and the webhook listener must be refactored to read the values from the headers instead of the URL.

Webhook listeners

Our (new) Visma Webhook Dispatcher service will after 30.04.2025 be the sender of webhook requests. If you have any white-listing configuration, this must be changed to allow this new sender’s IP addresses (18.202.121.26, 34.242.104.102, 54.220.26.45)