top of page
RedHorn.png

for Visma Business

top

RedHorn API for Visma Business is a REST based web API enabling access to Visma Business data over HTTP.

 

The API uses and requires HTTPS. The API exposes one resource per entity type/table within the Visma Business data model.

​

For example, the Orders table in Visma Business is exposed via the URI /api/{companyNo}/orders.

Replace {companyNo} with the desired Visma company number (e.g. /api/9999/orders).

All available resources (about 350 in total) can be listed via the Swagger iv documentation by browsing /swagger.

introducton

Setup Prerequisites

setup_prerequisites

IIS (Internet Information Services) have to be installed along with the ASP.NET modules.

See the following link for further information:

​

https://docs.microsoft.com/en-us/iis/applicationframeworks/scenario-build-an-aspnet-website-on-iis/configuring-step-1-install-iis-and-asp-netmodules

Supported versions of Visma Business

​

​2021-08-26

​

​Release API version 1.4
 

  • Pagination and count support with the OData query options $orderBy, $skip, $top and $count.

  • Improved automatic licence renewal support via Licence Service Web API.

  • Support to assign a value from the number series for a non primary key property (e.g. CustomerNo, SupplierNo and EmployeeNo for the Associate resource).

  • ​Improved automatic licence renewal support via Licence Service Web API.

Read more ➜

​2021-05-24

​

​Release API version 1.3

​

  • Support for Token-based authentication in addition to the existing Basic authentication.

  • Support for automatic product licence renewal via Licence Service Web API.

  • The product is rebranded and the new name is "RedHorn Visma Business API" (before "Capremill Visma Business Access API").

Read more ➜

​2021-05-24

​

​Release API version 1.2

​

  • New response structure for POST/PUT requests.

  • Custom assignment order for property values against Visma/VBS.

  • Support for Visma Data Model Extension (DME).

Read more ➜

Setup IIS

setup_iis

Depending on your requirements it might be an option to set up the Web API as a new application under an existing Website instead of creating a new Website (step 2 below). In that case - make sure to apply the applicable settings from the configuration part (step 3.2).

​

  1. Copy the provided files for the Web API and paste them in a suitable directory on the web server (e.g. “C:\RedHorn Visma Business API\”).
     

  2. Start IIS Use windows navigation menu and open IIS on your system, or open IIS by typing inetmgr in the run window.
     

  3. Add new Website in IIS
     

  4. Add new Website In left side base expand the tree and select Sites option. Right click on sites and select Add Website. This will open a popup to input new website details.
     

  5. Configure the Website Enter an appropriate site name (e.g. “RedHornVismaBusiness”) Select an application pool or create a new one dedicated to this site (default behaviour) Set the physical path to the Web API files directory (see step 1)
     

  6. Set the binding type to https Enter a port on which the website will be accessible for API users Select an SSL Certificate
     

  7. Add login in SQL Server (if Integrated Security is used) If the connection string to Visma database server (see VismaDbConnectionString in next section) is configured to use integrated security/trusted connection, the credentials for the identity used for the application pool is used. This identity is by default the ApplicationPoolIdentity, which results in a user named “IIS APPPOOL\ RedHornVismaBusiness” (if the application pool name is “RedHornVismaBusiness”). Add a login in SQL Server for this identity/user and map the login to the Visma company databases and the company independent databases “Catalog” and “vbsys”. Select the role membership “db_datareader”.
     

  8. Grant write access to the licence file for the AppPool user In order for the licence auto update feature to work.
     

Configuration Settings

configuration_settings

The settings for the Web API are located in the file “appsettings.json”.

The settings file contains three sections:

​

 

Important: Note that once the Web API is up and running the settings are cached in memory.

Changes to the settings file are not reloaded until the site is restarted.

The “Restart” action might not be enough though – instead stop the site, wait a couple of seconds, and then start it again.

appsettings.json

{
   "ApiLicence": {
       "LicenceFilePath": "~/RedHorn.VismaBusiness.lic",
       "LicenceServiceBaseUrl": "https://licence.capremill.se/"
   },
   "VismaConnection": {
       "DefaultVbsContextUser": "",
       "VbsIntegrationUser": "",
       "VbsIntegrationUserPassword": "",
       "VbsSiteId": "Standard",
       "VbsCultureId": "English__UnitedKingdom",
       "VbsEndpointAddress": "http://localhost:2001/GenericService",
       "VismaDbConnectionString": "Server=localhost;Trusted_Connection=true;"
   },
   "ApiUsers": [
       {
           "Username": "RedHornVismaBusinessApiUser",
           "Password": "lkhasgflhsadfge983fes#%JGjk#%#KJHldK",
           "VbsContextUser": "", 
           "AllowBasicAuthentication": true,
           "AllowAccessToSysDb": false,
           "AllowAccessToCatalogDb": false,
           "AccessibleCompanies": [
               9999
           ],
           "NumberSerieIntervals": [
               //{
               //    "ColumnNo": 4045,        // 4045 = Associate.CustomerNo
               //    "IntervalFrom": 1,
               //    "IntervalTo": 999
               //}
           ]
       }
   ]
}

