Overview
As additional convenience to enable more event driven integration architectures for information exchange related to documents registered in tax authority eInvoicing supports delivery of events to systems. This API describes delivery of document event notifications to taxpayer system that has been configured to receive them.
Types of notifications delivered are:
- document validated (validation complete and document is marked valid or invalid)
- document received
- document rejected
- document cancelled
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/documents (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 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 representing batched notification that contains only documents |
document |
| count | Number | Count of notifications in the batch if multiple ones are delivered in a single call to API | 39 |
| message | Document Notification Message[] | In case of document notification message the message element contains list of notifications batched together | See structure. |
Document Notification Message
| Input parameter | Type | Description | Value example |
|---|---|---|---|
| type | String | Notification type being delivered. For this notification batch can be document-validated, document-received, document-rejected, document-cancelled |
document-validated |
| uuid | String | Unique document ID in eInvoicing | F9D425P6DS7D8IU |
| submissionUUID | String | Unique ID of the submission tht document was part of | JU7GH07JNA23N |
| longId | String | Unique long temporary Id that can be used to query document data anonymously | LIJAF97HJJKH 8298KHADH0990 8570FDKK9S2LSIU HB377373 |
| internalId | String | Internal ID used in submission for the document | PZ-234-A |
| status | String | Current status of the document at the moment of sending out notification. For messages of type document-validated will be Invalid or Valid that should allow submitter to identify the documents that didn’t pass the validations at the tax authority and that need some action. Other possible statuses: Cancelled, Rejected |
Valid |
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.