POST /api/v1/transactions/cancelDocument

Mit dem Endpunkt

• POST /api/v1/transactions/cancelDocument

wird der Abbruch einer Transaktion an das Fiskalservice übertragen und dort gespeichert. 

Dies ist notwendig, um Transaktionen, welche mit PUT /api/v1/transactions/createDocument gestartet wurden, im Falle eines Transaktionsabbruchs auch korrekt zu schließen.

Ergebnis

Bei einer erfolgreichen Verarbeitung (200) antwortet der jeweilige Client des Fiskalservices mit einer fiscalResponse und speichert den Abbruch der Transaktion.

Verwendung

• Jedes Mal, wenn ein Dokument im elektronischen Aufzeichnungssystem durch Abbruch abgeschlossen wird.

Voraussetzungen

• Vor einem cancelDocument muss der Aufruf des Endpunktes PUT /api/v1/transactions/createDocument erfolgen
  • Daten aus der response von createDocument müssen in der JSON-Struktur von cancelDocument integriert werden. Siehe dazu nachfolgenden Abschnitt.

Übertragungsprozess

Wie beschrieben, setzt ein cancelDocument vorhergehendes createDocument voraus. Die fiscalResponse von createDocument beinhaltet die Felder:

"fiscalisationDocumentNumber": 0,
"fiscalisationDocumentRevision": 0,
"fiscalDocumentStartTime": 0,

die Informationen dieser Felder müssen in der JSON-Struktur, welche bei cancelDocument übermittelt wird, enthalten sein. Diese Felder beinhalten Werte, welche von einer benötigten Fiskalhardware (technische Sicherheitseinrichtung "TSE" in Deutschland) erzeugt werden und zur Transaktionsverkettung dienen.

"fiscalDocumentNumber": 24,
"fiscalDocumentRevision": 1,

Beispiel:

Das nachfolgende Beispiel zeigt einen einfachen Kassenbeleg für Deutschland (documentType = [0] = receipt), welcher an den Endpunkt POST /api/v1/transactions/cancelDocument geschickt wird.

{
   "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"
      }
   ]
}

Beispiel Mindestangaben cancelDocument:

{
   "uniqueClientId": "c1062c55-57c4-4ed2-9c53-aff1762326a4",
   "documentGuid": "{bdf8b5e9-5634-4c02-afad-543a7c480111}",
   "documentId": "100001",
   "documentNumber": "00002",
   "createDate": "2022-12-22T10:06:03",
   "bookDate": "2022-12-22T10:06:03",
   "user": {
      "id": "1234",
      "caption": "1234"
   },
   "fiscalDocumentNumber": 2938,
   "fiscalDocumentStartTime": "1671699962",
   "fiscalDocumentRevision": 1
   }
}

fiscalResponse

Die Rückmeldung (fiscalResponse) bei einem cancelDocument sollte in der Datenbank des Kassensystems, für Referenzzwecke, gespeichert werden. 

Die fiscalResponse enthält:

• generische Informationen
• landespezifische Informationen

Beispiel 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="
   }
}

Generische Informationen

Diese finden sich im Header-Bereich der fiscalResponse.

Bitte beachten Sie:

• Inhalt des Feldes "fiscalisationDocumentNumber" muss am Beleg angedruckt werden (DE).
• Inhalt des Feldes "printMessage" muss am Beleg angedruckt werden.

Landesspezifische Informationen

Landesspezifische Informationen werden im Bereich "AdditionalFields" bereitgestellt und beinhalten Informationen, welche am Beleg angedruckt werden müssen. (z.B. QR-Code oder alternativ TSE-Daten in Deutschland)

Beachten Sie dazu die Belegbeispiele des jeweiligen Landes.

"fiscalDocumentNumber": -1,

Antwort

Mögliche Antworten: