Vero API overview
General information
This is a general overview for Vero APIs. API definitions are located at Vero API developer portal https://avoinomavero.vero.fi/APIPortal/. Vero API developer portal contains each API specification.
For technical support contact ohjelmistotalot(at)vero.fi
Terminology
- API = Application Programming Interface
- URL = Uniform Resource Locator
- FTA = Finnish Tax Administration
- Developer = The software company that has the testing certificate, for example third party external developer.
- End user = The company that has the production certificate, for example tax accountant.
- End customer = The taxpayer
- Certificate = Public key of the certificate
- PKI = Public Key Infrastructure
Vero API development standards
API Versioning
Versioning of API endpoints is a sequential number. FTA will version API endpoints by adding the version to the end of the URL. URLs will show the version number with the character 'v' and one integer, example https://api.vero.fi/Customer/IDs/ValidateTaxNumber/v3
The version number count will start at 1 and be increased when a breaking change is made. A breaking change is a change that modifies the API in a way that requires a developer to change their application. For example, changing the data type of a given attribute within a response. Note that adding fields to a response is not a breaking change.
FTA will be supporting two API versions, the current version and one previous version. Exceptions can be made based on usage of the API.
When a version is deprecated, after 6 months it is marked as obsolete in the API catalog and the endpoint ceases to function. Obsolete dates and the introduction of new versions will be documented in the developer portal.
URL structure
Rest API URLs are resource oriented, like "GET" resource or "POST" resource:
Example, POST RealEstateReturn.
FTA API service URL Structure Standards:
- URLs will mirror the current FTA structure of system functional areas.
- English language is used in URLs. Including function names and categories.
- URL structure consists of common base URL and unique path to describe each API.
- Common base URL consists of following parts:
- Vero API domain api.vero.fi/
- Category customer/
- Subcategory IDs/
- Optional test end point test/
- Function name ValidateTaxNumber/
- Version number v1/
- Categories are determined by functional areas of FTA like customer, returns or payments. There may be multiple levels of categories like Registration/IDs.
- Example of API URL:
POST https://api.vero.fi/Customer/IDs/ValidateTaxNumber/v1
Headers
Headers use standard HTTP headers and specific FTA headers. FTA specific headers have a prefix of "vero-".
Standard request headers can be viewed at Microsoft's document:
- https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#75-standard-request-headers
- https://tools.ietf.org/html/rfc7235#section-4.2
The following list contains only those headers that are specific to FTA operations:
Header | Type | Description |
---|---|---|
vero-softwareid |
string |
Free text to identify the software developer and their software. Usually a business id of the software developer company and underscore + two digits. Used in contacting the developer if problems occur. |
Parameters
Personally identifiable information such as personal ids, business ids, tax numbers, etc. will not be transmitted as query parameters in URLs. Services that use this type of data will use a POST method and include the personally identifiable information in the request body.
Data types
APIs will use common JSON data types:
- string
- number
- Boolean
- null/empty
- object
- array
Dates & Timestamps
Dates are transferred in strings and encoded in following way:
2012-04-23T18:25:43.511Z
- When only the date is needed, the format is yyyy-MM-dd (use leading zeroes).
Example: 2010-04-20
Reasons to use the format:
- It's human readable but also succinct
- It sorts correctly
- It includes fractional seconds, which can help re-establish chronology
- It conforms to ISO 8601
- ISO 8601 has been well-established internationally for more than a decade
- ISO 8601 is endorsed by W3C, RFC3339, and XKCD
HTTP status codes and errors
HTTP codes are standard HTTP status codes. API specific codes are defined in the API specifications on the developer portal.
Code | Meaning | Methods |
---|---|---|
200 | OK - this is the standard success response. | <all> |
Client Side Error Codes
Code | Meaning | Methods |
---|---|---|
Bad request - generic / unknown error. This error will be delivered in case of input payload fails business logic validation. Response includes error structure for error details. |
<all> |
Standard responses
The primary response body format is json. Other formats will be used as needed per service. FTA will support json, xml and others when needed. Service specific error messages are documented with the API to which they apply in the development portal.
Getting access to the development endpoint
Example: How you can call our ValidateTaxNumber API
When you are in that point that you have access to the developer endpoint, here is example how you can call our ValidateTaxNumber API with a standard tool like curl. Curl is available on all platforms.
Example how you can validate access to the API with curl.
curl.exe -k -w "\n%{time_total};%{time_namelookup};%{time_connect};%{time_appconnect};%{time_starttransfer};%{http_code};%{url_effective}" --cert svapidp-ok.crt --key svapidp-ok.keyn--request POST --data "{\"TaxNumber\":\"200000000001\"}" --header "Content-Type: application/json" --header "Vero-SoftwareId:12345678_00 " -s https://pintatesti.vero.fi/FIS/Customer/IDs/Test/ValidateTaxNumber/v1
Before you use this call, please replace red texts as told here:
- svapidp-ok.crt = replace this with your own public key
- svapidp-ok.keyn = replace this with your own private key
- 200000000001 = this is test tax number you can use
- 12345678_00 = your business id and make sure there is also this _00
If you replace the cert & key with your own, you should get the same result as we get here. It also documents what is needed in the header.
API Service Availability
Test endpoint of APIs are available through test URLs. Test endpoints are available during business hours 08.00 – 16.00. During other times there might be planned service outages. Test environment is not available on Sundays.
Production endpoints are available almost 24/7. There are daily service restarts on business days at 17.00 - 18.00 and 21.00 on weekends and regular maintenance breaks on every third Sunday of each month.