Configuration API licence

configuration_apilicence

The ApiLicence section contains parameters for the Web API licencing.

​

  • LicenceFilePath 
    The file path to the licence file for the Web API (e.g. "~/RedHorn.VismaBusiness.lic")
     

  • LicenceServiceBaseUrl
    The base URL for the licence service Web API (default "https://licence.capremill.se/"), provided by us (Capremill System AB), to be able to update the licence file automatically before it expires.

    The licence service Web API have to be accessible from the web server (access to internet via port 443) in order for this auto update feature to work.
    If not, the licence file has to be manually replaced before it expires.

​

Configuration Visma connection

configuration_vismaconnection

The VismaConnection section contains parameters needed to be able to connect to Visma Business.

​

  • DefaultVbsContextUser
    The Visma user (named user) to be used as context user in VBS if the API user does not contain an override (see the APIUsers section)
     

  • VbsIntegrationUser
    The Visma user (server integration) to be used to authenticate against VBS.
    It’s possible to use a named user and leave the context user empty, but that’s not recommended for a number of reasons.
     

  • VbsIntegrationUserPassword
    The password for the VbsIntegrationUser.
     

  • VbsSiteId
    The Site ID (default “Standard”).
     

  • VbsEndpointAddress
    The URL to the VBS service endpoint (default "http://localhost:2001/GenericService").
     

  • VismaDbConnectionString
    The connection string to Visma database server.

Configuration API users

configuration_apiusers

The ApiUsers section contains an array of API user objects.

​

  • Username
    Username The username for the API user. Used to authenticate to the API (Basic or Bearer Authentication).
     

  • Password
    The password for the API user. Used to authenticate to the API (Basic or Bearer Authentication).
     

  • VbsContextUser
    The Visma user (named user) to be used as context user in VBS for this particular API user (overrides the VismaConnection.DefaultVbsContextUser).
    Leave empty to use the DefaultVbsContextUser.
     

  • AllowAccessToSysDb
    Whether or not this API user should be able to access the company independent database “vbsys”.
     

  • AllowAccessToCatalogDb
    Whether or not this API user should be able to access the company independent database “Catalog”.
     

  • AllowBasicAuthentication
    Whether or not Basic Authentication should be available for this API user (default true for backwards compatibility). Set to false to only allow Bearer Authentication.
     

  • AccessibleCompanies
    An array of company objects for the Visma companies this API user should be able to access.
    The company object contains the mandatory property CompanyNo, and the optional property NumberSerieIntervals.
     

  • CompanyNo
    The Visma company number (e.g. 9999).
     

  • NumberSerieIntervals
    Can be used if multiple number series exists for a non primary key property that supports assignment from number series (e.g. CustomerNo, SupplierNo and EmployeeNo for the Associate resource).
    A default interval has to be defined for VBS to be able to handle the assignment, and if it’s not suitable/ sufficiently to set a default interval per company (can be done in "Company data" in Visma for customer and supplier), this property can be used to define an interval for one/multiple property/properties per API user and company.

Examples

examples

This section provides a set of examples of how to work with the Web API. The examples are not intended to cover common scenarios but rather illustrating different ways the requests could be set up.

​

Authentication

The HTTP Authentication Schemes Basic and Bearer are available.

​

  • Basic Authentication
    Basic authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password. E.g. “Authorization: Basic YXBpMTph”.
     

  • Bearer Authentication (Token Based Authentication)
    Token-based authentication is a process where the credentials for the API user are sent in a request to obtain an access token.
    This token is then used (instead of the username/password credentials) to access the protected API resources for a designated period of time.
    To get a token - make a POST request to the API endpoint /api/oauth/token.
    The body of the request should contain the following form-url-encoded data:

    -username: <username for API user>
    -password: <password for API  user>
    -grant_type: "password"

    The response (if the credentials were validated successfully) contains the access token string, along with information regarding type ("token_type": "bearer") and how long the token is valid ("expires_in": XXXX) in seconds.

Bearer Authentication

curl --location --request POST '/api/oauth/token' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--data-urlencode 'username=' \

--data-urlencode 'password=' \

--data-urlencode 'grant_type=password'

​

Response body

{

"access_token": "uxuFqlF2JO3latEH5W072S5pqhwt9pra187vli4co4R…",

"token_type": "bearer",

"expires_in": 7200

}

bottom of page