My Products
Help

Knowledge base in Developers Visma.net

Sort by:
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:      
View full article
17-02-2023 13:00 (Updated 17-02-2023)
  • 12 Replies
  • 1 kudos
  • 4967 Views
What is OAuth 2.0 Grant Type? In OAuth 2.0, the term “grant type” refers to the way an application gets an access token. OAuth 2.0 defines several grant types, in Visma.Net Integrations the grant type used as of today is “Authorization Code”. Each grant type is optimized for a particular use case, whether that’s a web app, a native app, a device without the ability to launch a web browser, or server-to-server applications.   The Authorization Code Flow The “Authorization Code” grant type is generally used by web and mobile apps. It’s different from other grant types in that it requires the application to open a browser to initiate the flow. Therefore the client application has to be able to interact with the users browser and receive incoming requests from the authorization server.  The flow is split up in two parts: The application starts an authorization code request. The application opens a browser to send the user to the OAuth server. The user sees the authorization prompt and approves the app’s request. The user is redirected back to the application with an authorization code in the query string. The application starts an access token request. The application requests an access token with the authorization code provided in the previous step. The OAuth server exchanges this authorization code for an access token Getting the User’s Permission The point of using OAuth is to enable users to get access to the parts of the Application that they need. To be able to do this the application first has to decide what permissions it is going to ask for, then send the User to a browser to get their permission to do this. To start the flow the application constructs a URL like the following and opens a browser to that URL.   GET https://integration.visma.net/API/resources/oauth/authorize ?response_type=code &client_id={yourApiClientID} &redirect_uri={yourRegisteredRedirectURI} &scope=financialstasks &state={randomStringGeneratedByApplication}   Here’s each of the query parameters explained: response_type=code - This tells the authorization server that the application is initiating the authorization code flow. - This field is mandatory and has to be “Code”. client_id - The public identifier for the application. - This field is mandatory and is obtained when registering for Visma.Net Integrations redirect_uri - Tells the authorization server where to send the user back to after they approve the request. - This field is mandatory and must match the URI you registered for Visma.Net Integrations scope - One or more space-separated strings indicating which permissions the application is requesting. - This field is mandatory and case sensitive, it has to be financialstasks state - The application generates a random string and includes it in the request. It should then check that the same value is returned after the user authorizes the app. This is used to prevent CSRF attacks. - This field is recommended for the reasons stated previously When the user is redirected to the authorization server they will be prompted to enter their credentials to allow the applications request.   Redirect back to the Application If the user approves the request, the authorization server will redirect the browser back to the redirect_uri specified in the request, adding a code and state to the query string. For example, the user will be redirected back to a URL such as: https://yourApplicationLivesHere.com/redirect ?code={authorizationCodeGeneratedByAuthServer} &state={randomStringGeneratedByApplication}   The state value will be the same value that the application initially set in the request. The application is expected to check that the state in the redirect matches the state it originally set. This protects against CSRF and other related attacks. The code is the authorization code generated by the authorization server. The lifespan of this code is 10 minutes. Exchange the Authorization Code for an Access Token The second part of the Authorization Code flow is to exchange the Authorization Code the user just received for an Access token. The application makes a POST request to the token endpoint. There are two ways of doing this, HTTP Basic authentication and sending the client_ID and client_Secret in the request body. Both ways require a couple of parameters. Here’s each of the query parameters explained: grant_type=authorization_code - This tells the token endpoint that the application is using the Authorization Code grant type. - This has to be “authorization_code”. Code - The application includes the authorization code it was given in the redirect.  redirect_uri - The same redirect URI that was used when requesting the code.  client_id - The application’s client ID. - This is the ID obtained when registering for Visma.Net Integrations. client_secret - The application’s client secret. This ensures that the request to get the access token is made only from the application, and not from a potential attacker that may have intercepted the authorization code. - This is the secret obtained when registering for Visma.Net Integrations. Please note: All these fields are mandatory. 1. HTTP Basic authentication The HTTP Basic authentication scheme is the preferred way and we encourage all clients that can utilize this authentication scheme to use it. It is done by providing an Authorization header on the request:   Authorization: Basic XXXXXXXXXX= - The value of the Authorization header is a string composed from the authorization method a space(“Basic “) followed by a Base64 encoded string obtained from combining client_ID and client_Secret separated by a colon(client_id:client_secret). Example of this can be seen below: Request Header: POST https://integration.visma.net/API/security/api/v2/token Content-Type: application/x-www-form-urlencoded Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ= Request Body: grant_type=authorization_code& code={authorizationCodeGeneratedByAuthServer}& redirect_uri={yourRegisteredRedirectURI}& 2. Request body The second option for the client is to send it's client_id and client_secret to Visma.net Integrations in the request body. This option should be used by clients that cannot utilize HTTP Basic authentication directly. Example of this can be seen below: Request Header: POST https://integration.visma.net/API/security/api/v2/token Content-Type: application/x-www-form-urlencoded Request Body: grant_type=authorization_code& code={authorizationCodeGeneratedByAuthServer}& redirect_uri={yourRegisteredRedirectURI}& client_id={yourApiClientID}& client_secret={yourApiClientSecret} Please note: All the request parameters sent to https://integration.visma.net/API/security/api/v2/token must be sent on request body. Even though the entire transmission is encrypted when using HTTPS, it is not recommended to send sensitive information (password and client_secret) in the URL as query parameters. The URLs are stored in web server logs which means that your sensitive data is saved in clear text on the server. The token endpoint will verify all the parameters in the request, ensuring the code hasn’t expired and that the client ID and secret match. If everything checks out, it will generate an access token and return it in the response. A successful response will look like this: Response headers: HTTP/1.1 200 OK Content-Type: application/json Response body: { "token": "1f729814-1a98-4c8e-860b-76ec004742f5", "token_type": "bearer", "scope": "financialstasks" } Now the client can start using the token and token_type to make requests through VNA against Visma.net Visma.net Financials resources. Please note: Once generated, the token currently does not expire; the token can be used for making subsequent calls towards the exposed endpoints. A new token should not be generated before making a new call; the token is not connected to the session.  
View full article
28-01-2020 14:30 (Updated 28-01-2020)
  • 5 Replies
  • 0 kudos
  • 8113 Views
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.
View full article
22-01-2020 15:52 (Updated 07-06-2021)
  • 3 Replies
  • 1 kudos
  • 8526 Views
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:    
View full article
12-01-2023 10:18
  • 2 Replies
  • 0 kudos
  • 766 Views
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.
View full article
07-12-2022 16:19 (Updated 07-12-2022)
  • 2 Replies
  • 0 kudos
  • 9959 Views
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.
View full article
20-09-2022 08:00
  • 2 Replies
  • 0 kudos
  • 4856 Views
