ERP - Receive Download Ready Notification

API needs to be exposed by ERP and allows ERP system to receive notification when document package is ready for download.

ERP - Receive Document Notifications Full eInvoicing API list

Overview

As additional convenience to enable more event driven integration architectures for information exchange related to document processing in tax authority eInvoicing supports delivery of events to systems. This API describes delivery of document package notification to taxpayer system that has been configured to receive them.

Type of notification delivered is document package ready. If it gets delivered, it contains ID of the package that is ready to download by the system. System can use received ID to right away start the package download using download API.

Note that to receive notifications, ERP system needs to expose an API defined in this page that is “visible” to ETA system over the Internet and can be called over HTTPS that is protected using one of the globally valid Root CA issued certificates. “Visibility” is checked during registration by calling Ping API exposed by ERP system.

Signature

The signature to be supported by the ERP system to be able to receive notification is:

PUT /notifications/documentpackages (this relative path is attached to base URL shared by customer when registering system to receive notifications)

Note that the API should be idempotent - it is possible that due to network issues the same method with the same parameters get called more than once to deliver notifications.

Inputs

This API should accept these headers supplied by eInvoicing:

Header parameter Type Description Value example
Accept-Language String Will contain ar or en based on the notification preferences of the taxpayer ar
Content type String Defines the type of the message. JSON based content. application/json
Authorization String Pre-shared key registered by taxpayer when registering system callback is used so that ERP can authenticate eInvoicing ApiKey <Key value>

Body of the request contains a single an object that contains these fields:

Input parameter Type Description Value example
deliveryId String Unique identifier of the notification delivery, can be used to deduplicate if called multiple times. 838847HS2
type String Notification type or type of batched notification being delivered. For this notification type is document-package-ready representing notification that contains only document package ready information document-package-ready
count Number Count of notifications in a single call to API 1
message Document Package Ready Message[] In case of document package ready notification the message element contains 1 notification See structure.

Document Package Ready Message

Input parameter Type Description Value example
type String Notification type being delivered. For this notification batch can be document-package-ready document-package-ready
packageId String Unique package Id that can be used to download prepared package. Q932847883HDH

Outputs

On a successful submission ERP API must return 200 status code.

If 4xx or 5xx codes are returned the eInvoicing solution will retry calling the ERP pre-configured amount of retries.

Additional considerations

This API is called by eInvoicing only over protected HTTPS channel.