Income Register's technical interface
The technical interface means the integration built between the different systems. As an example, an electronic connection is built between payroll software and the Incomes Register, allowing data to be transferred between the two applications.
Send data to the Incomes Register directly from the payroll system
The technical interface allows the sending of earnings payment data directly from the payroll system to the Incomes Register, without the user having to open a separate Incomes Register reporting service. When the data is transferred to the Incomes Register via the technical interface, the number of manual steps involved in the reporting of earnings payment data is reduced. The technical interface allows the payroll officer to use the same system for both payroll calculations and the reporting of data.
Separate user identification is not required for reporting
Data providers do not need to separately sign into the service and personally identify themselves, because agreements have already been made during the opening of the service. Reporting will become quicker and the related tasks easier.
A certificate generated by the Incomes Register's certificate service is issued to either the company itself, or an accounting office or other payroll administration partner doing business on its behalf. A certificate is issued to a company, if the company reports the earnings payment data itself via the technical interface. If an accounting office or other payroll administration partner is issued with a certificate, it commits to reporting data only on behalf of those customers with which it has entered into a mutual agency agreement.
When the technical interface certificate is used, there is no need to separately authenticate each different employee.
Report automatically via the interface
Today, reporting involves several manual steps: preparing the reports, signing into the reporting service, uploading the file to the service and submitting the file. The technical interface allows the reporting to be automated. Data entered into a payroll administration system can be automatically transferred to the Incomes Register via the technical interface, reducing the number of manual steps required.
The interface requires an application for a certificate
Organisations using the Incomes Register's technical interfaces are identified by using the Incomes Register's certificate service. The solution is based on digital certificates (Public Key Infrastructure).
All organisations providing data to and retrieving data from the Incomes Register use the certificate service. A certificate is issued to an organisation that is responsible for delivering data to the Incomes Register, or that has the right to receive data from the Incomes Register. The Incomes Register's certificate service issues the certificates. The certificate is used to identify the organisation providing or using the data and to ensure the integrity of the records. Certificates are issued in accordance with the purpose of use.
Once the organisation has agreed with the Incomes Register on the use of the technical interface, the certificate can be applied for and processed. The certificate service will send a transfer ID and a one-time password to the customer. After receiving these, the customer can make a certificate request. In the acknowledgement of receipt, the certificate request service call to the certificate service returns a retrieval ID that uniquely identifies the certificate being generated for retrieval. The certificate is obtained as a response to a certificate retrieval service call to which the retrieval ID has been attached. The customer now has the certificate required to use the services of the Incomes Register.
Read more in the general description of the Certificate Service.
Three kinds of technical interfaces can be built into the Incomes Register:
1. Real-time Web Service interface
2. Deferred Web Service interface
3. SFTP interface
Real-time Web Service interface: few reports, immediate response
Real-time services can be used when integrating a payroll system directly with the services of the Incomes Register. The real-time WS interface is intended for use in situations in which only a small number of reports are submitted to the Incomes Register. When using the interface, the reporter receives an immediate acknowledgement of the report having been received by the Incomes Register. Only one report at a time can be submitted via the real-time WS interface.
If a large quantity of earnings payment reports is generated when running the payroll, the reports must be submitted to the Incomes Register via either the deferred Web Service interface or the SFTP interface.
Deferred Web Service interface: a large number of reports
The deferred Web Service interface is recommended when the data provider submits a large number of reports at a time to the Incomes Register. The data provider sends the record to the Incomes Register's technical interface using a WS service request. The Incomes Register sends a synchronous acknowledgement of receipt of the service request. The acknowledgement of receipt contains an itemised list of any errors detected upon receiving the service request. The Incomes Register processes the record.
The data provider sends a request for the processing feedback to the Incomes Register's technical interface, to which the Incomes Register responds by sending the processing feedback. If the Incomes Register has already processed the record, the processing feedback will contain information on the correct and incorrect data in the record, as well as an itemised list of any errors detected during processing. If the Incomes Register has not yet processed the record, the processing feedback will state that the processing of the record is still ongoing. In such a case, the data provider will have to resend the request for processing feedback after some time has passed. The size of the record that was sent, for example, affects the processing time. The Incomes Register processes the records in their order of arrival. If the size of the record exceeds 50 MB, it must be divided into separate records prior to submission.
SFTP interface: a large number of reports
Similar to the WS interface, the SFTP interface supports the submitting of large numbers of reports at a time. The data provider creates a record file and submits it to the Incomes Register. The Incomes Register receives the record file and processes the data contained in the file. Once the record has been processed by the Incomes Register, the data provider receives a feedback file containing the processing feedback for retrieval via the SFTP interface. The record processing delay in the Incomes Register should be taken into account when deciding the time of retrieval. The data provider should be prepared for the possibility that if the feedback file has not been completed by the retrieval time, retrieval will have to be re-attempted after some time has passed. The Incomes Register processes the records in their order of arrival, and the processing time is affected by the size of the submitted record, for example. If the size of the record exceeds 50 MB, it must be divided into separate records prior to submission.
The SFTP interface is recommended when the payroll run generates large amounts of data at a time and the data provider does not have the possibility of using the WS interface.