Overview
MyInvois System supports (i) sending out notification via email and (ii) storing the notification in notification history. The ERP system are able to utilise the Get Notification API to query the notification history to obtain the notifications. Note that reliance on notifications for implementing entire e-Invoice workflow is optional and it is provided as an 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 descending notification date.
Signature
This 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 e-Invoice API header parameters for authenticated call.
URL parameters accepted:
| URL parameter | Type | Description | Value example | Requirement |
|---|---|---|---|---|
| dateFrom | DateTime | Optional: start date and time for notifications to retrieve based on the date sent | 2015-02-13T14:20:10Z | Optional |
| dateTo | DateTime | Optional: end date and time for notifications to retrieve based on the date sent | 2015-02-14T14:20:10Z | Optional |
| type | String | Optional: type of notifications to retrieve specified as ID of the type. See Notification types | 2 | Optional |
| language | String | Optional: used to get notifications only if they were sent out in a specific language. Values:msand en |
en | Optional |
| 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 | Optional |
| channel | String | Optional: used to get notifications delivered over certain channel only. Values: email, push |
Optional | |
| 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 | Optional |
| pageSize | Number | Optional: number of the packages to retrieve per page. Page size cannot exceed system configured maximum page size for this API which is 100 | 20 | Optional |
Notification Types
To be determined later.
Outputs
Successful Response
This 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:20:10Z |
| deliveredDateTime | DateTime | Optional date time when notification was delivered | 2015-02-13T14:23:10Z |
| 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: email, push |
|
| address | String | Channel address that was used to deliver the message | test@test.com |
| language | String | Language used for delivery. Values:ms,en |
en |
| 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:20:10Z |
| 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 e-Invoice system administrators.