My Products
Help

Important: End of VNI and transition to Azure API Management

by Oskar Jansson (Updated ‎18-02-2025 13:06 by Oskar Jansson VISMA )

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, effective April 30th, 2025. We would like all clients who are 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.

 

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 to

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

  • Example: GET https://api.finance.visma.net/v1/account (Note the lack of “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. 

  • It is estimated that the new Base URL will be available by the end of February. Once it is released, a new date will be set 3 months after it becomes available. This means that the EOL date for the Base URL is currently set for 30.05.2025.

 

API requests to v1 and v2 that take more than 4 minutes

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 

  • 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.

  • To the 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//:

  • 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)

7 Comments
JohanFriedrichsen
CONTRIBUTOR **
by JohanFriedrichsen

When will it be possible to start using the new base-URL? Our developer tried it now and it doesn't seem active as it is now.

SierdW
PARTNER
by SierdW

As asked by JohanFriedrichsen, when will we be able to start using the new base-URL and will both base-URL's be supported during a specific period?

 

And regarding the webhooks:

 

  • It's very unfortunate that the endpoints are being removed. We had everything automated, and now it will require manual work again. Web/interactive integrations initiated by the user registered their own webhook subscriptions, this functionality is not available anymore?
  • I see that I can't add any webhooks at all for a web/interactive type application. The only webhook I can select is 'a background API operation has response ready.'
  • Will we receive duplicate events for a period if we don't do anything with the subscriptions endpoint and manage to add the webhooks in the developer portal?

 

product_scansys_nl
CONTRIBUTOR **
by product_scansys_nl

We have the same question: when can the new URL be used? We have three short months to implement this in our software and roll out to our customers.

by Trygve Storrønningen1

Will this URL replace both:

https://integration.visma.net/API/

and 

 

https://salesorder.visma.net/api/v3

by Suzdar Ibrahim

@Trygve Storrønningen1 Hi Trygve,

 

The base URL change will only apply to the ERP API (v1 & v2 salesOrder), not salesOrder V3.

by Suzdar Ibrahim

Hi, @product_scansys_nl @JohanFriedrichsen,

 

We estimate the new base URL to be active by end of February. When the new base URL is released you will have approx. 3 months to migrate. So this means the current EoL for the Base URL is 30.05.2025

 

I hope this answers your questions 🙂

 

BR

Suzdar

 

by Suzdar Ibrahim

Hi @SierdW,

 

Please check my replies regarding the new base URL. Regarding webhooks, we will make sure to create a small course which explains how to set them up and use them. Webhooks are usually meant for machine-to-machine integrations, but I totally understand your concerns and will report this back to the team. 

 

Thanks for the feedback!

 

BR,

Suzdar