Overview
API allows caller to get details of a single submission to check its processing status after initially submitting it and getting back unique submission identifier.
This API is available to submitter only as it might contain documents issued to multiple receivers.
Signature
API is REST based API that takes unique ID of the submission as URL parameter and returns details of the submission and summary information of the documents part of the submission.
Because submission might have quite some number of the documents as part of it, list of the documents returned by this API is paged.
Signature:
GET /api/v1.0/documentsubmissions/{uuid}?pageNo={pageNo}&pageSize={pageSize}
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 submission to retrieve. | HJSD135P2S7D8IU |
| 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 documents to retrieve per page. Page size cannot exceed system configured maximum page size for this API | 20 |
Outputs
Successful Response
API returns HTTP status code 200.
The resulting structure is a single object containing the attributes as defined in the table:
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| uuid | String | Unique document submission ID in eInvoicing | HJSD135P2S7D8IU |
| documentCount | Number | Total count of documents in submission that were accepted for processing | 234 |
| dateTimeReceived | DateTime | The date and time when the submission was received by eInvoicing. | 2015-02-13T14:20Z |
| overallStatus | String | Overall status of the batch processing. Values: in progress, valid, partially valid, invalid |
valid |
| documentSummary | Document Summary[] | List of the retrieved batch documents in current page. | See structure. |
| documentSummaryMetadata | Metadata | Information on object count. | See structure. |
Document Summary
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| uuid | String | Unique document ID in eInvoicing | F9D425P6DS7D8IU |
| 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 |
| 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 |
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.
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 a submission while caller profile has ‘B2B Deny ERP Document Retrieval’ tag assigned to it by ETA Admin. |
Additional considerations
Maximum page size allowed is defined by eInvoicing system administrators.
API is available to issuers that are querying their submissions. This also includes authorized intermediaries (service providers) who submitted the documents on behalf of the taxpayer they represent.