Important: End of VNI and transition to Azure API Management

[#1]

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.

 

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)

[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]

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]

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.

[Trygve Storrønningen1]

Will this URL replace both:

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

and 

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

? 

[Suzdar Ibrahim]

@Trygve Storrønningen1 Hi Trygve,

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

[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

[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

[erik_anders]

Hi, the example in this article Example: GET https://api.finance.visma.net/v1/account does not take controller/api/v1/account into account. Can we assume that we don't need to have controller/api/ in the request url anymore?

[adrianm]

1. Doesn't the API already have a timeout? e.g. https://community.visma.com/t5/Forum-in-Developers-Visma-net/Searching-for-attribute-often-fails/td-...

2. What return code will we get on timeout?

3. If the timeout happens on PUT/POST, will the operation also be cancelled?
(i.e. if an order with many rows times out, will the order be created or not?)

[WimV]

Hello, I am using this site. Is it still valid?

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

[Suzdar Ibrahim]

@WimV Hi, 

It is still valid and will be for 3 months after the new URL has been released. 

BR,

Suzdar

[WimV]

A new URL for the new documentation? Can you tell more about the new documentation?

[Michel V]

Any news on the new base url and when it will be active. Earlier post said end of februari but it is not active yet.

[FenistraKristian]

I think the article should clearly state that the new base url does not work yet (and update it when it works).

[Rozhat]

The plan was to have this in place by the end of February, but due to an internal network issue, some resources were not available to us.

We appreciate your patience and will ensure this is available before the end of this week.

[jborg]

The old integration site https://integration.visma.net/API-index/ provides an API specification in Swagger/OpenAPI 2.0 format but it looks like the new site https://finance.visma.net/swaggerui/ provides the API specification in OpenAPI 3.0 format.

Does this mean that you will not provide any API specification in OpenAPI 2.0 format going forward? If so from what date?

This is a pretty big deal since most API code generators only support one version of Swagger/OpenAPI.  So by suddenly dropping support for a 2.0 specification will break a lot of integrations in ways that are pretty time consuming and expensive to fix.

[Oskar Jansson]

Hi @product_scansys_nl, @SierdW, @JohanFriedrichsen, @FenistraKristian, @Michel V, @WimV, the new base URL is now available, and this article has been updated with this information.

[Oskar Jansson]

Hi @erik_anders, you are correct. The article has been updated to Note the lack of “API/controller/api/”

[adrianm]

Does "available" mean it is ready for production use?

i.e. is it monitored and covered in the status page etc?

Also, how does versioning work with the new url. Swagger just says "v1"

[HansK2]

Hi.

In order to change the url (lack of API/controller/api/) I need a new swagger file since our code is auto generated. Is it this one that I should use? Is it this one? https://finance.visma.net/swaggerui/api/vismanet.erp.service.api%20stage-apim

It would be good to link it and the swaggerui page in the information above.

[adrianm]

>Does "available" mean it is ready for production use?

> i.e. is it monitored and covered in the status page etc?

Answering this myself and it is "No, not ready for production".

One of the first tests was to create a supplier invoice. The location returned was:

http://finance.visma.net/1038011008/api/v1/supplierInvoice/Invoice/200120

which doesn't work to fetch the invoice.

POST: https://api.finance.visma.net/v1/supplierInvoice
Headers: {
    Accept: application/json
    Authorization: <hidden>
    Transfer-Encoding: chunked
    Accept-Encoding: gzip    Accept-Encoding: deflate
    Content-Type: application/json; charset=utf-8
}
{"documentType":{"value":"Invoice"},"origInvoiceDate":{"value":"2025-03-11T00:00:00+01:00"},"supplierReference":{"value":"ABC123xxx"},"supplierNumber":{"value":"50013"},"currencyId":{"value":"SEK"},"dueDate":{"value":"2025-04-10T00:00:00+02:00"},"invoiceLines":[{"operation":"Insert","transactionDescription":{"value":"Kost"},"costInCurrency":{"value":9722.36},"accountNumber":{"value":"2446"}}]}
Response: 201 Created
Headers: {
    Cache-Control: no-cache
    Pragma: no-cache
    ETag: "AAAAAB1sBKE="
    Location: http://finance.visma.net/1038011008/api/v1/supplierInvoice/Invoice/200120
    X-Handled-By: Visma-PX.Export/AuthenticationManagerModule
    Set-Cookie: <crumbs>;  expires=Mon, 10-Mar-2025 11:33:11 GMT;  path=/;  HttpOnly    Set-Cookie: <crumbs>;  path=/;  HttpOnly    Set-Cookie: <crumbs>;  path=/;  HttpOnly    Set-Cookie: <crumbs>;  path=/;  HttpOnly
    VnfInstanceId: ERP_SE_DEMO_0005
    Request-Context: appId=cid-v1:898a32d3-12b9-4a24-865d-6ed5d67429a6
    Access-Control-Expose-Headers: Request-Context
    Referrer-Policy: origin-when-cross-origin
    Strict-Transport-Security: max-age=31536000; includeSubDomains
    X-Content-Type-Options: application/json
    X-XSS-Protection: 1;mode=block
    x-ms-request-id: 402cbb15-12ee-4171-b4d1-7ed83526a14b
    Date: Tue, 11 Mar 2025 11:33:14 GMT
    Content-Length: 0
    Expires: -1
}

[Oskar Jansson]

Hi @WimV & @HansK2, the new documentation can be found here: https://finance.visma.net/swaggerui 

[Oskar Jansson]

Hi @adrianm, thank you for reporting this. The developers are currently working on a fix.

[HansK2]

Hi!

The swagger has ben updated to openapi 3.0.X, in this version the default behaviour is that properties can not be null. The swagger is therefore incorrect now? All properties should have "nullable: true" in order to be the same as before? We are using NSwagstudio to generate c# clients and now all properties are not nullable.

https://swagger.io/docs/specification/v3_0/data-models/data-types/

[adrianm]

@HansK2, I think Visma.Net uses "JsonIgnoreCondition.WhenWritingNull" so properties are never null in responses, they are ignored. i.e. undefined in js-terminology.

In OpenApi, all properties are optional unless marked required.

(unfortunately Visma.Net often has the text "Mandatory" in the description instead of using required)

The new swagger is also correct.

[HansK2]

@adrianmn Since the properties are not allowed to be null in my generated types, I can't use "JsonIgnoreCondition.WhenWritingNull" in my code when I am sending data to Visma.net, since nothing is null. Furthermore when I receive data from Visma.net, all properties that are null in Visma.net and not sent, will get the default value for that type in my code, instead of null.

So for me it is a big change with openapi 3.0.X unless the swagger is changed to allow null values.

At least in NSwagstudio, it does not do any difference that all properties are optional, they do not become nullable.

[adrianm]

@HansK2, sorry, I just meant that the new swagger reflects how the API actually works.

I understand it is a change that can introduce breaking changes in auto-generated clients and it should probably have been mentioned by Visma.

Havn't used nswag to generate clients but isn't there a settings to make optional properties nullable? As you say, if it is not nullable there is no way to know if a property was included or not and that can't just be a problem with visma.net api?

[adrianm]

Can I get a response to this?

2. What return code will we get on timeout?

3. If the timeout happens on PUT/POST, will the operation also be cancelled?
(i.e. if an order with many rows times out, will the order be created or not?)

Also noted the url to the OpenAPI file has changed.

Can someone officially state something about the status of the new url?

When will it be ready for production use?

Does it have its own versioning (still says v1 in OpenApi specification)?