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:

The following list contains only those headers that are specific to FTA operations:

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:

  • Use the format emitted by Date's toJSONJavaScript method:

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.

HTTP status codes and errors
Code Meaning Methods
200 OK - this is the standard success response. <all>

Client Side Error Codes

Client Side Error Codes
Code Meaning Methods

400

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.