Vero API — overview

Vero API services — recommendations for developers 

• Integration to Vero API services requires using a client certificate. Authentication method is client certificate authentication which means that the client certificate is verified during SSL handshake. Caller’s private key and certificate are verified during the handshake. Tax Administration cannot give detailed instructions on how to attach the certificate to a service call because it is done based what technology solutions user's application is using. Further details can be found with popular search engines with keywords “client certificate authentication”. 
• When building integration with Vero API services you must test most common use cases in Vero API test environment using a test certificate. Typical use cases include reacting appropriately to response status codes received from service when sent message was valid and when message contained input errors or business validations failed. Also, the client software should handle unexpected errors or service down time gracefully.   
• Software that is calling Vero API services should include all input validations like data format validations and other logical validations that are described in the service documentation in API portal. This helps to ensure quality of data before it is sent to the service and unnecessary errors are avoided early. Examples of input format validations include input length, customer id formatting, date formatting, required fields, allowed date ranges (date cannot be in the past or in the future). 
• The Tax Administration monitors service usage and errors. The Tax Administration may contact software developers or end users to clear up errors. For this purpose, it is the responsibility of software developers to have their contact information updated. You can submit a new testing start up form with updated information when necessary. End user and holder of the production certificate is responsible to keep contact information updated in the Incomes register e-service.  
• Access to the API services can be blocked or limited by the Tax Administration in the event of overload situations, suspected abuse, or denial-of-service attack. 
• Services prevent intended or unintended overload situations and denial-of-service attacks by limiting incoming traffic volume. We recommend that applications make max 50 - 125 simultaneous calls.  
  • Applications calling services should be prepared to handle heavy load scenarios when services respond with status codes 429 – too many requests or 403 –  forbidden. In these heavy load scenarios, your software must reduce number of simultaneous calls or try calling again at another time.  
• Vero API services are not available 24/7/365 and services have regular downtimes due to maintenance. Your software must be able to handle the downtime, store the user’s data-entry records temporarily and call again when downtime is over.  
   
  Information on maintenance downtime: Maintenance breaks and disruptions - vero.fi.

Technical policies

Endpoint versioning 

• Versioning is done for endpoints or for API products when necessary. Versioning is based on sequential number at the end of endpoint address with letter "v", for example https://api.vero.fi/Customer/IDs/ValidateTaxNumber/v3  
• Version numbering begins at 1 and whenever a new breaking change is introduced, the version number is increased. A breaking change is for example such where fields have been removed or data types have been changed in a message. Breaking change usually means that users of the service must change their integrations with the service. Please note that adding new optional fields to a message is not considered to be a breaking change.  
• The Tax Administration usually supports no more than 2 different versions of one interface: the current version and the version. We expect all users of the previous version to begin using the latest version within the transition period specified for each version change. The documentation appearing in the API portal contains information about new versions.  

The structure of endpoint addresses 

The general structure of the Tax Administration’s functional systems is reflected in the structure of endpoint addresses. Addresses are in English, and they consist of the following parts in the production environment:  

• Vero API domain: api.vero.fi/  
• Category: Customer/  
• API product name or sub-category: IDs/  
• Name of the service: ValidateTaxNumber/  
• Version: v1 

Addresses of test environment endpoints may have additional identifiers to indicate both the environment and that it is a test endpoint, for example:  

• Vero API test domain: pintatesti.vero.fi/  
• Test environment ID: FIS/  
• Category: Customer/  
• API product name or sub-category: IDs/  
• Identifier of the test endpoint: Test/  
• Name of the service: ValidateTaxNumber/  
• Version: v1

For a list of current addresses, see the API portal.  

Information in the Header  

It is necessary for Vero API users to insert their software application’s unique identifier into a “vero-softwareid” header. We recommend using the Business ID of the company that has developed the software and adding the unique identifier or a description to it.  If necessary, the Tax Administration can use the identifier in order to contact the software developer later.  

Service parameters  

There are many data items that relate to individuals’ personal data in the service calls and data-entry inputs that the interfaces work with. Typically, the significant parameter is the personal identity code. No interface parameters are included in the addresses of the calls (as URL parameters) because as such, they could stay stored for a long time in the log data of various servers, and they could expose personal data. Services that use this type of data will use a POST method and include the personally identifiable information in the request body only. 

Information about data types  

In general, message structures are based on JSON format where the usual JSON data types are in use:  

• string  
• number  
• Boolean  
• null/empty  
• object  
• array

Files are transferred in JSON message as base64 encoded or separately as type application/binary. JSON messages has to be UTF-8 encoded.  

Dates and timestamps  

The date format is in accordance with the ISO 8601 standard, yyyy-MM-dd. Timestamps must indicate milliseconds and the relevant time zone.  Example: 2022-02-25 is the date, and the timestamp is 2022-02-25T14:59:43.397+02:00.  When a timestamp is generated in another time zone, the Tax Administration’s system converts the time into local Finnish time.  

Http status codes  

• Users receive standard http status codes. Only the “200 OK” message code from the service will indicate that the service call was successful. Typical response values from services are a unique identifier and timestamp, which together serve as an acknowledge-of-receipt message from the Tax Administration. If http status code is something else than 200 then response usually contains detailed error message as JSON structure.  
• Other http response codes such as 400 and 500 mean that the inbound call was not accepted, or cannot be answered, for example: “bad request” plus a JSON message containing an error code and the error code’s description or label. Typical errors include structural validation errors, input validation errors, insufficient authorisation, overload, or a downtime situation.   
• If the user’s “production” certificate had been obtained the same day when an attempted service call is made, it may be that the interface only returns the “http 500” error until the certificate is properly uploaded in the production environment of Vero API. Vero API services respond to calls made with production certificates only after the certificate has been fully installed in our environment. Certificates for Vero API are retrieved from the Incomes Register's certificate service. In general, production certificates generated in the certificate service during office hours (8.00 am to 4.15 pm) will work in Vero API calls at the latest on the following day.