Get Notifications

API allows ERP system to query for previously received notifications.

ERP - Receive Download Ready Notification ERP - Ping

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.