Since version 8.19 (18.02.2020), a method for retrieving resources with base64url encoded values has been available for all resource endpoints.   This makes it possible to use characters otherwise reserved in URL, i.e: : / ? # [ ] @ & * + ;  To use it, one simply adds b64(encodedValue) in place of the resource name when you make your request.   Below is an example of how this works. Inventory item with several reserved characters: Getting this without encoding the resource name will result in an error: GET /Inventory/:/?#[]@&*+;   If you instead encode the value with base64Url encoding: :/?#[]@&*+;  ⇾ Oi8_I1tdQCYqKzs, and insert it in the b64 method you will get the wanted item: GET /inventory/b64(Oi8_I1tdQCYqKzs)   If you want to read more about base64Url encoding, please have a look at the following links: RFC 4648 § 5  Base64Guru base64encode
View full article
11-01-2021 13:06
  • 1 Replies
  • 0 kudos
  • 1906 Views
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]
View full article
15-03-2024 16:16
  • 0 Replies
  • 2 kudos
  • 121 Views
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.
View full article
01-12-2022 10:54 (Updated 01-12-2022)
  • 0 Replies
  • 0 kudos
  • 2398 Views
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
View full article
06-09-2022 10:49
  • 0 Replies
  • 0 kudos
  • 4705 Views
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.
View full article
14-03-2022 17:17 (Updated 15-03-2022)
  • 0 Replies
  • 0 kudos
  • 2612 Views
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
View full article
09-02-2022 18:47
  • 0 Replies
  • 0 kudos
  • 578 Views
