How to get started
How can we become a Fivaldi API partner?
By becoming a Fivaldi Integration partner you will be able to provide your services to the customers of the most widely used accounting software in Finland. You will get access to the Fivaldi marketplace and an easy to use API for scalable business. Please contact us at fivaldi.integrations@visma.com and we will schedule a short kick-off meeting with you!
Where do I get general information regarding Fivaldi API?
Please read our general API documentation. For detailed information regarding API endpoints, please refer to Fivaldi API’s OpenAPI documentation.
What are the use cases Fivaldi API supports?
Examples of typical use cases are listed here but the list is not exhaustive. You can read more about the Visma Fivaldi API Resources that are currently available in this instructions folder. If you have any questions regarding your integration use case, please contact us at fivaldi.integrations@visma.com and we are happy to clarify whether your use case can be supported.
API credentials and authentication
Do I use the same Fivaldi API credentials for all customers or do I need separate API credentials for different customers?
Fivaldi API partner credentials (Kumppanikäyttäjätunnus) are created only once for API partners and you use the same Fivaldi partner credentials for all your customers.
Can I also use the API partner credentials to access the Fivaldi application via the user interface?
No. Fivaldi application/user interface requires separate user credentials which are valid only for the Fivaldi application (user interface). If you have requested for a test/sandbox company to be created by the Fivaldi API team, you should have received a Visma Fivaldi welcome email where there are instructions on how to create a password for your username (username is your email address).
Can I also use the UI credentials to access the Fivaldi API?
No. Fivaldi application/user interface credentials only work together with the Fivaldi application/user interface and Fivaldi API partner credentials are needed to access Fivaldi API.
I have small challenges to get started with authentication. Where could I get more information and do you have any sample code available?
Please read our help page Fivaldi API authentication for further details. We do have sample code available for following programming languages; Bash, C#, Go, Java, JavaScript (Node.js), PHP, Python, Ruby (Rails).
Just email us at fivaldi.integrations@visma.com and let us know which programming language you use. We will provide you with the sample code!
Testing and Rate limiting
Do you provide testing tools and/or test/sandbox company for API partners?
Yes. Here is a Postman collection that contains code for creating the correct authentication headers and an endpoint for testing it. Please remember to add your partner id and partner secret in the variables. Here is an example of how the id and secret can be added.
We can also provide you with a separate testing/sandbox company if required. Just email us at fivaldi.integrations@visma.com and we will create a test company for you as well as separate user credentials for the UI access.
Does Fivaldi API use API rate limiting?
Yes, it does. A rate limit is the number of API requests an integration partner can perform within a given time period. If this limit is exceeded, further API requests will be blocked. All API requests are subject to rate limits. Please note that the rate limit applies to your Fivaldi API partner id (ws-something) so all the API calls made with that partner id are counted/subject to rate limiting. You can read more about rate limiting here.
API endpoints for customers and companies
How do I differentiate between different customers when I use the same partner credentials for all of our end customers?
The Fivaldi API endpoint GET Customers returns to you all the Fivaldi customers who have granted you API access to any of their companies. A customer is a company who has purchased a Fivaldi license from Visma. Typically this is an accounting office, a real estate management company or any other company using Fivaldi. Use this call to retrieve all “main customer” details.
The second API call that you need to use is GET Companies which returns to you all the Fivaldi companies under the main customer. This is a company whose accounting or other process is handled in Fivaldi. For example, each customer of an accounting office is a “company” entity within Fivaldi. This is also where you get CUID’s and other information related to the companies that you can use to GET or POST data using any of the remaining API endpoints.
Please remember that the customer's admin has to grant API access rights for each company, otherwise you cannot access their data via API. Example instructions for admins can be found here.
Integration to Sales orders and Customer & Product registers
Do all Fivaldi customers have the same Fivaldi company invoicing details?
No, they do not. You should always use the API endpoint GET /companies/{cuid}/sales/company-invoicing-details to retrieve customer-specific information. This API call returns you values such as
- paymentTermDTOList
- deliveryMethodDTOList
- deliveryTermDTOList
- currencyDTOList
- salesPersonDTOList
- postingGroupDTOList
- unitDTOList, etc.
You must always use these customer specific id’s when posting a new sales order to Fivaldi. Please note that you have to use the “id’s” of the value, not the name of the value.
How about customer/supplier and product registers. Do all Fivaldi customers have the same register details?
No they do not. Similarly to Sales order invoicing details, you have to use the getProductRegisterBasicDetails and getCustomerRegisterBasicDetails endpoints to retrieve the correct register details and the values (id’s).
Can I POST multiple sales orders with one API call or do I need to post those individually?
You can POST multiple sales orders with the sales/multiple_sales_orders API endpoint. However, what you need to keep in mind is that if any of the sales orders in this batch contains non valid data or errors, then the whole batch will be rejected.
Can I GET information regarding the sales orders that have been posted to Fivaldi?
Yes, by using the GET sales-orders API call that returns you the sales order information. You can limit the query either by fromDate or status (Limit results with status DRAFT/INVOICED)
Can I GET information on whether the sales orders have been paid?
Not yet. The GET sales-orders API call only returns the status information DRAFT or INVOICED, but not yet the PAID status. This will be added to the Fivaldi API at a later stage, please follow our Change log for any changes/additions to our API endpoints.
Which system is the “master” when it comes to Customer & Product registers?
This is something that you as an integrator have to decide (together with your end customer). Fivaldi API supports both use cases.
If the external system (not Fivaldi) is the “master”, you have to create any new Customers and/or Products in the corresponding registers before posting a new sales order. Fivaldi will reject any Sales orders unless the related customer and/or product has been added to Fivaldi.
In the use case where Fivaldi is the master, then you can use the GET endpoints to retrieve all the data from Fivaldi registers to your system.
When POSTing data, what are the minimum and maximum field lengths and how do I know if the data is mandatory?
This information is documented in the Schema which can be found in the Swagger documentation separately for each endpoint.
Can I POST attachments to Sales orders?
Not yet. Support for attachments will be added later.
Can I POST dimension information to Sales orders products?
Yes you can. Please see our Sales order schema for more information (salesOrderRowDTOS > accountDimension1 - accountDimension4). Please use the endpoint get_companies__cuid__sales_company_invoicing_details to retrieve the correct, customer-specific accountDimension information and their id’s.
Can I POST free text information to Sales orders?
Yes you can. Please see our Sales order schema for more information. You have two options: You can POST rowFreeText that is related to the product (will be shown on sales order/invoice together with the product information), or you can post rowFreeText that is not related to any product by using the textRow boolean to determine if the row is a product row or a text row.
How do I POST product price?
You have two options.
- You can use unitPriceExcludingTax, in which case you input the single unit price without any taxes. Fivaldi will calculate the row total sum based on the posted sum, number of products on the row (quantity), discount percent (discountRate) and vat code. The used vat percent depends on the vat defined for the posting group (postingGroupId) that is selected for the customer (customerId).
- You can use totalSumIncludingTax, in which case you input the row total sum. Fivaldi will calculate the single unit price based on the posted sum, number of products on the row (quantity), discount percent (discountRate) and vat code. The used vat percent depends on the vat defined for the posting group (postingGroupId) that is selected for the customer (customerId).
Can I POST sales invoices that have already been sent to customers from our ERP?
No, not yet. Fivaldi API currently only supports Sales orders (which are open/uninvoiced invoices). Sales orders that are sent via API to Fivaldi must be invoiced from the Fivaldi UI. Invoicing via UI can be done easily for multiple orders by using “mass” invoicing from Fivaldi Sales management. See instructions for mass invoicing in Fivaldi (in Finnish).
Purchase invoices
What are the use cases Fivaldi API supports for purchase invoices?
There are several use cases where you can use the Purchase invoices API endpoints. These include, but are not limited to;
- Using GET calls to retrieve purchase invoice data to a Business Intelligence/reporting system, for example.
- Retrieving the purchase invoice data from Fivaldi and manipulating it in an external system (with AI or RPA), and posting the changed data back to Fivaldi.
- Posting new purchase invoices and their attachments to Fivaldi.
For detailed information, please refer to our Swagger documentation
Can I POST purchase invoices that have already been approved in our ERP and only need to be paid?
No, not yet. When posting a new purchase invoice, it will get the new/no approval chain defined (syötössä) status in Fivaldi, and it will have to be processed/approved in Fivaldi prior to payment.
Can I get information regarding the approval chain and/or persons who are in the approval chain?
No, not yet.
Can I get the purchase invoice attachment/s?
Yes, you can. When using the includeAttachments parameter for the GET purchases/invoices API call, it returns to you the attachment ids related to invoices. Then you can use the GET archive/files/{fileId} API call to retrieve the attachment/s.
VAT on purchase invoice rows
You can update VAT information on purchase invoice rows with three data elements, vatStatus, vatPercent and vatDeductionPercent.
The table below shows example values that are supported in Fivaldi, if the company uses the VAT specifications in the Liikekirjuri accounts. The Fivaldi vatStatus is based on the tax administration data file specification VAT (VSRALVKV) as shown in the table below.
vatStatusvatPercentFivaldi default descriptionTax admin IDDescription1024Myynti 24%301Tax on domestic sales at 24%2014Myynti 14%302Tax on domestic sales at 14%3010Myynti 10%303Tax on domestic sales at 10%350Ostot 0%307Tax deductible for the tax period10Ostot 10%14Ostot 14%24Ostot 24%400Myynti 0%309Sales taxable at zero VAT rate600EU-myynti 0%311Sales of goods to other EU countries700EU-palvelumyynti 0%312Sales of services to other EU countries800EU-ostot 0%313/305, 307Purchases of goods from other EU countries, deductible10EU-ostot 10%14EU-ostot 14%24EU-ostot 24%85
313/305Purchases of goods from other EU countries, non-deductible9024EU-palveluostot 24%314/306, 307Purchases of services from other EU countries, deductible95
314/306Purchases of services from other EU countries, non-deductible100
301/307Purchases of services, reverse charge mechanism, deductible105
301Purchases of services, reverse charge mechanism, non-deductible110
319Sales of construction services, reverse charge mechanism11524Rak.palv. vähennyskelpoiset ostot 24% 320/318, 307Purchases of construction services, reverse charge mechanism, deductible120
320/318Purchases of construction services, reverse charge mechanism, non-deductible13010Maahantuonti EU ulkop A2% 10%304/310Imports of goods from outside the EU14Maahantuonti EU ulkop A1% 14%24Maahantuonti EU ulkop Y% 24%
0Osto EI verokäsittelyä 0%
Bookkeeping
When to use vatType AUTO / CALCULATED
The AUTO parameter will calculate VAT based on the bookkeeping account, however this requires individual bookkeeping accounts for every VAT percent/vatCode.
When using the CALCULATED parameter, Fivaldi will not perform any VAT calculation. VAT must be pre-calculated and sent to Fivaldi with the correct vatCode, vatAmount and account(s).
VatCodes in detail
These parameters should be used with the CALCULATED parameter.
- vatId: internal id in Fivaldi
- vatAccount1: receivable/deductible account
- vatAccount2: receivable/deductible account, only used with reverse VAT charge
- vatPercentageCode: VAT percentage code valid at the time
- percentage: VAT percentage valid at the time
- deductionPercentage: only used if not 100%
- description: VAT code definition
- startDate: VAT percentage´s start date
Real Estate
We want to send consumption readings to the Fivaldi meter register. Do we send “meter reading” or “consumption reading”?
Both are supported and it depends on how the end customer has set up their Fivaldi meter register. Please use the API endpoint GET /companies/{cuid}/estate-meter/meters to get the list of the meters. The saveType field gives you the information whether to use METER or CONSUMPTION (Tallennustapa. METER = Mittarin lukema, CONSUMPTION = Kulutus) when posting data.
Pricing
What is the cost for us (development partner) when we start using Fivaldi API?
We grant you access to Fivaldi API free of charge. We also support you during the development phase without additional charges.
Are there any costs for the end customers when they start using our integration that uses Fivaldi API?
Yes there are. The API fee per ISV solution can vary depending on which API endpoints are used (coverage of the integration). The use of API will be charged by Visma from the Fivaldi main Customer (typically Accounting office) and it is transactions-based, monthly billing (based on the data that has been accessed during the calendar month).
Marketing
We would like to create a “productized” integration that can be used by different end customers. Do you offer any marketing visibility for us as an integration partner?
Yes we do. Visma Fivaldi has a built-in Marketplace that is visible for all existing Fivaldi customers and users. For new/potential customers, we have our public web page where we list all integration partners. We are happy to list your integration on the Fivaldi Marketplace as well as on our public web pages.
General
As a Fivaldi customer, how do I enable integration for the integration partner?
Integration for a 3rd party integrator can be enabled by the Fivaldi Customer's administrator. The admin users can follow our instructions. After the admin has opened the API access for the 3rd party, the integrator will immediately have access to the company data (based on the opened API endpoints).
Oliko tästä vastauksesta apua? Kyllä Ei
Send feedback