Overview
API allows caller to get full details of the document when requested by unique ID assigned to document by eInvoicing solution.
Details include original XML or JSON submission and additional ID and validation details, current status added by the tax authority. Because document is submitted in XML or JSON, this API returns document information also in either JSON or XML.
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}/raw
Inputs
This API accepts standard eInvoicing API header parameters for authenticated call. But the content type parameter can define the expected output format - JSON or XML.
| 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 DocumentExtended.
Document Extended contains:
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| uuid | String | Unique document ID in eInvoicing | F9D425P6DS7D8IU |
| 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 |
| internalId | String | Internal ID used in submission for the document | PZ-234-A |
| typeName | String | Unique name of the document type that can be used in submission of the documents. | ‘i’ [invoice], ‘c’ [credit note], ‘d’ [debit note], ‘ii’ [import invoice], ‘ei’ [export invoice], ‘ec’ [export credit note], ‘ed’ [export debit note] |
| typeVersionName | String | Name of the document type version within the document type that can be used in document submission to identify document type version being submitted | 1.0 |
| issuerId | String | Registration number of issuer | 927398557 |
| issuerName | String | Issuer company name | My company |
| receiverId | String | Optional: receiver registration number (can be national ID or foreigner ID). | 087377381 |
| receiverName | String | Optional: receiver name (can be company name or person’s name) | Their company |
| dateTimeIssued | DateTime | The date and time when the document was issued. | 2015-02-13T13:15Z |
| dateTimeReceived | DateTime | The date and time when the document was submitted. | 2015-02-13T14:20Z |
| totalSales | Decimal | Total sales amount of the document in EGP. | 10.10 |
| totalDiscount | Decimal | Total discount amount of the document in EGP. | 50.00 |
| netAmount | Decimal | Total net amount of the document in EGP. | 100.70 |
| total | Decimal | Total amount of the document in EGP. | 124.09 |
| status | String | Status of the document - submitted, valid, invalid, rejected, cancelled |
valid |
| lateSubmissionRequestNumber | String | Optional: Late submission request identifier. Used to identify which late request no. used when submitting the document. | 927398557-23-1585 |
| document | Document | Document object depending on the type | See structure of all documents in type Document page. |
| 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. |
| additionalMetadata | Additional Metadata[] | Array about the metadata objects associated with the document | See structure |
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. |
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 download raw document 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.