With the
- POST /api/v1/transactions/storeDocument
endpoint, a document is transmitted to the fiscal service and stored there.
Result
If processing is successful (200), the respective fiscal service client responds with a fiscalResponse.
Usage
- Each time a document is finished in the electronic recording system (cash register).
Prerequisites
- storeDocument must be preceded by the call of the endpoint PUT /api/v1/transactions/createDocument
- Data from the response of createDocument must be integrated into the JSON structure of storeDocument. See the following section.
Transmission process
As described, a storeDocument requires a preceding createDocument. The fiscalResponse of createDocument contains the fields:
"fiscalisationDocumentNumber": 0,
"fiscalisationDocumentRevision": 0,
"fiscalDocumentStartTime": 0,
The information in these fields must be contained in the JSON structure transmitted with storeDocument. These fields contain values that are generated by a required fiscal hardware (technical security device "TSE" in Germany) and are used for transaction chaining.
Attention: Please note the following special characteristics:
The fiscalResponse of createDocument returns the fields fiscalisationDocumentNumber and fiscalisationDocumentRevision. In storeDocument, however, these fields must be passed with
"fiscalDocumentNumber": 24,
"fiscalDocumentRevision": 1,
without "isation"! Please also note: Given transaction not started
Example:
The following example shows a simple receipt for Germany (documentType = [0] = receipt), which is sent to the endpoint POST /api/v1/transactions/storeDocument.
{
"uniqueClientId": "c1062c55-57c4-4ed2-9c53-aff1762326a4",
"documentGuid": "7d4a7761-e9e9-4759-8591-ed147a581da4",
"documentId": "HAM01-00010329",
"documentNumber": "00010329",
"createDate": "2023-04-18T21:34:45",
"bookDate": "2023-04-18T21:34:46",
"cancellationDocument": false,
"isTraining": false,
"documentType": 0,
"user": {
"id": "1234",
"caption": "1234"
},
"fiscalDocumentNumber": 2853,
"fiscalDocumentStartTime": 1681803100,
"fiscalDocumentRevision": 1,
"Positions": [
{
"positionNumber": 0,
"netValue": 10.66,
"grossvalue": 12.90,
"taxValue": 2.24,
"quantity": 1,
"itemId": "1101202930050",
"itemCaption": "Pizza Margherita",
"cancellationPosition": "false",
"type": "0",
"businessTransactionType": 0,
"vatPercent": 19,
"vatIdentification": 1,
}
],
"Payments": [
{
"Amount": 12.90,
"paymentType": "cash",
"uniqueReadablePaymentIdentifier": "Cash",
"caption": "Bar+Euro",
"currencyIsoCode": "EUR"
}
]
}
fiscalResponse
The fiscalResponse for a storeDocument should be stored in the POS database for reference purposes.
The fiscalResponse contains:
- generic information
- country-specific information
Example fiscalResponse:
{
"fiscalCountry": "[0] = Germany",
"fiscalisationDocumentNumber": 52,
"fiscalisationDocumentRevision": 2,
"fiscalDocumentStartTime": 1674819139,
"processStartTime": 0,
"errorDescription": null,
"cashRegisterId": "00345-00345",
"signature": "pCeGi98gNNhshcGJkbw0DwtSzuJkaawON8l5QwsFDEaDHOyYK2aNVO4ZAlpkYYnub7oxM/2R1/KB36UzmOQwew==",
"userMessage": null,
"printMessage": "***Test***",
"requestTime": "2023-01-27T12:34:21.3088836+01:00",
"requestCompletionTime": "2023-01-27T12:34:22.4379009+01:00",
"AdditionalFields": {
"QrCodeDataString": "V0;00345-00345;Kassenbeleg-V1;Beleg^13.90_0.00_0.00_0.00_0.00^13.90:Unbar;52;197;2023-01-27T11:32:19.000Z;2023-01-27T11:34:20.000Z;ecdsa-plain-SHA256;unixTime;pCeGi98gNNhshcGJkbw0DwtSzuJkaawON8l5QwsFDEaDHOyYK2aNVO4ZAlpkYYnub7oxM/2R1/KB36UzmOQwew==;BNHckCuXF2fEktIp8qwtnMLLgvpJDX6wEOqFENlHXZpekBHxHniQh9gbigjWS9UbCwZSrOTJTMK7WiV5owAfXkk=",
"TransactionStartTime": 1674819139,
"TransactionEndTime": 1674819260,
"ProcessData": "Beleg^13.90_0.00_0.00_0.00_0.00^13.90:Unbar",
"ProcessType": "Kassenbeleg-V1",
"TseSerial": "e5f5836a57c50c526d4bed37f18823608f2f44e2c98cab73278a7676c5ea0885",
"TseTimeFormat": "unixTime",
"TseHashAlgorithm": "ecdsa-plain-SHA256",
"TsePublicKey": "BNHckCuXF2fEktIp8qwtnMLLgvpJDX6wEOqFENlHXZpekBHxHniQh9gbigjWS9UbCwZSrOTJTMK7WiV5owAfXkk=",
"TseSignatureCounter": 197,
"TseCertificate": "MIIB0jCCAVmgAwIBAgIhAOX1g2pXxQxSbUvtN/GII2CPL0TiyYyrcyeKdnbF6giFMAoGCCqGSM49BAMDMDExFTATBgNVBAoTDGZpc2thbHkgR21iSDEYMBYGA1UEAxMPZmlza2FseSBUZXN0IENBMB4XDTIyMTAzMDEyMjgzMloXDTIzMTAzMDEyMjgzMlowMjEVMBMGA1UEChMMZmlza2FseSBHbWJIMRkwFwYDVQQDExBmaXNrYWx5IFRlc3QgVFNFMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE0dyQK5cXZ8SS0inyrC2cwsuC+kkNfrAQ6oUQ2Uddml6QEfEeeJCH2BuKCNZL1RsLBlKs5MlMwrtaJXmjAB9eSaNBMD8wDgYDVR0PAQH/BAQDAgeAMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUlllBymQBup6ldKGojZVpZtWG5tQwCgYIKoZIzj0EAwMDZwAwZAIwEFsoSON9cIBqA5d9vsGI2jSjDlZxHokDvJ4yBmayvigrDbdhMYe3hw3HyQbO2B/FAjBXSVNbYR6Wg2TVzL9BhCla+tewRDGcs6vnetJ4i3VRtya1+ejt+vRjWnb/RUyo0Uw="
}
}
Generic information
These can be found in the header area of the fiscalResponse.
Please note:
- Content of the field "fiscalisationDocumentNumber" must be printed on the document (DE).
- The content of the field "printMessage" must be printed on the receipt.
Country-specific information
Country-specific information is provided in the "AdditionalFields" area and contains information that must be printed on the receipt. (e.g. QR code or alternatively TSE data in Germany).
Please refer to the document examples of the respective country.
Note: If the value "-1" is returned in the fiscalResponse of storeDocument in the field
"fiscalDocumentNumber": -1,
the client has recognised the corresponding document as non-fiscal.
Response
Possible responses:
Code | Beschreibung | Beispiel |
200 |
The document was transmitted successfully and without errors and saved in the documentStore. |
fiscalResponse |
404 |
Germany: the specified fiscalDocumentNumber could not be found. The transaction with the specified fiscalDocumentNumber has not yet been created (started). Troubleshooting:
|
- |
406 |
The transmitted document type is not supported Troubleshooting:
|
- |
422 |
The document content is empty or incorrect Troubleshooting:
|
- |
Comments
0 comments
Please sign in to leave a comment.