Overview
As additional convenience to enable more event driven integration architectures for information exchange related to POS Devices registered in tax authority eInvoicing supports delivery of events to systems. This API describes delivery of POS Device event notifications to taxpayer system that has been configured to receive them.
Types of notifications delivered are:
- POS Device Credentials Expiration
- POS Device Dates Expiration
- POS Device Deactivated
- POS Device Unused
- Issue Received
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 (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 (70) | Defines the type of the message. JSON based content. | application/json |
| Authorization | String (100) | 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 |
|---|---|---|---|
| Id | String (100) | POS Device serial number | POS-No-123 |
| Type | String | Notification type. PosCredentialExpiration, PosDeviceUnused, IssueReceived, PosDeactivated or PosDatesExpiration |
PosCredentialExpiration |
| Message | General Notification Message | The message element contains details of POS device and event. | See structure. |
General Notification Message
| Input parameter | Type | Description | Value example |
|---|---|---|---|
| TaxpayerRin | String (30) | Taxpayer registration number, available in all events except for PosDeviceUnused |
123456789 |
| DeviceName | String (250) | Device name, available in all events except for PosDeviceUnused |
POS1 |
| ActiveFrom | Datetime | POS device active from, available in all events | 2022-07-19T00:00:00 |
| ActiveTo | Datetime | POS device active to, available in all events | 2022-08-19T00:00:00 |
| ExpirationPeriod | Integer | Expiry period of POS credentials or POS device in days, available only in PosCredentialExpiration and PosDatesExpiration |
1 |
| ClientId | String (100) | Client Id used to authenticate POS device, available only in PosCredentialExpiration event |
12345060-c072-4050-bb28-035c32152d55 |
| Reason | String (1000) | Reason of POS device deactivation, available only in PosDeactivated and IssueReceived |
Out of service |
| ModelName | String (250) | Model name of POS device, available only in PosDatesExpiration event |
TM88IV |
| VendorName | String (150) | Vendor name of POS model, available only in PosDatesExpiration event |
EPSON |
| DeviceCount | Integer | Taxpay POS devices count, available only for PosDeviceUnused event |
1 |
| Name | String (250) | Device name, available only for PosDeviceUnused event |
TEST_TEST |
| LastReceiptDate | Datetime | Last Receipt received date, available only for PosDeviceUnused event |
2022-09-06T08:38:52.7192874 |
| Id | Integer | available only for IssueReceived event |
|
| ReportId | String | Id of the issue receipt, available only for IssueReceived event |
|
| Status | String | Status of the issue, available only for IssueReceived event |
Cancelled or Resolved |
| Response | String | Response for the complaint, available only for IssueReceived event |
|
| Category | String | complaint category, available only for IssueReceived event |
Receipt / Submission / POS / Other |
| Type | String | complaint type, available only for IssueReceived event |
TotalAmountNotMatched or Other |
| Title | String | Title for the complaint, available only for IssueReceived event |
|
| BuyerRIN | String | RIN of the Buyer, available only for IssueReceived event |
|
| SellerRIN | String | RIN of the Seller, available only for IssueReceived event |
|
| ComplainantFirstName | String | available only for IssueReceived event |
|
| ComplainantLastName | String | available only for IssueReceived event |
|
| UpdatedBy | String | available only for IssueReceived event |
|
| UpdatedAt | String | available only for IssueReceived event |
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.