In order to be able to add a new "Contact" to a Supplier or Customer via Visma.net ERP API, we can use the POST - Contact Endpoint.  Visma.net ERP API - Endpoint Documentation     Visma.net Financials ERP - Contact Module - ScreenID=CR302000     The connection between Supplier / Customer and Contact will be established by "businessAccount" field which is available in the POST - Contact DTO. "businessAccount": { "value": "string"   We need to set POST - Contact:"businessAccount" field's value with the "Customer ID" or "Supplier ID" depending on where you'd like to assign the "Contact". 1) POST Contact Endpoint (Sample payload) https://integration.visma.net/API/controller/api/v1/contact { "active": { "value": true }, "title": { "value": "Doctor" }, "firstName": { "value": "Crowley" }, "lastName": { "value": "Ozy" }, "position": { "value": "Position" }, "businessAccount": { "value": "Supplier or Customer ID" }, "sameAsAccount": { "value": false }, "address": { "value": { "addressLine1": { "value": "A1" }, "addressLine2": { "value": "A2" }, "addressLine3": { "value": "A3" }, "postalCode": { "value": "1313" }, "city": { "value": "test" }, "countryId": { "value": "01" }, "county": { "value": "02" } } }, "email": { "value": "test@gmail.com" }, "web": { "value": "web" }, "phone1": { "value": "0002" }, "phone2": { "value": "56565655" }, "phone3": { "value": "656565" }, "fax": { "value": "65656565" }, "contactMethod": { "value": "Any" }, "doNotCall": { "value": true }, "doNotFax": { "value": true }, "doNotEmail": { "value": true }, "doNotMail": { "value": true }, "noMassMail": { "value": true }, "noMarketing": { "value": true } }   2) Financials ERP UI Output Customer: Supplier:
View full article
07-06-2021 15:41 (Updated 07-06-2021)
  • 0 Replies
  • 0 kudos
  • 819 Views
