Knowledge base in Developers Visma.net

  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.

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 )      

Manage environments Creating a new environment You can create a new environment from the: Manage Environments icon New button Launch screen Manage environments icon Click "Manage Environments" icon in the upper right corner of the Postman app.     Select “Manage Environments”. Click the Add button. New button In the header toolbar, click the New button or click the “Gear” Manage Environments icon   Click "Environment" and enter a name for the new environment.   Add the variables you want to save as key-value pairs.   Click the Add/Update button. Manage Environments to change the values with your own   base_uri :currently pointing to API environment < https://integration.visma.net/API > client_id : The client identifier given to the client during the Application registration process. client_secret : The client secret given to the client during the Application registration process. redirect_uri : (CallbackURL)The Application’s callback URL that’s registered with the server. If not provided, Postman uses a default empty URL and extracts the code or access token from it. company_id : Financials companyId that will be used on API calls   scope: The scope of the access request { financialstasks } state: An opaque value that prevents cross-site request forgery auth_URL: The endpoint for authorization server, which retrieves the authorization code.< https://integration.visma.net/API/resources/oauth/authorize > Access_Token_URL: The endpoint for the resource server, which exchanges the authorization code for an access token. < https://integration.visma.net/API/security/api/v2/token >     oAuth2 OAuth 2.0 is an authorization type that enables you to approve an application that contacts another application for you without exposing your password. To use the OAuth 2.0 authorization in Postman In the Authorization tab , select "OAuth 2.0" from the TYPE drop down menu. From the "Add authorization data to" drop down menu, select either "Request URL" or "Request Headers". To set the authorization parameters for a request, you have three options: Click the Get New Access Token button. The screen appears.  Enter the appropriate values, click the Request Token button to populate the "Access Token" field, and then click the Send button. In the "Access Token" field, enter a token, or an environment defined variable, and click the Send button. In the "Available Tokens" drop down menu, select an existing token and click the Send button.     Get New Access Token After clicking the Get New Access Token button , Postman brings the following screen where user should fill out the parameters.     The values used here are the variables defined in the environment. After filling the parameters user needs to click Request Token button.   You will be directed to a Visma.net login, enter your credentials and sign in.     Allow Visma.net Integrations to connect to your account.     After you click the Allow button and if entered data is correct, you will see the Postman window that has the token. By default Postman expects to find a field named: access_token in the response. Since the Visma.Net response contains a field named  token , instead of access_token , Postman cannot auto-detect it as an access_token     Copy the value of token , close the MANAGE ACCESS TOKENS screen and paste it in the Access Token field.      

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.  

Setup up your user rights To be able to use Visma.Net API you need to make sure your visma users have the correct roles on the company you want to use it for. Visma.Net Admin To be able to edit the access rights you need to be logged in with a user with “Customer administrator” role. To set your rights, click on Visma.Net Financials in the top left corner and choose Admin.   User and roles When you have accessed Visma.net Admin click on “User and roles”. Head to the “User” tab. Search for your user name and click your name. Company access and rights If the company you want to edit roles for does not exist in the list under your username, click the “Add access to” menu and look for the company you wish to add.      Find the company you want to edit roles for.     On the line for the desired company, press the field for “Financials” and add the roles “Financial Administrator” & “Financials User”.   Swagger Our Swagger is a good point for you to start using the API.   Connect to your Visma.Net account Authorize and get a VNF token to use in Swagger. Click “Authorize” on the right side of the interface.     Tick the box for “financialstasks” and press “Authorize”     You will be directed to a Visma.net login, enter your credentials and sign in.(If you are not asked to enter your credentials but get directed to the next step straight away, please clear your cookies in your browser and retry)     Allow Visma.net Integrations to connect to your account.     When you have allowed the connection you see that you are now authorized in Swagger. Close the window and proceed to use Swagger.   Start using Swagger The first thing you need to do is check what companies your visma.net financials user have access to. You can find the names and Ids via the “Context” endpoint. Scroll down to the “Context” endpoint and expand it.     Expand the first GET method - Get the companies available for this token, and press “Try it out”.     You will now see a button, “Execute”, press it and you’ll notice the result below will have updated to show your available companies. You’ll also see the request URL.     In the list, decide which company you want to use and copy the “id:”, this is the Id you will add to your “ipp-company-id” header when you are making requests. For now scroll back up to the top and paste the ID in the field “ipp-company-id”. When you have filled this field, the requests you execute via Swagger will target that company.    

Using webhooks can significantly improve the performance of your integration. With webhooks you can subscribe to changes and actions that happens in Visma.net and trigger functionality in your application.  This article explains how webhooks works, and how you can implement this.

  In this article, you can find guidelines 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)

Visma.Net Integrations - API Client Configuration In this document we will go through what needs to be done after you completed your Visma.Net Integration certification.  Redirect_URI The first thing you need to do to configure your API client is to set up an redirect_URI.  Redirect URIs are a critical part of the OAuth flow. After a user successfully authorizes an application, the authorization server will redirect the user back to the application with an authorization code in the URL. Because the URL will contain sensitive information, it is critical that the service doesn’t redirect the user to arbitrary locations.       Due to this, it is required to specify one or more redirect URIs when you register your integration with Visma.Net. For production it is required that the provided URI is set up with HTTPS.  When you have a redirect URI this should be sent your partner service in order for you to get your Client_ID and Client_Secret. When this has been processed, you will receive an Activation email for your registration, the link to activate your Client_Id will be active for 5 days , so make sure to do this when the email is received:     API client types For Visma.Net there are two client types available, API “ test client ” and “ production client ” (also known as live)   API Test Clients All new API clients are generated as the type “ Test ”. In the test client there is a limit to the allowed calls per hour, which is set to 500 calls/hour . When you are ready to go live with your integration you need to contact your partner service to get access to the API production client type.