General remarks about the changes
During 2020, we will withdraw logins based on Katso ID and password in the Web Service interface of Ilmoitin.fi. Logging in will be replaced by a Tax Administration-issued certificate.
This makes for significant changes to message structures because the WS Security and SAML2 structures will be withdrawn.
There will also be a simpler authorisation process: new authorisations are similar to those in the Incomes Register. A specific Suomi.fi authorisation will only be required in a small number of submitted reports (an example is the VSTULLER information flow).
The currently used Apitamo will work parallel with ApitamoPKI for as long as logging in through Katso is available to users. However, it may be that the current Apitamo is phased out before that if all the users have adopted the new routines.
User identification with an ApitamoPKI certificate
ApitamoPKI accepts logins with the certificates of the data providers issued by the certificate service, intended for use in the Web Services channel (either with a delay, or in real time) (the issuer is Data Providers Issuing CA and for test purposes, it is Test Data Providers Issuing CA). However, the certificates intended for the SFTP channel of the Incomes Register (the issuer is Vero Data Providers SFTP Issuing CA) are not accepted by ApitamoPKI.
If the user has acquired a certificate already, either for Incomes Register purposes or for Vero API, no new certificate is necessary.
The certificate is used for identification of the sending party only (client certificate authentication), and the submitted reports are not digitally signed. ApitamoPKI does not sign the response messages or answer files.
When you are in the test environment, only the certificates for testing are accepted by ApitamoPKI, and correspondingly, when you are in the production environment, you must use “production” certificates. Read more about applying for a test certificate on Certificate service.
Certificates both for testing and for production have a 2-year period of validity. If the period of validity is over, the certificate is obsolete and you can no longer use it. The same goes for certificates that are revoked (i.e. on a blacklist).
Description of the ApitamoPKI setup and its services
The interface is comprised of two SOAP services described in WSDL:
- sending files i.e. SendOperation (SOAPAction: SendAction)
- picking up files i.e. retrieving the answers, RetrievalOperation (SOAPAction: RetrievalAction)
You must send the files containing tax returns and enclosures to income tax returns as MTOM enclosures (Message Transmission Optimization Mechanism). Correspondingly, the system will send answer files and results of checks as MTOM as well.
Use the ISO-8859-1 character set, the one specified in the Finnish Tax Administration's descriptions. Files in the XML format use the UTF-8 character set.
For descriptions of message structures, see the technical description of the ApitamoPKI interface.
How to send files (SendOperation)
To send a filing, use SendOperation. SendOperation is also in use for enclosures to income tax returns (such as the balance sheet and profit-and-loss account).
All the filings and enclosures to income tax returns are MTOM attachments in the request message.
If the size is large (with several megabytes of file size) or if you have another reason to submit the file to background processing instead of real time, your request file must contain BackgroundProcessing = true. Then the response will contain an ID – ResultId – that you can use for retrieval. If you expect to have an answer file for the file that you submit, the response message will contain the ID for retrieving the answer in the RetrievalId element instead.
Description of the send process
The following is a general description of how to submit a return:
- You are the end user, and you must first log in to the software/service (the 'system') with the identification method used by the system.
- Then you select the desired reporting function.
- The system sends a call to ApitamoPKI and sends the certificate on to ApitamoPKI.
- When ApitamoPKI has checked the certificate and performed a format check on the tax return, your system will receive an acknowledgement of receipt.
- At this stage, your system should show the received response and acknowledgement on the screen.
- Your submittal is transferred (not in real time) to the Tax Administration's operations system for processing.
Alternatively, the above process may be fully automatic, requiring no action on the end user’s part.
Picking up files i.e. retrieving the answers (RetrievalOperation)
If an answer file is expected from the Tax Administration (such as tax card information, or tax numbers for construction workers), a RetrievalOperation must be run in order to retrieve the answer file. The same applies for large submittals of files (with file sizes reaching several megabytes) that go to background processing due to the large size (BackgroundProcessing=true). The RetrievalOperation must be run also for them when their check results need to be retrieved.
To retrieve any files, you must use the ID that you receive from ApitamoPKI when it answered your initial SendOperation as above.
If the answer file or other result is ready, the RetrievalOperation will return “Ok” as the status code, and the files are available for retrieval as MTOM attachments.
If the system has not yet made your answer file or other result ready, the RetrievalOperation will return “Wait” as the status code.
We have developed an "ApitamoPKIClient" model for your reference, in order to assist you with software integration work. The model is Java based and it not only contains the source code but also a small interface and a binary version you can run. It saves the SOAP messages in a log file, as well.
The purpose of ApitamoPKIClient is to render assistance to the users of the application to implement the functionalities that are necessary for sending.
With the help of the ApitamopkiClient application, users can submit software-generated files conforming to the Tax Administration’s data record specifications, and retrieve any related answers or responses.
If you find that ApitamoPKIClient is not suited for your specific need, you can generate a better version based on the WSDL description of ApitamoPKI.
Links for downloading the ApitamoPKIClient
The test environment and the production environment
The URL’s for accessing the test environment of ApitamoPKI:
- the service: https://apitesti.ilmoitin.fi/wsapp/apitamopki
- the WSDL: https://apitesti.ilmoitin.fi/wsapp/apitamopki?wsdl
After successful testing, the URL addresses for the production environment of ApitamoPKI will be available at tamo.tk(at)vero.fi.
For support, send e-mail to the usual support address tamo.tk(at)vero.fi also if you need support for ApitamoPKI.