Currently, the "Attributes" parameter is exposed on the following endpoints.  Endpoint Customer CustomerContract Inventory Project Supplier   Setting the attributes for other assets works in the same way as for e.g. customer.    To set Attributes on Customers and Inventory Items you first need to Create the attributes in the UI. Assign the attributes to the Customer/Inventory etc. Classes respectively. Assign the class to the Customer/Inventory Item you want to use them on. Set the values of the attributes. 1. Creating the attributes: You can do this in the Attributes screen(ScreenId=CS205000): 2. Assigning the attributes to the class: Customer You can either reach the customer classes by Going to screen ScreenId=AR2010PL Clicking on the pen next to the class in the customer card: Here you then add attributes based on the attributes you have created in the attributes screen. Inventory You can either find the Item classes by: Going to the Item class screen(ScreenId=IN201000) Or clicking in the pen next to the Item class in the Inventory screen: Same as for customer, you can add attributes here based on the attributes you have created in the Attributes screen.   3/4. Setting the attributes and their values When this has been done, you can under the Attributes tab add the attributes from the classes the Customer/Inventory belongs to and set their values:   Using the attribute parameter via the API   To use these attributes, below is the syntax to use in your query: Filtering on several attributes. {{base}}/inventory?attributes={"AttributeID1":"ValueID1","AttributeID2":"ValueID2"} Filtering on date time {{base}}/inventory?attributes={"DATETIME":"2019-04-19"} Filtering on text. It will not match partial strings. only exact string. {{base}}/inventory?attributes={"TEXT":"long text to filter upon"} Filtering on True/False {{base}}/inventory?attributes={"ACTIVE":"1"} With special case for Multiple selection combo: {{base}}/inventory?attributes={"AttributeID":"ValueID1,ValueID2"}​ When encoding your query, the "equal sign" should not be encoded, below is an example for the customer endpoint and accepted forms of encoding it: Customer Endpoint: GET {baseUrl}customer?attributes={"DATETEST":"2019-01-01","TEST":"testvalue"} Encoded: (both encoding examples below are accepted) customer?attributes=%7B"DATETEST":"2019-01-01","TEST":"testvalue"%7D customer?attributes=%7B%22DATETEST%22%3A%222019-01-01%22%2C%22TEST%22%3A%22testvalue%22%7D Inventory Endpoint Inventory?attributes={"TEST":"testvalue"} Encoded: (both encoding examples below are accepted) inventory?attributes=%7B"TEST":"testvalue"%7D inventory?attributes=%7B%22TEST%22%3A%22testvalue%22%7D
View full article
19-04-2021 16:20 (Updated 21-05-2021)
  • 0 Replies
  • 1 kudos
  • 2759 Views
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.
View full article
25-03-2021 15:20 (Updated 07-06-2021)
  • 0 Replies
  • 0 kudos
  • 1022 Views
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)
View full article
18-12-2020 15:03 (Updated 13-11-2023)
  • 0 Replies
  • 0 kudos
  • 1007 Views
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.
View full article
20-10-2020 12:13 (Updated 02-02-2021)
  • 0 Replies
  • 2 kudos
  • 2539 Views
In this article we'll review an error message that can be returned when invoking POST > Timecard operation via Timecard Endpoint as well as how to resolve this issue. Timecard endpoint is corresponding with "Employee time card" module in the Visma.Net ERP. (Document View "ScreenID=EP305000"  / Module View ScreenID=EP406000 )   Employee field indicates the employee's reference ID that who we want to create a time card for. The correspondent field in the API POST/PUT DTO is  "employee": { "value": "string" },   Based on your Financials ERP Company setup , The ID of the currently signed-in employee is selected by default on the identifier of the employee whose time cards you want to manage. If your Visma.net User which is used while generating an API Token isn't member of a group that is not hierarchically higher order in the company tree than the desired Employee ID  you want to create a time card, TimeCard POST operation returns the following error: "message": "You cannot create timecards for the selected user. Please review the company tree." The same scenario is valid for ERP UI as one cannot select different employee unless above-mentioned settings are configured. Since this is related to your Financials ERP Company configuration, you need to adjust organization/company tree setup. In order to be able to configure this, please follow the instructions below. 1) Workgroup assignment for the Employee Go to Company Tree (ScreenId=EP204060)  Click your Company Name on top left Add a group by clicking (+) under List of Groups Add a Group Member  Update Tree Save                   2) Continuing with, Create a new group under the recently created one.  Click Test Group on the hierarchy tree (left)  Add a group by clicking (+) under List of Groups Add a Group Member (That is different from your current Login, this employee must be registered in the company) Update Tree Save                 3) Then select newly created group e.g (A Group) and click (=>) right arrow, this will give transaction access to your current user on the users these grouped below in the hierarchy.                     4) Now this employee can be selected / used with both UI Employee Time Card and API.
View full article
31-08-2020 15:43 (Updated 31-08-2020)
  • 0 Replies
  • 0 kudos
  • 1126 Views
