Lag integrasjon

API documentation

Swagger

The API is documented using Swagger, you can find the full Swagger documentation here. Swagger is an industry standard for creating user-friendly documentation of APIs. Swagger also provides a web based runtime that allows you to test, explore and use the different functionality of the API directly in your web browser.

 

Webhooks

The Visma.net API also supports WebHooks. Webhooks is a concept that enables the API to make outgoing calls to your application in addition to the traditional API usage where your application makes all the calls. 

An example of usage where this will be a great benefit is if you in your application want to handle changes that’s made to a customer in Visma.net. With traditional APIs your application would then have to make calls to the Visma.net API regularly (every minute/hour/day/etc.) to check if the customer has changed, most of these calls will discover that nothing has changed so it would be a waste of both time and resources to make the call. 

With webhooks your API can subscribe to certain events in Visma.net, for example customer changed, and instruct the Visma.net API to make a call to your service. So in this case, your service will be notified each time a relevant change is made and you can create your logic around that.

Webhooks can also be utilized in combination with custom actions inside the Visma.net user interface. This gives you the opportunity to create a custom button within the user-interface which when pressed will make a call to your service and you can then build your own logic for what will happen.

Batch operations

Sometimes you need to make multiple calls to API to perform your desired task. This could be for example if you want to import a number of customers into Visma.net or more complex tasks where you first create a customer, then a new invoice for this customer, then finally release the invoice.

To help with this Visma.net Integrations support batch-operations which means that you could combine multiple calls to the API together and send them as a single request to the API which will then make the calls sequentially.

Paging

Paging is a concept that allows you to control the number of results you get from a call to the API by dividing the results into pages. If you for example want to use the customer-endpoint to get a list of the customers in Visma.net you can utilize the parameters pageSize and pageNumber to control what part of the result you would like to receive.

If you would like the first 10 customers in the result, you can set pageSize=10 and pageNumber=1. To get the next 10 customers (result 11-20) you change the parameter to pageNumber=2

Paging is implemented in all list-functions in Visma.net Integrations.

 

Security 

The API is only accessible via the HTTPS-protocol so that all traffic between Visma .net and your application is encrypted.

To access the API you need to obtain a clientid and a client secret from Visma, this process is described in more detail under the Become an ISV-partner section. Once you are registered and have your clientid and secret you will be able to authenticate with the API and start using it.

OAUTH2

Visma.net Integrations uses OAUTH2-standard for authorization. OAUTH2 is a commonly used standard that allows you securely be granted access to different resources, for example the Visma.net API. To learn more about OAUTH2, see this.

The authentication-process consists of two steps:

  1. First you will use your clientid to create a url for the authorize-service in Visma.net Integrations.
    This URL must also include a parameter called redirect_uri, this is a uri to an endpoint in your application that is able to receive a call from Visma.net Integrations once the authorization is completed. The redirect_uri has to be a known uri to Visma.net Integrations, so this means that the redirect_uri has to be defined and given to Visma before you can get your clientid and secret.

The redirect_uri can be changed at any time so for development-usage you can use a localhost-address, i.e http://localhost:5000/AuthRedirect.
You can also register multiple redirect_uri's for your application.
In the url, you must also provide the different scopes you require access to. A scope is a given set of rights to access specific data or functionalities.

Once the url is created your solution can redirect to the url and the user will be presented with the Log in to Visma.net screen and can provide the credentials. 

  1. When the user has successfully logged in via the Visma.net login screen, and approved access to the selected scopes, a call will be made to the redirect_uri defined. This call will include a unique code as an request argument. This code will be used to obtain a token, the token will be your “key” to able to make further calls to the Visma.net API.
    To get the token your application will make a call to the token-endpoint. This call must use the HTTP-verb POST and include the code received in addition to your clientid and secret. The response of this call will contain the token which can then be used for further communication with the API.

  2. Once you have the token you will have access to call any endpoint in the API as long as you include this token in the HTTP-headers.
    Note that the token you receive does not expire, so for all further calls you can utilize the same token without generating a new token. The token will also be valid across sessions, so once you have a token you can reuse this for all future sessions for the user.

This figure below illustrates the flow of the authentication-process, you can also download example-code for this process here. 

Become an ISV-partner

Before you can use the Visma.net API you must become an ISV Partner. As an ISV partner you can utilize the API to build your custom applications, you will get access to our developer-forum and support from our support-team. When your app is ready you can also upload it to our online integrations markedplace so all Visma.net users can easily find it.

To become an ISV partner you must complete the following process:

  1. Fill out the registration-form to apply for ISV partnership.

  2. Once the application is approved we will send you the ISV Partner-agreement.

  3. Read through the agreement and sign digitally.

  4. When the signature is received you will receive a welcome-mail with information about how you can log in to our online certification-portal.

  5. In the certification-portal go through the ISV Certification program. Here you will have to complete a few courses about Visma.net Financials to get to know the system, in addition you will need to complete a few courses that goes more in depth of the technical usage of the API. The courses are completed by passing an online multiple-choice exam. 

  6. When the exam is passed you will be a certified Visma.net Integrations developer. When Visma receives confirmation that the exam is passed you will get your login credentials and can start developing your application.