Software registration and API key
Developers must register their software that uses the Vero API interfaces in the Tax Administration's API portal as of 18.1.2023. As of 1.6.2023, a software-specific API key will be required in production in addition to a user-specific certificate and in test environment calls from 18.1.2023.
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
Integration verification
The purpose is to ensure the technical functionality of the production connection and the API key against the interfaces used by the software. If the software starts to use new interfaces, they must be updated to the Vero API portal.
Before starting production use of the software, it is possible for the software developer to verify the functionality of the integration with Vero APIs by using a software-specific API key and the software developer's own production certificate as of 18.1.2023.
- The technical functionality of the production connection and the API key is ensured by calling each interface used by the software with the test data found in the Vero API portal
- The endpoint addresses used for verification (URL Integration Verification) can be found in 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.
- Verification is done to the software only once per interface
- After verification, the interface can be taken into production use
- It is not necessary to contact the Tax Administration separately once the production connection and the technical functionality of the API key have been ensured
- To verify that integration is working properly, it is typically enough to call the integration verification endpoint successfully once with valid request message content so that the endpoint responds with HTTP 200 OK code
- Integration verification endpoint is not meant for any functional testing, integration verification is for integration acceptance of completed application