About paging When getting lists of data from API-endpoints it will be most efficient for both the client and server to divide the result into portions instead of getting all the data returned at once. The Visma.net API supports this by implementing a method called paging. Paging means that when you request lists of data you should also provide two extra query-parameters called pageSize and pageNumber. pageSize: The maximum number of records you want to have returned on each page (the length of each page) pageNumber: The page you are requesting.   Example In the database you have 350 customers, you make a GET request to the Customer-endpoint to get all these. To limit the number of customers received you can divide this into pages that contain upto 100 customer (pageSize=100). To get the complete list you then have to make 4 requests to the Customer-endpoint:     Request Result 1 GET /customer?pageSize=100&pageNumber=1  Returns the first 100 customers (1-100) 2 GET /customer?pageSize=100&pageNumber=2 Returns the second page of 100 customers (101-200) 3 GET /customer?pageSize=100&pageNumber=3 Returns the third page of 100 customers (201-300) 4 GET /customer?pageSize=100&pageNumber=4 Returns the last page of remaining customers (301-350)   Paging is implemented on all GET endpoints that returns lists in the Visma.net API. It is mandatory to use the parameters pageSize and pageNumber in all requests to endpoints that support this. How paging is implemented in Visma.net API For all endpoints that return lists paging is implemented by providing two queryparameters, pageSize and pageNumber. For all endpoints these parameters are documented in the swagger documentation (https://integration.visma.net/API-index/). For all endpoints that provide these parameters it is important that your integration provide these for all requests. If not provided default-values will be used and you will potentially not receive the complete resultset. In the swagger-documentation you can see the default-value for the specific endpoint. Default parameter values Parameter Default value (if not provided) pageNumber 1 pageSize Can vary from endpoint to endpoint, can also change over time. Maximum value for the pageSize parameter is bound to the default-value that will also represent the maximum value allowed. Meaning that if you specify a value in pageSize that is greater than the default value, the endpoint will only return the number of records defined by the default value for pageSize in this endpoint. In addition to swagger-documentation the maximum allowed value for pageSize will also be returned as part of the metadata-property in the returned JSON-data. The value will have the name maxPageSize.               "metadata": { "totalCount": 450, "maxPageSize": 500 }               Metadata As part of every request to an endpoint that supports paging you will get a metadata-property returned as part of the returned JSON-data. This metadata is provided to give your integration information about the available results and restrictions of the current request. The metadata-property will provide the following values:               "metadata": { "totalCount": 450, "maxPageSize": 500 }                 Value Description totalCount The total number of results for the current request regardless of pages. Example: GET /customer?name=Norwegian?pageSize=5&pageNumber=1 This request will return the first page of 5 customers with the name containing “Norwegian”. However, in the database there are 12 customers with names containing “Norwegian”, so the totalCount will have the value 12. maxPageSize The maximum pageSize you can set for this endpoint. If you specify a number higher than this, the result will be restricted to only return the maxPageSize number of records.   You can use the values in the metadata to calculate the number of pages you need to get in order to receive the whole result-set based on the pageSize you are using. Paging in combination with filters Most GET-endpoints in the API contain filter-parameters. These are used to narrow down the resultset to only contain the records that are relevant to the request. It is important to notice that when these filter-parameters are used in combination with the paging-parameters, the resultset is defined as the total resultset for the specified filter-parameters. This means that if the resultset spans across multiple pages, the exact same filter-parameters must be specified for all subsequent requests to get the following pages. The Visma.net API contains no state to store what pages/records have been delivered, so every request will be handled independent of previous requests. The figure below illustrates what results will be included in each page based on three different queries with different values for parameters lastModifiedDateTime and pageSize. Query 1: ?lastModifiedDateTime=2020-03-01T00:00:00&lastModifiedDateTimeCondition=>=&pageSize=3 The resultset will be divided into 4 different pages, meaning that you have to make 4 requests to the API, with the exact same values for parameter lastModifiedDateTime, lastModifiedDateTimeCondition and pageSize. The pageNumber-parameter will define what results you will get, marked by the numbers 1-4 and the colors yellow, pink, green and blue in the figure.   Query 2: ?lastModifiedDateTime=2020-03-01T00:00:00&lastModifiedDateTimeCondition=>=&pageSize=5 The resultset will be divided into 2 different pages, meaning that you have to make 2 requests to the API, with the exact same values for parameter lastModifiedDateTime, lastModifiedDateTimeCondition and pageSize. The pageNumber-parameter will define what results you will get, marked by the numbers 1-2 and the colors green and purple in the figure.   Query 3: ?lastModifiedDateTime=2020-03-06T00:00:00&lastModifiedDateTimeCondition=>=&pageSize=3 The resultset will be divided into 2 different pages, meaning that you have to make 2 requests to the API, with the exact same values for parameter lastModifiedDateTime, lastModifiedDateTimeCondition and pageSize. The pageNumber-parameter will define what results you will get, marked by the numbers 1-2 and the colors blue and gray in the figure.       If you do not keep these parameters constant (the pageSize is changed), and do the following set of requests:   ?lastModifiedDateTime=2020-03-01T00:00:00&lastModifiedDateTimeCondition=>=&pageSize=3&pageNumber=1 ?lastModifiedDateTime=2020-03-01T00:00:00&lastModifiedDateTimeCondition=>=&pageSize=5&pageNumber=2 This will result in you getting the following records: First request: Record 1,2,3 Second request: Record 6,7,8,9,10 As you can see the records 4 and 5 will not be returned to you. New records added while getting pages Sometimes new records are added to or removed from the database by other uses while you are getting the records using paging. In that scenario the totalCount metadata-property will always change to reflect the new total number of records available for your query. Because of this it is important to always check the value of totalCount for each GET request to retrieve a new page, to be able to calculate the total number of pages needed to get the complete resultset. Example You want to get all the customer with status=”Active”, the results should be divided into pages with 10 customers (pageSize=10). You make the following request to get the first 10 customers. GET/customer?status=Active&pageSize=10&pageNumber=1 As part of the response you get the metadata including the totalCount - property that tells you that the total number of results are 30.           "metadata": { "totalCount": 30 }             3. This means that you have to repeat the request two more times to get the full result-set. 4. You make the second request to get the next 10 customers. GET/customer?status=Active&pageSize=10&pageNumber=2 5. As part of the response you again get the metadata including the totalCount - property, but this now tells you that the total number of results are 32. Meaning that two new customers have been added or changed status to Active by another user               "metadata": { "totalCount": 32 }               6. This means that you now have to make a total of 4 requests to get the complete result-set. (10+10+10+2). This shows that your client should always keep track of the total number of results received and the total count of results available to make sure that you always get the complete result-set. The following code-example represents a possible implementation of this.                 def get_all_active_customers(): page_size = 10 # The pageSize we want to use nest_page_number = 1 # The next page to get, initial value = 1 results_recieved = 0 # The number of results we've recieved total_count = 1 # The total number of results available #If we've revieved less than the total number of resultes, we make a new loop while results_recieved < total_count: response = request.get('https://integration.visma.net/API/controller/api/v1/customer', params={ 'status': 'Active', 'pageSize': page_size, 'pageNum': next_page_number }, headers={ 'Accept': 'application/json', 'Authorization': 'Bearer' + token, 'ipp-company-id': company_id, 'ipp-application-type': 'Visma-net Financials' } | ) if response.status_code == 200: result = json.loads(response.text) # Decodes the recieved JSON # {handle the results} # Increments the number of results recieved by the number of results recieved by this request results_recieved += result.len total_count = result[0]['metadata']['totalCount'] # Updates the total_count variable with the current total count of results next_page_number += 1 # Increments the next page to get by 1             Reference: www.visma.no/erp/api/dokumentasjon/paging Enforcement of pagination on API endpoints and change of maxPagesize - September release (8.25)
View full article
28-07-2020 16:22 (Updated 05-02-2021)
  • 0 Replies
  • 0 kudos
  • 5010 Views
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.
View full article
10-02-2020 12:25 (Updated 10-06-2021)
  • 0 Replies
  • 0 kudos
  • 2379 Views