Overview
API allows caller to get details of the document type version that contains also definition of the XML or JSON structures that are expected to be submitted as part of document submission and receipt document submission.
Document type versions are used to allow document type data fields to be evolved over time without introducing a new document type. For example if initially document type version 1.0 could have certain field optional, a certain time later document type version 2.0 can be published where that field is made mandatory.
Note that it is possible that for one document type there are multiple valid document type versions. It is needed to enable transition periods allowing older versions to be submitted while already accepting newer document versions. Of course it is suggested to migrate to the latest document type version as soon as possible.
Signature
API is REST based API that takes unique ID of the document type and ID of the document type as URL parameter and returns full document type version object.
Signature:
GET /api/v1.0/documenttypes/{id}/versions/{vid}
Inputs
This API accepts standard eInvoicing API header parameters for authenticated call.
| URL parameter | Type | Description | Value example |
|---|---|---|---|
| id | Number | Unique ID of existing document type | 45 |
| vid | Number | Unique ID of existing document type version that is published or deactivated | 41235 |
Outputs
Successful Response
API returns HTTP status code 200.
The resulting structure is a single object of type DocumentTypeVersion.
Document Type Version contains:
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| typeName | String | Unique name of the document type that can be used in submission of the documents. | i (for invoice), c (for credit note), d (for debit note) |
| name | 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 |
| description | String | Description of the document type version | Credit note version 1.1 |
| versionNumber | Decimal | Unique version number of the document type version that can be sorted to find the latest version | 1.1 |
| status | String | Status of the document type version - “published”, “deactivated” | published |
| activeFrom | Date | Date when the activity of the document type version started | 2015-02-13T13:15Z |
| activeTo | Date | Optional: date when the activity of the document type version sends/when it was deactivated | 2027-03-01T00:00:00Z |
| jsonSchema | String | Base64 encoded JSON schema definition defining the technical structure of the JSON representation of the document type in this version. When submitting document of this type to eInvoicing, it is expected that the structure of the Document gets validated using this schema if used encoding is JSON1. | Base64 encoded string |
| xmlSchema | String | Base64 encoded XML schema definition defining the technical structure of the XML representation of the document type in this version. When submitting document of this type to eInvoicing, it is expected that the structure of the Document gets validated using this schema if used encoding is XML1. | Base64 encoded string |
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
To get the ID used to call this API, taxpayer system needs to first call API returning list of the document types and their versions.