Scam messages have been sent out in the Tax Administration’s name. Read more about scams.

Technical guidance for ApitamoPKI

Login and authorisations

For authentication, ApitamoPKI relies on the certificates included in the Tax Administration’s certificate-based authentication service. The certificate is only for the sending party’s authentication (client certificate authentication), and the submitted reports are not digitally signed. ApitamoPKI does not add a signature to the response messages or answer files.

ApitamoPKI accepts logins with the data providers’ certificates issued by the certificate service (the issuer is Data Providers Issuing CA and for test purposes, it is Test Data Providers Issuing CA) and intended for use in the Web Services channel (either with a delay or in real time).

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. However, the certificates intended for the SFTP channel of the Incomes Register (the issuer is Vero Data Providers SFTP Issuing CA) cannot be used with ApitamoPKI.

Certificates both for testing and for production have a 2-year period of validity. Users cannot log in with outdated certificates or with certificates that have been blacklisted.

For more information, see the Stage 1: Test and develop and Stage 2: Moving to production -pages.

ApitamoPKI does not require that the user has a Suomi.fi e-authorization for handling the tax affairs of another party. When it has been so agreed between the parties involved, users of certificate-based authentication can submit reports, tax returns, etc. belonging to other organisations than the one for which the certificate had been issued. The Suomi.fi e-authorization requirement is only maintained in some circumstances. An example of an information flow that can only be sent with the Suomi.fi e-authorization is VSTULLER, the report concerning value-added tax on imports. For more information on authorisations required for various reports and flows, click here.  

Description of ApitamoPKI 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 ApitamoPKI technical description 1.4 (pdf)

The URL’s for accessing the test environment of ApitamoPKI:

For support, send e-mail to tamo.tk(at)vero.fi.

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 (several megabytes, or even larger) or if you have other reasons 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 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:

  1. 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 select the desired reporting function as appropriate. Alternatively, the send process may be fully automatic, requiring no action on the user’s part.
  2. The system sends a call to ApitamoPKI and sends the certificate on to ApitamoPKI.
  3. When ApitamoPKI has checked the certificate and performed a format check on the tax return, your system will receive an acknowledgement of receipt.
  4. At this stage, your system should show the received response and acknowledgement on the screen.
  5. Finally, your submittal is transferred (not in real time) to the Tax Administration's operations system for processing.

Picking up files i.e. retrieving the answers (RetrievalOperation)

If an answer file is expected from the Tax Administration (such as tax-card information containing workers’ withholding rates), a RetrievalOperation must be run in order to retrieve the answer file. The same applies to 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 for them, too, when their check results need to be retrieved.

To retrieve any files, you must use the ID that you received 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.

ApitamoPKIClient

We have developed an “ApitamoPKIClient” model for your reference, 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.

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 answers and responses.

If you find that ApitamoPKIClient is not suited for your specific needs, you can generate a better version based on the WSDL description of ApitamoPKI. 

ApiTamoPKIClient uses the MIT-license, and the services provided by third parties that are related to this are controlled by terms and conditions of the license that the providers indicate, in reference to the libraries of the respective third-party service.

 

Go back to the ApitamoPKI page

 

Page last updated 9/2/2020