Software registration and acceptance procedure
The goal of software registration is to improve the user experience of interfaces and the quality of integrations through a standardized implementation procedure and targeted guidance.
Software developer registration
One or more developers from a software developing organization can register to the API portal. You can register to the portal with your email address and chosen password. The portal does not use Suomi.fi authentication and the organizational information provided by the developer is not verified. The portal only processes software information provided by the developers.
In the API portal, developers belong to teams of developers to which they can invite other developers with an email address. The purpose of the team structure is to reduce the challenges of maintaining the software information due to personnel changes, among other things. All developers can create teams and manage their members themselves. Developers have the same level of access with each other, this must be considered when inviting new members.
Software registration
The software is registered in the API portal under the developer team responsible for the development of the software. The name, brief description of the use case, administrator and contact information are provided for the software.
After registration, the interfaces used by the software are selected, so that the software-specific API key can be used to access the selected interfaces.
It is the software developer's responsibility to maintain information about the software, such as interface usage data.
The Tax Administration monitors the interface usage of software and can remove unused software from the API portal. The contact person of the software will be notified.
API key
- The API key can be seen in the API portal in the software information and more keys can be created if necessary. The API key is meant to be built inside the software, not to be managed by users.
- As a rule, one software has one API key. The key is not the main access control mechanism to the Tax Administration's interfaces.
- The API key is intended to be known only by the organization that developed the software.
- The software-specific API key is placed in the vero-softwarekey header and must be in each interface call. This is documented in the API portal in the description of each interface.
- The API key is required in test environments, but its content is not checked and it does not limit access to certain interfaces
Acceptance procedure for software’s production use
Starting from 20.11.2023 the production use of the Vero API interfaces requires an acceptance testing for the software applications. The acceptance testing is done as a self-service in the API portal. The user must have a production certificate. The acceptance testing process will involve the introduction of interface-specific test scenarios in the API portal, with the objective of ensuring high quality integration, reducing errors in the use of interfaces and clarifying the interface production deployment process.
The interface-specific test scenarios are executed by calling the interface’s verification endpoint with the message content described in the scenario. For each interface there is at least one basic scenario which must be passed. In the basic scenario the application must pass all the interface’s business rules, parameter validations and error validations. For some interfaces there might also be multiple test scenarios. In that case the user must pass every test scenario to gain production access. After the testing has been completed successfully the production access is granted automatically for the application.
Please note about the production access:
- All applications which have been registered after 20.11.2023 must execute the acceptance testing for all the integrated interfaces.
- The acceptance testing does not include the applications which have been registered before 20.11.2023 and the interfaces which have already been used in production. These applications can continue using the interfaces without any outages.
- The acceptance testing must be executed every time the user adds new interface integrations for the application in the portal. This procedure includes all the registered applications. For example: A registered application is currently using the withholding percentage request interface. After 20.11.2023, the household expenses reporting interface is added to the application. The acceptance testing must be executed for the household expenses reporting interface.
- For the existing applications it is also recommended to execute the test scenarios. Production access is not revoked for an existing interface even if the test scenarios are not passed initially.
- The test scenarios can be re-tested after the production access has been granted once. This can be used, for example, to test a new version of the application in the API portal.
- The API portal user doesn’t have to contact the Tax administration about the testing procedure. In case of any issues regarding the testing or any errors in the portal, the observation form can be used to contact the FTA.
Clarifying instructions for executing test scenarios:
- Interface addresses used in test scenarios (URL Integration verification) can be found on the Vero API portal.
- Service calls done to the verification address are not processed in the tax system and the responses are the same static responses as the responses in the lower test environments.
- Test scenario can be executed with just one successful call with valid data content, to which the verification interface responds with HTTP 200 return code.
- Integration verification endpoint is not meant for any functional testing, integration verification is for integration acceptance of completed application.