Knowledge base in Developers Visma.net

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

  You can get a recently created object ID by looking into the Response Headers{Location} of the HTTP Response Headers. HttpResponse.GetResponseHeader("location"); This is one of the Response Headers (LOCATION) that API returns after each successful POST Operation which contains created object ID. public string readLocation(string json) { string[] headers = new string[2]; string strResponse = string.Empty; string location = string.Empty; var httpWebRequest = (HttpWebRequest)WebRequest.Create(endPoint); httpWebRequest.ContentType = "application/json"; httpWebRequest.Method = httpVerb.POST.ToString(); httpWebRequest.Headers.Add("ipp-company-id", "<CompanyID>"); httpWebRequest.Headers.Add("ipp-application-type", "Visma.net Financials"); httpWebRequest.Headers.Add("Authorization", "<token>"); using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream())) { streamWriter.Write(json); streamWriter.Flush(); streamWriter.Close(); } var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse(); using (var streamReader = new StreamReader(httpResponse.GetResponseStream())) { var result = streamReader.ReadToEnd(); headers[0] = httpResponse.GetResponseHeader("location"); headers[1] = httpResponse.GetResponseHeader("date"); strResponse = ("ID: "+headers[0].Substring(headers[0].LastIndexOf('/') + 1)+" // Date: "+headers[1]); //Seperate Resource URL - Created Object ID } return strResponse ; } } Disclaimer The sample code on Visma Community > Visma.Net API is provided “AS IS” and any express or implied warranties, including the implied warranties of merchantability and fitness for a particular purpose, are disclaimed. In no event shall Visma or contributors be liable for any direct, indirect, incidental, special, exemplary or consequential damages.

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]

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:    

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.

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.

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.

When posting documents with subaccounts, some times you might encounter errors that look like this: “Error: (.*) of Subaccount do not exist."   To troubleshoot this please have a look at your Segment Key/Value setup of the dimension “SubAccount” (ScreenId=CS202000&DimensionID=SUBACCOUNT)     Clicking on the “Segment ID” will lead to the screen showing your values for that Segment Key:     If you have validation activated for your Segment Key’s, you need to set up the combinations you want to be using in the SubAccounts screen(ScreenId=GL203000)      

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)

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:

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

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.