Overview
API allows caller to get full details of the document when requested by unique ID assigned to document by eInvoicing solution including the detailed validation results
Signature
API is REST based API that takes unique ID of the document as URL parameter and returns document details that were received from the issuer and additional details added after registration and validation of the document in the tax authority.
Signature:
GET /api/v1.0/documents/{uuid}/details
Inputs
This API accepts standard eInvoicing API header parameters for authenticated call.
| URL parameter | Type | Description | Value example |
|---|---|---|---|
| uuid | String | Unique ID of the document to retrieve. | F9D425P6DS7D8IU |
Outputs
Successful Response
API returns HTTP status code 200.
The resulting structure is a single object of type DocumentDetails.
Document Details contains:
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| 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 |
| dateTimeReceived | DateTime | The date and time when the document was submitted. | 2015-02-13T14:20Z |
| status | String | Status of the document - submitted, valid, invalid, rejected, cancelled |
valid |
| transformationStatus | String | Flag defining if the document has been transformed from XML to JSON or the other way depending on what was requested and what was the original format. Values: original, transformed. Note that transformed documents will have signature invalid due to format change. |
original |
| validationResults | Document Validation Results | Object structure containing full validation results of the document | See structure. |
| document | Document | Document object depending on the type | See structure of all documents in type Document page |
| cancelRequestDate | Date | Refer to the document cancellation request that has been initiated by the taxpayer “issuer” of the document on the system, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| rejectRequestDate | Date | Refer to the document rejection request that has been initiated by the taxpayer “receiver” of the document on the system, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| cancelRequestDelayedDate | Date | Refer to the date when this document will be marked as cancelled if the receiver taxpayer didn’t decline the cancellation request that was raised by issuer taxpayer, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| rejectRequestDelayedDate | Date | Refer to the date when this document will be marked as rejected if the issuer taxpayer didn’t decline the rejection request that was raised by receiver taxpayer, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| declineCancelRequestDate | Date | Refer to the decline cancellation request that has been initiated by the receiver taxpayer on the system, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| declineRejectRequestDate | Date | Refer to the decline rejection request that has been initiated by the issuer taxpayer of the document on the system, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| freezeStatus | Freeze Status | Information about the Freeze status of the document | See structure |
| additionalMetadata | Additional Metadata[] | Array about the metadata objects associated with the document | See structure |
| lateSubmissionRequestNumber | String | Optional: Late submission request identifier. Used to identify which late request no. used when submitting the document. | 927398557-23-1585 |
Document Validation Results
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| status | String | Validation status. Values: In progress, Valid, Invalid |
Valid |
| validationSteps | Validation Step Result[] | Validation results for each of the validation steps that has been scheduled. | See structure. |
Validation Step Result
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| name | String | Validation name from definition of all system validations. | GS1 code validator |
| status | String | Validation status. Values: In progress, Valid, Invalid |
Valid |
| error | Error | Optional: validation error structure containing one or more errors if status is Invalid |
See structure. |
Freeze Status
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| frozen | Boolean | Flag to indicate if the document is frozen | false |
| type | Number | Indicates the current freeze type on the document after performing the Unfreeze operation (0/null:Unfreezed, 1:Temporary Freeze, 2:Permanent) | 1 |
| scope | Number | Indicates the current freeze scope on the document (0/null:not-set, 1:Full, 2:Cancellation) | 1 |
| actionDate | Date | Refer to the date when the last Freeze or Unfreeze action took place, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| auCode | string | Accounting Unit Code | 13300101 |
| auName | string | Accounting Unit Name | Supreme Council for Media Regulation |
Additional Metadata
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| fieldName | String | Metadata field name. Should be one of the defined field names. Possible values (‘CustomsDeclarationDate’, ‘CustomsDeclarationID’, ‘PaymentNo’, ‘ExportPort’) | PaymentNo |
| fieldValue | String | Metadata field value | 12-55-889 |
| fieldType | String | Metadata field type. Possible values (‘Text’, ‘Boolean’, ‘DateTime’, ‘Number’) | String |
| fieldNameDescEn | String | Metadata field name description in English. | Payment Number |
| fieldNameDescAr | String | Metadata field name description in Arabic. | الرقم الالكتروني |
Error Response
Error situations are reported back by this API through the standard error response.
Additional specialized error messages can be returned:
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 403 | Forbidden | Returned when caller of the endpoint is trying to query document details while caller profile has ‘B2B Deny ERP Document Retrieval’ tag assigned to it by ETA Admin. |
Additional considerations
To get the ID used to call this API, taxpayer system can first call API returning list of recent documents.
Receiver of the documents can retrieve documents that are in statuses Valid, Rejected or Cancelled. If document exists, and is issued to given receiver, but status is submitted or invalid, not found code is returned.
Issuer of the documents can retrieve documents in any status.