Overview
eInvoicing system supports sending out notifications to ERP systems of taxpayers that have been configured to receive them. But even if system is not configured to receive notifications, they can be delivered, for example, to e-mail and stored in notification history that allows ERP system to query this history and get notifications either to show to users of ERP or to process them automatically.
This API enables ERP systems to query notifications sent to taxpayer account. Note that reliance on notifications for implementing entire eInvoicing workflow is optional and provided as additional functionality that can be leveraged.
System limits the number of the notifications that can be received through a single request by implementing paging mechanism for this API.
List of notifications is ordered based on notification date descending.
Signature
API is REST based API that takes optional URL parameters to do data filtering and also enable paging.
Signature:
GET /api/v1.0/notifications/taxpayer?dateFrom={dateFrom}&dateTo={dateTo}&type={type}&language={language}&status={status}&channel={channel}&pageNo={pageNo}&pageSize={pageSize}
Inputs
This API accepts standard eInvoicing API header parameters for authenticated call.
URL parameters accepted:
| URL parameter | Type | Description | Value example |
|---|---|---|---|
| dateFrom | DateTime | Optional: start date and time for notifications to retrieve based on the date sent | 2015-02-13T14:20Z |
| dateTo | DateTime | Optional: end date and time for notifications to retrieve based on the date sent | 2015-02-14T14:20Z |
| type | String | Optional: type of notifications to retrieve specified as ID of the type. See Notification types | 2 |
| language | String | Optional: used to get notifications only if they were sent out in a specific language. Values: ar and en |
en |
| status | String | Optional: used to get notifications of certain status only, e.g., only those that were not delivered. Values: pending, batched, delivered, error |
delivered |
| channel | String | Optional: used to get notifications delivered over certain channel only. Values: sms, email, push, system |
system |
| pageNo | Number | Optional: number of the page to retrieve. Typically this parameter value is derived from initial parameter less call when caller learns total amount of page of certain size | 3 |
| pageSize | Number | Optional: number of the packages to retrieve per page. Page size cannot exceed system configured maximum page size for this API | 20 |
Notification Types
Notifications types values supported are:
- Delegation Invite = 1
- OTP = 2
- Profile Data Validation = 3
- Generic Notification = 4
- Receive DownloadReady = 5
- Document Received = 6
- Document Validated = 7
- Document Cancelled = 8
- Document Rejected = 9
Outputs
Successful Response
API returns HTTP status code 200.
The resulting structure is part of a single object containing result structure and metadata structure.
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| result | Notification[] | Array of notification objects | See structure |
| metadata | Metadata[] | Information about the results retrieved or results matching the query | See structure |
Notification
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| notificationId | String | Unique ID of the notification. | 73DKLJHH78NJUHQ |
| receivedDateTime | DateTime | The date and time when notification was sent out | 2015-02-13T14:20Z |
| deliveredDateTime | DateTime | Optional date time when notification was delivered | 2015-02-13T14:23Z |
| typeId | String | Id of the type of the message | 34 |
| typeName | String | Type name of the message | Invoice received |
| finalMessage | String | Optional: final message that was sent out - depends on the channel | Taxpayer 893838273 has received new documents |
| channel | String | Channel used for delivery. Values: sms, email, push, system |
sms |
| address | String | Channel address that was used to deliver the message | test@test.eg |
| language | String | Language used for delivery. Values: ar, en |
ar |
| status | String | Status of the notification delivery. Values - pending, batched, delivered, error |
delivered |
| deliveryAttempts | Delivery Attempt[] | Structure containing information about delivery attempts of the notification or its batch (if batched with others and delivered together) | See structure. |
Delivery Attempt
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| attemptDateTime | DateTime | Date time when delivery was attempted. | 2015-02-13T14:20Z |
| status | String | Status of the notification delivery. Values - delivered, error |
delivered |
| statusDetails | String | Error message in case of error in delivery | Cannot connect to system URL supplied |
Metadata
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| totalPages | Number | Total count of pages based on the supplied (or default) page size | 23 |
| totalCount | Number | Total count of matching objects | 157 |
Error Response
Error situations are reported back by this API through the standard error response.
No custom error codes are provided by this API.
Additional considerations
Maximum page size allowed is defined by eInvoicing system administrators.