Knowledge base in Developers Visma.net

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.

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)

  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.

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.  

  In this article, you can find guidelines for how to use Visma.Net API Endpoints connected to the Customer Ledger from Visma.Net Financials. 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     Supplier  Common usage example for Supplier(ScreenId=AP303000) URL: https://integration.visma.net/API/controller/api/v1/Supplier Methods: GET All Suppliers URL: https://integration.visma.net/API/controller/api/v1/Supplier   Example of usage with parameters Query parameters: lastModifiedDateTime=YYYY-MM-DD As of today Filtering Parameters does not accept certain characters such as W-Z These are the formats for Filtering *2001-01-01 *2001-01-01 13:13:13 *2001-01-01 13:13:13.133   lastModifiedDateTimeCondition=Operator Supported comparative operators for LastModifiedDateTime Conditions on filtering  > - Greater than < - Less than <= - Less than or equal to >= - Greater than or equal to   Usage example: This query will return suppliers updated on 2020-01-14 or later. GET https://integration.visma.net/API/controller/api/v1/Supplier ?lastModifiedDateTime=2020-01-14 &l astModifiedDateTimeCondition=>= ( Lines are separated for readability) POST Supplier URL: https://integration.visma.net/API/controller/api/v1/Supplier   This example shows the minimum fields you should send to be able to post a new Supplier, if you are using automatic numbering you can omit the “number” field. JSON Request body {     "number": {         "value": "50002"     },     "name": {         "value": "NewSupplier"     },     "mainAddress": {         "addressId": 3001,         "addressLine1": "Testroad 5",         "postalCode": "0110",         "city": "OSLO",         "country": {             "id": "NO",             "name": "NORGE"         },         "county": {             "id": "0301",             "name": "OSLO"         }     },     "supplierClassId": {         "value": "1"     } }   If sent successfully, the API will return: Status 201 Created   Supplier Invoice Common usage example for Supplier Invoice(ScreenId=AP301000) URL: https://integration.visma.net/API/controller/api/v1/SupplierInvoice Methods: GET All Supplier Invoices URL: https://integration.visma.net/API/controller/api/v1/SupplierInvoice   Example of usage with parameters Query parameters: Project=String Will limit response to documents with the specified project   Usage example: This will return Supplier Invoices with projectID 20. GET https://integration.visma.net/API/controller/api/v1/customerDebitNote ?project=20 POST SupplierInvoice URL: https://integration.visma.net/API/controller/api/v1/SupplierInvoice   This example shows the minimum fields you should send to be able to post a new Supplier Invoice, if you are using automatic numbering you can omit the “referenceNumber” field. JSON Request body {     "date": {         "value": "2019-11-08T00:00:00"     },     "documentType": {         "value": "Invoice"     },     "referenceNumber": {         "value": "000357"     },     "invoiceLines": [         {             "inventoryNumber": {                 "value": "test*test"             },             "lineNumber": {                 "value": "1"             },             "operation": "Insert",             "projectId": {                 "value": "X"             },             "quantity": {                 "value": 1             },             "subaccount": [                 {                     "segmentId": 1,                     "segmentValue": "00"                 }             ],             "unitCostInCurrency": {                 "value": "1.60"             },             "vatCodeId": {                 "value": "1"             }         }     ],     "paymentRefNo": {         "value": "test"     },     "postPeriod": {         "value": "112019"     },     "supplierNumber": {         "value": "50000"     },     "supplierReference": {         "value": "test"     } }   If sent successfully, the API will return: Status 201 Created   PUT PurchaseOrder URL: https://integration.visma.net/API/controller/api/v1/SupplierInvoice/{debitNoteNumber}   When using PUT, you only send the fields you want to update. In the below example, we update the first line of the Credit Note: URL PUT https://integration.visma.net/API/controller/api/v1/SupplierInvoice/000050 JSON Request body {     "lines": [         {             "operation": "Insert",             "lineNumber": {                 "value": 1             },             "inventoryNumber": {                 "value": "6"             },             "quantity": {                 "value": 1             },             "unitPriceInCurrency": {                 "value": 1             }         }     ] }   If successful, the API will return: Status: 204 No Content   Purchase Order Common usage example for Endpoint(ScreenId=PO301000) URL: https://integration.visma.net/API/controller/api/v1/PurchaseOrder Methods: GET All Purchase Orders URL: https://integration.visma.net/API/controller/api/v1/PurchaseOrder   Example of usage with parameters Query parameters: Supplier=string Lets you search for Purchase Orders registered to one supplier   orderStatus=string Lets you define what orderStatuses to return, these are the Statuses of Purchase Order: On hold - The purchase order is a draft and can be edited manually. Open - The order was processed in accordance but has not been completed yet. Pending approval - The purchase order has not been approved by all the assigned persons. Rejected - The order was rejected by one of the persons assigned to approve it. Pending printing - Printing is required for the document but has not been performed yet. Pending e-mail - E-mailing is required for this document, but it has not been performed yet. Closed - All the ordered goods were received. Cancelled - The order was cancelled through the “ Cancel order” action - An order with this status cannot be edited, and purchase receipts cannot be based on it.   Usage example: This will return Purchase Orders registered on supplier “50000” that are in status OPEN. GET https://integration.visma.net/API/controller/api/v1/purchaseorder ?Supplier=50000 &status=open (Lines are separated for readability) POST PurchaseOrder URL: https://integration.visma.net/API/controller/api/v1/PurchaseOrder   This example shows the minimum fields you should send to be able to post a new Purchase Order, if you are using automatic numbering you can omit the “referenceNumber” field. JSON Request body {     "orderType": {         "value": "RegularOrder"     },     "date": {         "value": "2019-12-27T09:46:11.202Z"     },     "supplier": {         "value": "50000"     },     "lines": [         {             "operation": "Insert",             "inventory": {                 "value": "teststock"             },             "lineType": {                 "value": "GoodsForInventory"             },             "warehouse": {                 "value": "2"             },             "uom": {                 "value": "PALL"             },             "orderQty": {                 "value": 2             },             "unitCost": {                 "value": 2000             }         }     ] }   If sent successfully, the API will return: Status 201 Created PUT PurchaseOrder URL: https://integration.visma.net/API/controller/api/v1/PurchaseOrder/{purchaseOrder}   When using PUT, you only send the fields you want to update. In the below example, we update the first line of the Credit Note: URL PUT https://integration.visma.net/API/controller/api/v1/PurchaseOrder/25698 JSON Request body {     "lines": [         {             "operation": "Update",             "lineNumber": {                 "value": 1             },             "inventoryNumber": {                 "value": "6"             },             "quantity": {                 "value": 1             },             "unitPriceInCurrency": {                 "value": 1             }         }     ] }   If successful, the API will return: Status: 204 No Content   Supplier Payment Common usage example for Endpoint(ScreenId=AP302000) URL: https://integration.visma.net/API/controller/api/v1/SupplierPayment Methods: GET All Supplier Payments URL: https://integration.visma.net/API/controller/api/v1/SupplierPayment   Example of usage with parameters Query parameters: SupplierId=String This will limit the response to the provided SupplierId   Usage example: This will return Purchase Orders registered on supplier “50000”  GET https://integration.visma.net/API/controller/api/v1/purchaseorder ?Supplier=50000 (Lines are separated for readability)