Knowledge base in Developers Visma.net

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.  

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

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 ---------------------------------------------------------------------------------------------------------------------------------------- We're currently working on updating the swagger documentation, once the work is done, function will be listed on all the related operations / actions accordingly.   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.

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]

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

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:

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

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.

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)