Overview
In modern web applications, ensuring data consistency and preventing conflicts is essential, especially when multiple clients attempt to update the same resource concurrently. The ETag and If-Match HTTP headers offer a solution for these challenges. Here's how they work together to maintain data integrity.
ETag Response Header
An ETag (Entity Tag) is a unique identifier that the server assigns to a specific version of a resource. It is included in the response header when a client requests the resource. This identifier helps clients in managing cache and detecting resource changes.
Usage in API: When a client requests a resource, the server responds with the ETag value in the response header and as part of the response DTO (with the field name: "Timestamp").
Pagination Note: During paginated responses, the ETag value isn't included in the response header but is available within the response DTO (Field name: "Timestamp").
If-Match Request Header (Optional)
The If-Match HTTP header is used by clients to signal that they wish to update a resource only if its current version matches a specific ETag. This mechanism prevents resource conflicts when multiple clients try to update the same resource simultaneously. See also, lost update problem, If-Match, HTTP conditional requests
Conflict Prevention: If the ETag stored on the server doesn't match the client's If-Match header, the server responds with a 412 Precondition Failed status code
Usage in API: Currently "If-Match" header is optional and can only be used with certain PUT & POST Action endpoints shared in detail in the following section below.
Example:
1) GET : .../api/v1/supplier/xxxxx Response headers : ETag
Response body : timeStamp
2) PUT: .../api/v1/supplier/xxxxx Request headers : If-Match
This request will succeed in updating the resource only if the resource's current "ETag" is "AAAAAE0YIiI=". A) In case of success, the server returns "204 - No content" together with the new ETag value in the response headers.
B) In case of failure, the server returns "412 - Precondition Failed".
Advantages of using ETag and If-Match
Optimistic concurrency control: By using If-Match headers, clients can ensure that updates to resources are made safely without unwanted overwrites.
Data Integrity: Helps maintain data consistency by validating that resource updates are based on the most current data.
API Endpoints with ETag and If-Match Header Support
A) Endpoints & Operations Supporting "ETag" Response Header
ℹ️ PUT: The ETag of the recently updated entity is included in the response header.
ℹ️ POST: The ETag of the recently created entity is included in the response header.
GET Supplier
PUT Supplier
POST Supplier
GET SupplierInvoice
PUT SupplierInvoice
POST SupplierInvoice
GET SupplierLocation
PUT SupplierLocation
POST SupplierLocation
GET SupplierPayment
PUT SupplierPayment
POST SupplierPayment
GET Shipment
PUT Shipment
POST Shipment
GET PurchaseOrder
PUT PurchaseOrder
POST PurchaseOrder
GET PurchaseOrderBasic
PUT PurchaseOrderBasic
POST PurchaseOrderBasic
GET PurchaseReceipt
PUT PurchaseReceipt
POST PurchaseReceipt
GET PurchaseReceiptBasic
PUT PurchaseReceiptBasic
POST PurchaseReceiptBasic
Note: : "TimeStamp" field can also be checked via the DTOs where it's exposed.
B) Endpoints & Operations Supporting "If-Match" Request Header
PUT Supplier
PUT SupplierInvoice
PUT SupplierLocation
PUT SupplierPayment
PUT Shipment
PUT PurchaseOrder
PUT PurchaseOrderBasic
PUT PurchaseReceipt
PurchaseReceiptBasic
If the endpoint is asynchronous, meaning that if it is immediately returning a “202-Accepted” HTTP response and starts the actual job in the background, such as “Action” based operations. (Endpoint URL: …/action/…) If-Match is supported in the following actions only with “erp-api-background usage,
POST SupplierPayment action/Release
POST SupplierInvoice action/Release
POST SupplierInvoice action/Prebook
POST SupplierInvoice action/voidinvoice
POST SupplierInvoice action/sendtoapproval
POST SupplierInvoice action/reverse
POST SupplierInvoice action/correctInvoice
POST SupplierInvoice action/Attachment
POST SupplierInvoice action/AttachmentLine
---------------------------------------------------------------------------------------------------------------------------------------- This knowledge article serves as a guide for developers to incorporate ETag and If-Match functionality into their applications, ensuring smooth updates and mitigating conflicts in a multi-client environment.
Introduction
In SalesOrder v1 and v2, when you set the {"markForPO": "true"}, the Purchase order source is by default set to Purchase to order.
In SalesOrder v3, only the field purchaseOrderSource is included. If you set purchaseOrderSource in v3, markForPO will automatically be true in the database.
ScreenId=SO30100S
This change simplifies the process compared to v1 and v2, where you needed to include both markForPO and poSource if you wanted to set the Purchase order source to Drop-Ship. The change in v3 allows you to set Purchase order source with just one field.
Available Options for v3
There are two main methods to set the purchase order source in v3.
Option 1: Default Replenishment Setting in UI
If an item has a default replenishment source, such as Drop Shipment or Purchase to Order, set in Item warehouse details screen (IN204500, Replenishment Info-tab), the system will automatically mark the line for PO when you add the item to an order line. The Purchase order source will be set according to the item's default setting.
ScreenId=IN204500
Option 2. Manual Setting
If an item does not have a default replenishment source, set the Purchase order source manually for the line when needed. In v3, use {“purchaseOrderSource”: “purchaseToOrder” } instead of setting {markForPO: true} as in v1 and v2. See the documentation for more information.
POST /api/v3/SalesOrders
With these changes in v3, managing purchase order source in sales orders becomes more straightforward and efficient.
Request Limitation(throttling) is applied based on per client, As of today, there is 500 transactions/calls allowed per company, per hour during the development phase(Test Client)
Have you ever wanted to add a button in one of the Visma.net ERP screens that allows the user to call custom functionality you have made? By combining the the feature Automation Actions and Webhooks you can. This article shows you how you can create a custom action that will be visible under the Actions toolbar item, and how you can connect this to your custom logic using webhooks.
Using webhooks can significantly improve the performance of your integration. With webhooks you can subscribe to changes and actions that happens in Visma.net and trigger functionality in your application. This article explains how webhooks works, and how you can implement this.
In this article, you can find guidelines on utilizing Visma.Net API Endpoints using DateTime parameters, as well as their associated condition and operators. For more information regarding the endpoints, query parameters and other endpoints for all areas, Please read the documentation found here: Swagger - Visma.Net Integrations Documentation
lastModifiedDateTimeCondition=Operator
Supported comparative operators for LastModifiedDateTime Conditions on filtering
> - Greater than
< - Less than
<= - Less than or equal to
>= - Greater than or equal to
Explanation:
?lastModifiedDateTime=2024-05-25
&lastModifiedDateTimeCondition=>-
Retrieve records after and on the given DateTime
?lastModifiedDateTime=2024-05-25
&lastModifiedDateTimeCondition=<-
Retrieve records before and on the given DateTime
?lastModifiedDateTime=2024-05-25
&lastModifiedDateTimeCondition=>=
Retrieve records after and on the given DateTime
?lastModifiedDateTime=2024-05-25
&lastModifiedDateTimeCondition=<=
Retrieve records before and on the given DateTime
Usage example:
This query will return customers updated on 2024-05-25 or later.
GET https://integration.visma.net/API/controller/api/v1/Customer
?lastModifiedDateTime=2024-05-25
&lastModifiedDateTimeCondition=>=
( Lines are separated for readability)
The operators are used the same for: createdDateTimeCondition=Operator
dunningLetterDateTimeCondition=Operator
In certain instances, users may encounter a specific error message when sending request via the API: {
"ExceptionType": "IPPException",
"ExceptionMessage": "No license for this company.",
"ExceptionFaultCode": "12027",
"ExceptionMessageID": "12027_6e2a06a8-76d8-4e9a-bce8-a5818d60a388",
"ExceptionDetails": ""
} Follow these steps to troubleshoot this error:
Using the Interactive authentication without the API user role Make sure that the user has the correct role assigned. [Needs to be checked by Customer in Admin]
Ensure to verify that the customer sends the TenantID to their company and not the customer The tenantID provided to the ISV/Application is the end customers “Customer TenantID” (The customer contract which holds the license for all companies) and not the specific companies tenantID. [Needs to be checked by Customer(with “integration administrator” role) in Visma App Store] TenantID for Company in Visma App Store.
For further information regarding Tenant ID provisioning and integration processes, please read the documentation available on the Visma Developer Portal and the start-up guide: Developer Portal Startup-Guide
3. The license for Visma.Net Financials has expired [Needs to be checked by Visma]
Webhook notification system is available at https://status.visma.com With this feature, Visma Cloud Services Status page can send notifications via webhooks when there are incidents & scheduled maintenance or status update on a component status. Webhooks contain information about the Product / Component / Status these changed. We would highly appreciate your feedback about this feature, so please feel free to inform us after implementing this. How to enable webhook notifications ? After navigating to the https://status.visma.com, please follow the steps shown below respectively.
Immediately afterwards, you'll receive an email from "noreply@statuspage.visma.com" that is informing you about Webhook subscription confirmation.
If Status.Visma is unable to communicate with your Http listener domain, it will be sending you another email as a warning.
For further information please see the following articles.
What is a component?
Enable webhook notifications (JSON Schema)
The Visma.net ERP API documentation is created using Swagger, which presents a graphical user interface for documenting the endpoints. The documentation can be found here: https://integration.visma.net/API-index/.
An added benefit of using Swagger to present the documentation is that you can test the API by making API-calls directly from the documentation. This guide describes how to do that.
Authentication-methods
Visma.net ERP API supports two different authentication-flows targeted against different types of applications. The functionality of the API is identical for the two flows. Visma net ERP Interactive API
This flows is designed for applications/integrations that should run in the context of a specific user and requires the users to sign in using their Visma.net ERP credentials. All API calls will impersonate this user.
Visma net ERP Service API
This flow is designed for applications that should not run in the context of a user, but in the context of the application/integration itself. The authentication does not require a user to sign in. The flow is especially targeted against service-applications running in the background without user interaction.
You can switch between the to flow in the Select an API: - drop-down on top of the documentation page.
Once you have selected the desired flow, you can authenticate to the API by pressing the Authorize button. The flow will be different for the two methods so the rest of this article will be divided into to parts.
Visma net ERP Interactive API
When pressing the Authorize-button you will be presented with a Visma.net sign-in screen i a new window or tab. Any Visma.net user can be used to sign in here, but the user must have the role API User on one or more Visma.net Financials companies. This role can be set from Visma.net Admin:
After you have logged in with you username and password you will be presented with the context-selector screen if you have the API User role on more than one Visma.net Financials company. Select the company you want to work with. If you only have access to one company the screen will be omitted and the company will be automatically selected.
When the company is selected you will be brought back to the Swagger UI and presented with a confirmation screen. You can now close this screen and start making your API-requests.
Visma net ERP Service API
As mentioned the service flow does not require a user to log in, but it needs to identify the application that are making the API requests. These types of applications needs to be created before the can be used in the Visma Developer Portal. A guide to how you can register this application can be found here.
Once you application has been registered and you have received your Client ID and Client Secret, a representative for the company you want to access needs to approve your applications access from Visma App Store. You also need a Tenant ID, which is the unique identifier for a Visma.net Financials company. This Tenant ID can be found in Developer Portal for all the companies that has approved your applications access.
When you press the Authorize-button you will be presented with a popup where you can supply your Tenant ID, Client ID and Client Secret and select the required scopes (access permissions).
Press the Authorize-button to get your access token.
Making API requests
To make an API-request choose the endpoint you want to use and press the Try it out button.
You now have the list of available parameters visible and you can type in a value to any of the parameters you need. After you have filled in your parameters press Execute to execute the request.
The API request will be executed and the result will be visible in the UI:
Question
We received a 400 Bad Request when using POST/api/v3/SalesOrders. How can I see what is the reason for this error?
Answer
When receiving a 400 Bad Request it include an error response body. This response body will indicate the reason for getting the error, looking like this:
Since the Visma.net ERP API was released authentication has been handled by an implementation of the OAuth 2.0 protocol called VNI. This has served us well, but it has some limitations that makes it somewhat cumbersome to work with both for you as developers and internally in Visma.
Since the release of the Visma.net ERP API, the importance of APIs and number of integrations has grown rapidly and the amount of traffic we have received on the API has doubled year over year. More importantly, the requirements to securing the APIs are constantly increasing, and protecting our customers' data is always a top priority for us.
In the last few years we have developed our Visma Connect product into a state of the art implementation of the OAuth 2.0 protocol, including surrounding tools like the Visma Developer Portal and Visma App Store.
Using Visma Connect as the authentication provider for the Visma.net ERP API is therefore an important step to keep your integrations and our customers' data secure.
Why should you switch?
There are multiple reasons why you should upgrade your applications to use the Visma Connect authentication provider.
Visma Connect is more secure than VNI.
Visma Connect supports the Client Credentials-flow, this makes it possible to create machine-to-machine integrations.
Handling of your application is done self-service in the Visma Developer Portal, this includes creating new applications, managing credentials (ClientId and Secret), managing token lifetimes, scopes and much more.
The new next generation APIs for Visma.net ERP, like the Sales Order Service uses Visma Connect, therefore when you switch to Visma Connect for your application you can reuse the same authentication.
All new integrations should use the Visma Connect authentication mechanism. The existing VNI authentication-mechanism will be deprecated during 2023, so please consider changing your integrations already. The attached PDF is a detailed guide on how you could migrate your existing integrations to use Visma Connect.
If you are an organization working with developing integrations towards Visma APIs you might have the need to have multiple people in your organization accessing the Visma Developer Portal to perform different tasks.
Visma Developer Portal accommodates this by allowing you to set up and organize teams that can access Visma Developer Portal for your company.
Most users of Visma’s cloud solutions have Visma Home as their startpage to access all applications they use in their daily work. So if you have an application that is relevant as part of the users daily work it could be useful to have your application visible on Visma Home as well. This guide describes the steps you need to take to expose your application on Visma Home.
As a Visma ISV you have the opportunity to showcase your Visma-integrated applications on our Visma App Store (https://apps.visma.com). The Visma App Store is the end customers portal, where all customers of Visma products can find, activate and administer the applications and add-ons to their products. This article describes how you can use Visma Developer Portal to create and manage apps for display on Visma App Store
We’ve implemented a new feature that API Endpoints available at Visma.net ERP API Documentation, can be invoked in an asynchronous mode by using the new “Background API” functionality. (Version: 8.88.0) This can be achieved by adding an extra request header “erp-api-background: “WebhookURL” to your request.
If this additional “request header” is provided in your request, our servers will "intercept" the API request before it reaches the Endpoint.
The request will be persisted in our backend. All our application web servers will regularly pull queued requests and process them in the background.
This processing is not taking place in a web context, and therefore it is not prone to web exceptions like timeouts etc.
In this way, with this new feature, potentially long-running operations can be performed more effectively.
Once the request has been processed, the API Client will be notified with the webhook notification if “erp-api-background” request header had been provided with “webhookURL” value in your request.
This webhook notification will contain information about,
“stateLocation” of the operation(status of the background operation) and
“ContentLocation” that where the response can be picked up, in other word, where the API Client can GET the result of the request that has recently been made.(if it has any content aka ResponseBody)
If the “erp-api-background” request header value set as “none”
Webhook notification will not be invoked.
In any case, every queued API request will be assigned an ID that will be present in the immediate “202-Accepted” response to the client.
This response also contains a "stateLocation" address that the client can call at any time to check what is the status of the background operation.
"contentLocation" address that points to the readily formatted and stored response body of the operation if it has any content to be returned.
If the endpoint today is asynchronous, meaning that if it is immediately returning a “202-Accepted” HTTP response and starts the actual job in the background, such as “Action” based operations. (Endpoint URL: …/action/…),
Currently, the new "Background API" system is also unable to receive the state of the document when the action based request invoked.
Therefore, we’re unable to determine whether the “action” based process succeeded or the state of the document changed without making an additional GET request to see the actual status of the document.
However, this topic is already in our development plan. (Endpoint logic should be "synchronous" so that, waiting for the actual job to be done, to inform the client accordingly.)
Example request:
"Request Headers erp-api-background : yourWebhookURL"
Key
Value
ipp-application-type
Visma.net Financials
ipp-company-id
"ERP CompanyID"
Content-Type
application/json
Authorization
"yourToken"
erp-api-background
"yourWebhookURL"
GET: "Customer Invoice" Request URL: /api/v1/customerinvoice?pageNumber=1&pageSize=100 HTTP Response: “202-Accepted” Response Body:
Received Webhook Notification:
GET: "stateLocation"
Request URL: /api/v1/background/{id}
HTTP Response: ”200-OK”
Response Body:
GET: "contentLocation" Request URL: api/v1/background/{id}/content HTTP Response: ” 200-OK” Response Body: Contains the “GET - CustomerInvoice” data.
---------------------------------------------------------------------------------------------------------------------------------------
POST: “Customer Invoice” Request URL: “/api/v2/customerinvoice” HTTP Response: “202-Accepted” Response Body: Contains request “ID” and “stateLocation”
Received Webhook Notification:
GET: "stateLocation" Request URL: /api/v1/background/{id} HTTP Response: ”200-OK” Response Body:
---------------------------------------------------------------------------------------------------------------------------------------
PUT: "Customer Invoice" Request URL: /api/v1/customerinvoice/{invoiceNumber} HTTP Response: “202-Accepted” Response Body: Contains request “ID” and “stateLocation”
Received Webhook Notification:
GET: “stateLocation” Request URL: /api/v1/background/{id} HTTP Response: ”200-OK” Response Body:
---------------------------------------------------------------------------------------------------------------------------------------
"Request Headers erp-api-background : None"
Key
Value
ipp-application-type
Visma.net Financials
ipp-company-id
"ERP CompanyID"
Content-Type
application/json
Authorization
"yourToken"
erp-api-background
"None"
ℹ️ Webhook notification will not be invoked, State & Content Location logic will be the same as request examples shared above.
---------------------------------------------------------------------------------------------------------------------------------------
Please feel free to contact us (Financials ERP API Support) if you need any further information.
Did you know that Visma.net ERP API supports different compression algorithm? We support brotli, gzip and deflate. They can be used by adding Accept-Encoding: <compression type> in your request header. More info and sample code can be found at:
Response compression in ASP.NET Core
Setup up your user rights
To be able to use Visma.Net API you need to make sure your visma user have the correct roles on the Financials company you want to use it for. Login with your Visma.Net Account : https://signin.visma.net and go to Admin Panel.
1- Visma.Net Admin
1.A- To be able to edit the access rights you need to be logged in with a user with “Customer administrator” role.
1.B- To set your rights, click on Visma.Net Financials in the top left corner and choose Admin.
2-User and roles
2.A- When you have accessed Visma.net Admin click on “User and roles”. 2.B- Head to the “User” tab.
2.C- Search for your username and click your name.
3-Company access and rights
3.A- If the company you want to edit roles for does not exist in the list under your username, click the “Add access to” menu and look for the company you wish to add.
3.B- Find the company you want to edit roles for.
3.C- On the line for the desired company, press the field for “Financials” and add the roles “Financial Administrator” & “Financials User”.
Swagger
Our Swagger is a good point for you to start using the API.
Connect to your Visma.Net account
Authorize and get a VNF token to use in Swagger.
Click “Authorize” on the right side of the interface.
Tick the box for “financialstasks” and press “Authorize”
You will be directed to a Visma.net login, enter your credentials and sign in.(If you are not asked to enter your credentials but get directed to the next step straight away, please clear your cookies in your browser and retry)
Allow Visma.net Integrations to connect to your account.
When you have allowed the connection you see that you are now authorized in Swagger. Close the window and proceed to use Swagger.
Start using Swagger
The first thing you need to do is check what companies your visma.net financials user have access to. You can find the names and Ids via the “Context” endpoint.
Scroll down to the “Context” endpoint and expand it.
Expand the first GET method - Get the companies available for this token, and press “Try it out”.
You will now see a button, “Execute”, press it and you’ll notice the result below will have updated to show your available companies. You’ll also see the request URL.
In the list, decide which company you want to use and copy the “id:”, this is the Id you will add to your “ipp-company-id” header when you are making requests. For now scroll back up to the top and paste the ID in the field “ipp-company-id”. When you have filled this field, the requests you execute via Swagger will target that company.
We also recommend taking a look at : OAuth 2.0 Authorization Flow
Visma.Net Integrations - API Client Configuration
In this document we will go through what needs to be done after you completed your Visma.Net Integration certification.
Redirect_URI
The first thing you need to do to configure your API client is to set up a redirect_URI.
Redirect URIs are a critical part of the OAuth flow. After a user successfully authorizes an application, the authorization server will redirect the user back to the application with an authorization code in the URL. Because the URL will contain sensitive information, it is critical that the service doesn’t redirect the user to arbitrary locations.
Due to this, it is required to specify one or more redirect URIs when you register your integration with Visma.Net. For production, it is required that the provided URI is set up with HTTPS.
When you have a redirect URI, this should be sent to your partner service in order to be able to get your Client_ID and Client_Secret. When this has been processed, you will receive an Activation email for your registration, the link to activate your Client_Id will be active for 5 days, so make sure to do this when the email is received:
API client types
For Visma.Net there are two client types available, API “test client” and “production client” (also known as live)
Test Clients
All new API clients are generated as the type “Test”.
In the test client there is a limit to the allowed calls per hour, which is set 500 calls/hour/per company.
ℹ️ When you are ready to go live with your integration you need to contact your partner service to obtain the "production" type API Client.
Production Clients
In the Production Client, the limit for calls is 15,000 calls / per hour & per company
(since version: 8.25)
Please also see,
Why am I receiving "HTTP 429 - Too many request / throttling" response from API ?
Visma.Net Integrations Startup Guide
Visma.Net API International Support Policy
Contacting the Visma.Net ERP Support / Partner Service
API incidents - Troubleshooting and reporting
TaxID '01' cannot be found in the system
To diagnose why you get this error message, you must check a couple of things.
The process flow of applying VAT in Visma.Net Financials follows this flow:
First, the VAT Zone ID is collected from the Supplier or Customer, check the following:
Supplier(ScreenId=AP303000) Purchase settings tab:
Customer(ScreenId=AR303000) Delivery settings tab:
For this article, we’ll have a look at the Customer.
VAT Zone ID
To check the VAT Zones, go to ScreenId=TX2060PL and click on the Zone ID of your customer(Here it is Zone 01).
Clicking on the Zone will show the different VAT ID’s available for this zone.
VAT Category
Next, you need to check the VAT category of the Item you are going to use, this is found under the “General Information” tab of the item (Non-Stock: ScreenId=IN202000, Stock Item: ScreenId=IN202500).
Clicking on the pencil next to the category will open the window for that category(ScreenId=TX2055PL).
Here you need to make sure that the category has the correct VAT type for the document you are creating.
You will also see a list of available VAT Ids for this category.
Visma.Net Financials will select the VAT ID based on the the ID where Category and Zone match.
Opening VAT Id 3 will show you that both Zone 01 and Category 03 will be present here, and will therefore be valid on the line when you are creating your invoice.
Posting the invoice without specifying the VAT id:
Generates invoice in VNF:
Specifying the VAT ID based on this will create the invoice, however posting a VAT ID that does not comply with the points in this article(eg. A VAT ID that has a category that is not does not match the type of document you want to create, a VAT Category / Zone combination that does not exist) will give you an error message.
ℹ️For further information regarding how to set up VAT zones/ids and categories, contact your partner service / ERP Support.
Override Visma.net Financials ERP number-series via API function has been implemented in Visma.net Financials ERP API version 8.25 (September 2020) With this function, we can set different asset number / ID via API than the Number-series that have been configured in the Visma.net Financials ERP UI without breaking the auto-numbering sequence.
Currently, available in the following endpoints
POST Customer
POST CustomerDebitNote V2
POST SalesOrder
POST Supplier
POST Journal Transaction V2
POST PurchaseOrder
POST Supplier Invoice
POST CustomerCreditNote V2
POST CustomerInvoice V2
How to set it up? 1) Set "Allow manual numbering on imports" true in the Visma.net Financials ERP UI. (Number Series - ScreenId=CS201010)
2) Include the following key-value pairs in the payload based on the aforementioned endpoint DTO syntax. ("ReferenceNumber" field may vary depending on the resource.) Visma.net ERP API - Endpoint Documentation
...
"overrideNumberSeries": {
"value": true
},
"referenceNumber": {
"value": "string"
}
...
After a successful POST request, the value specified in the "ReferenceNumber" field would be assigned to the resource as an identifier.
Afterward, the end-user or any integration can continue using Financial Company's automatic numbering setup in the transactions without any number skipped from the defined number series.