RedHorn Visma Adm API is a REST i based web API enabling access to Visma Administration data over HTTP(S). The API uses and requires HTTPS.
The API exposes one resource per entity type/table within the Visma Administration data model.
For example, the Orders table in Visma Administration is exposed via the URI /api/{company}/orders.
Replace {company} with the desired Visma company code (e.g. /api/ftg1/orders).
All available resources (about 80 in total) can be listed via the Swagger documentation by browsing /swagger.
All operations (data retrieve and data manipulation) are performed via the Visma Administration integration component (ADK).
The ADK is an integration building tool provided by Visma.
The tool uses the same business logic as Visma Administration to validate data being added to the system via an integration.
1 Authentication
The HTTP Authentication Schemes Basic and Bearer are available.
By default, both of them are available due to backwards compatibility. It’s possible to disable Basic Authentication though, to provide Bearer Authentication only. This is done per API-user..
1.1 Basic Authentication
The credentials for the API user are transmitted as username/password pairs in the HTTP authorization header for every request.
1.2 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 (e.g. two hours).
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 the 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.
2 Data retrieving
Data retrieving is performed using the HTTP GET method against a specific resource.
2.1 OData queries
When fetching data from the API you can specify what information you are interested in by using OData queries.
If you for example want to get the customer name for the customer with customer number 123 you would use the following request:
/api/{company}/customers?$select=namn&$filter=kundNr eq ‘123’
2.1.1 Define properties/fields - $select
Specify the information you want to fetch using the OData query option $select and provide a comma separated enumeration with the properties/fields of interest.
Properties/fields with null values will be excluded in the response.
E.g. $select=dokNr,fktTyp,datum1
2.1.2 Define query filter - $filter
By using the OData query option $filter you are able to specify conditions that have to be met in order to be part of the result set.
E.g. $filter=landKod in(‘SE’,’NO’) and orderplock eq true and startswith(namn, 'abc')
2.1.3 Include rows - $expand
Some entities (e.g. Order and Invoice etc) have a row collection associated to it (e.g. order-/invoice rows).
These entities have a property/field named rows, which can be expanded by using the $expand OData query option. Within the expand clause you can then use the $select query option to specify the properties you want to include for the rows, and it’s even possible use the $filter query option if you’re only interested to receive rows that meet certain conditions.
Please notice that a filter within an expand clause only applies to that child (row) entity collection for each parent entity (e.g. the order rows for each order) – it doesn’t narrow down the parent entity result set (e.g. what orders that are returned).
E.g. $expand=rows($select=artnr;$filter=(antal1 le 10))
2.1.4 Ordering the result set - $orderby
In addition to the $select, $filter and $expand OData query options the API also supports ordering (ascending or descending) the result set via the $orderby query option.
A complete example with the above examples for selecting, filtering and expanding, including ordering by date would look like this:
/api/{company}/orders?$select=dokNr,fktTyp,datum1&$filter=landKod in(‘SE’,’NO’) and
startswith(namn, 'abc')&$expand=rows($select=artnr;$filter=(antal1 le 10))&$orderby=datum1
3 Data manipulation
3.1 Create/update data [HTTP POST/PUT]
When creating new or updating existing entities/records in Visma via the API you provide the entity
to create or update in the request body. Use the HTTP POST method to create and the HTTP PUT method to update.
Provide only the properties/fields you explicitly want to set and default values will be assigned to the rest according to Visma Administration business rules.
You are able to choose whether or not the resulting entity should be returned in the response.
3.2 Delete data [HTTP DELETE]
Deleting entities/records in Visma via the API is possible via the HTTP DELETE method.
Please note that all resources have the HTTP DELETE method, but some resources can’t be deleted due to Visma
Administration business rules. If you try to delete a record for a resource that can’t be deleted, you’ll get an error message telling you so.
3.3 Primary keys
When performing an update or delete operation (HTTP PUT/DELETE) the primary key property/properties must be set for each entity in the request body.
