Hopp til hovedinnhold
The API is documented using Swagger, you can find the full Swagger documentation here. Swagger is an industry standard for creating userfriendly documentation of APls. 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.
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 APls 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.
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 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=1 O and pageNumber=1. To get the next 1 O customers (result 11-20) you change the parameter to pageNumber=2
Paging is implemented in all list-functions in Visma.net Integrations.
Read more about Paging here.
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.
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 httQ:lllocalhost: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.
2. 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 tokenendpoint. 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 APL
3. 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.
