Notification Service

Purpose of the service

The Notification Service is an additional service designed to enhance the use of other Vero API interfaces. The service allows user to subscribe and receive different notification types from the Tax Administration. Notification is a simple message that tells you that something taxation-related has happened for a customer. For example, a tax event has occurred for the customer selected in the subscription and a notification is generated based on it. The notification is an indicator that the user of the Vero API interfaces must respond to it.

The notification contains the notification type and the key information to retrieve the actual data content associated with the notification. The user must then select the appropriate interface to retrieve the data. Notifications are stateless and it is the responsibility of the software using the Notification Service to keep track of which notifications have already been processed and how to respond to the received notifications.

The current version of the service

The notification service is designed to be multi-purposed service and it can be extended with new notification types for different use cases. The current version of the notification service was released to customer use in 2022 and the first use case was the Excise tax’s EMCS-system and the transactions related to it.

The notification service is planned to be extended for other use cases, such as: Withholding percentage inquiry, letter related interfaces and tax period inquiry. The extensions are developed and released during the year 2024. Users of the Notification Service and the Vero API interfaces will be able make subscriptions and receive notifications for these new use cases as well once the extensions are implemented as part of the service.

In the first version of the service, push-typed JSON calls are not supported. Only inquiry type of calls is supported. This means that the user must regularly poll for notifications with the ListNotifications interface.

By retrieving the latest notifications, the software does not need to request the information of all target customers continuously with individual calls, but only when the target customer's information has changed based on the notifications.

Push notification service

The push notification service is a new additional service for the current version. The push notification service is planned to be released for customer use during the spring 2024.

In the push notification service new notifications are sent for the users almost in real-time using Push-typed JSON calls.
The user doesn’t have to poll for the latest notifications by using the ListNotifications interface continuously.
In the push notification service the user makes a subscription in order to receive different notifications types and registers the used software in to the push notification service. In the registration, the user must submit their subscription identification number (SubscriptionID), the URL-endpoint of the software (CallBackURL) to which the notifications are sent to and a chosen secret (CallBackSecret) which will be used as authentication method, when the push notifications are sent for the customer. The call back secret is chosen and defined by the customer and it’s purpose is to authenticate that the push notifications are sent from the Tax administration only.

The Benefits of the service for the user

The notification service can be used to speed up the data retrieval processes, because there is no need to make Vero API interface calls for each customer continuously, but only for those customers whose data has changed.
Usage of resources are diminished in both customer’s and in Tax administration’s systems, because the number of calls is lower. Information is submitted or requested only when it’s necessary.
Network traffic is diminished which results saving of costs for the software using the service. The software requires less server capacity and resources. In addition: the costs of cloud-based software might diminish, because the usage of the interfaces is managed better and number of unnecessary calls are lower. Use of cloud service is enhanced when the need for resource usage in interface calls is lesser.
The speed up in process times. The user’s software no longer requires large batch jobs -process to send large mass of calls, as they might have done earlier. This will speed up the usage of the software and the data retrieval processes of the correct information. Enhancing process times is also dependable of the user’s software development solutions.
The network load for the Vero API services is diminished. The use of the Notification Service will also improve the overall load on the Vero API services, which makes submitting and retrieving of data via the interfaces more efficient. Reducing the network load will also reduce delays in calls response times, and calls will reach the Tax Administration's system and the user's own software more quickly.
Push notifications are well suited for real-time use cases where an immediate indication is needed for a change in information, e.g. EMCS export approval.
- Customer system data can be maintained in real-time with Tax Administration data without lengthy batch processes outside of office hours.

Examples of use cases

Tax card inquiry: a user has made a subscription to receive notifications about new tax cards. The user is a payroll office or an accounting office that is using the withholding percentage inquiry API interface. A new tax card is created in the Tax Administration’s system or in MyTax for the customer associated with the subscription (employee). The selected notification type is salary and based on that notification type and the new tax card, a notification is created in the Tax system. The notification is retrieved with the ListNotifications interface or sent to the user via the Push Notification service. Based on the notification, the user can react and retrieve the new tax card information for the payroll using the withholding percentage inquiry API. The user does not need to request the changed tax card information continuously, for example daily for all their employees, but only when the tax card information has changed for certain customers. The customer (employee) does not need to send the tax card to payroll.

Letter inquiries: a user has subscribed to receive new letter notifications. The user is an accounting office which uses the Letter inquiry API interfaces to manage their clients in their tax affairs. A new letter is sent to the client associated with the subscription (the client of the accounting firm) from the Tax Administration, which generates a notification in the Tax system. The notification is retrieved with the ListNotifications interface or sent to the user via the Push Notification service. Based on the notification, the user can react and retrieve the new letter information with the letter inquiry API interfaces. The user does not need to poll for new letters continuously, for example daily for all customers, but only when new letters have arrived.

Steps to use the service

Subscribe (API endpoint: Subscribe) Customer system first creates a subscription of notification types for customers they are interested in by calling the Subscribe endpoint. A unique subscription id is provided in the response message.
- With the Push Notification Service, the user registers their own software’s hosting interface to the service to receive the latest notifications in near real-time to their system.
Poll for notifications (API endpoint: ListNotifications) When subscription is successfully configured, the customer system polls the ListNotifications endpoint with the subscription id and the appropriate date range to receive available notifications.
- If you have enabled Push Notifications, you will automatically receive the latest notifications based on your subscription and registration as Push Notifications JSON calls directly to your software. Only the notification key (NotificationKey) is sent in the push notification call. No sensitive, personal- or business information is sent in the Push Notification calls.
- Retrieve the actual data content of the Push Notification call, using the GetNotification interface.
React to notifications (Customer system) When notification have been retrieved by the customer system, decide what to do with it, call other Vero API endpoints to get or send data based on the notification message content. Orchestration of activities is done by the customer system. Keeping track of read notifications is responsibility of the customer system.