POST /api/v1/transactions/cancelDocument – RetailForce

Med

POST /api/v1/transactions/cancelDocument

sendes en annullering af en transaktion til den skattemæssige tjeneste og gemmes der. Den bruges til at afbryde en transaktion, før den er afsluttet. For eksempel:

kunden ønsker at købe nogle varer i butikken
kassereren begynder at scanne varerne (POS sender PUT /api/v1/transactions/createDocument)
kunden opdager, at han har mistet sin tegnebog og ikke kan gennemføre købet
kassereren stopper transaktionen og sletter alle de scannede varer (POS sender POST /api/v1/transactions/cancelDocument for at afslutte den transaktion, der blev åbnet ved brug af PUT /api/v1/transactions/createDocument)

Resultat

Hvis behandlingen lykkes (200), svarer den pågældende skatteclient med en fiscalResponse og registrerer, at transaktionen er afbrudt.

Anvendelse

Hver gang et dokument lukkes i det elektroniske registreringssystem (kasseapparatet) ved at afbryde det.

Forudsætninger

cancelDocument skal forudgås af et kald til endpointet PUT /api/v1/transactions/createDocument
- Data fra svaret på createDocument skal integreres i JSON-strukturen i cancelDocument. Se det følgende afsnit.

Bemærk: Dokumenter, der ikke indeholder betalingsdata (f.eks. X- eller Z-rapport, ...), kan sendes til POST /api/v1/transactions/cancelDocument-endpointet uden et forudgående createDocument . Vi anbefaler dog, at du altid kalder createDocument som det første trin.

Overførselsproces

Som beskrevet kræver et `cancelDocument` et forudgående `createDocument`. `fiscalResponse` fra `createDocument` indeholder følgende felter:

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

Oplysningerne i disse felter skal indgå i den JSON-struktur, der sendes med `cancelDocument`. Disse felter indeholder værdier, der genereres af en påkrævet skattehardware (teknisk sikkerhedsenhed, "TSE", i Tyskland) og bruges til transaktionskædning.

OBS: Vær opmærksom på følgende særlige forhold:

fiscalResponse fra createDocument returnerer felterne fiscalisationDocumentNumber og fiscalisationDocumentRevision. I cancelDocument skal disse felter dog overføres med

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

uden "isation"! Bemærk også: Den pågældende transaktion er ikke påbegyndt

Eksempel:

Følgende eksempel viser en simpel kvittering for Tyskland (documentType = [0] = kvittering), som sendes til endpointet POST /api/v1/transactions/cancelDocument.

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

Bemærk: Ovenstående eksempel viser et (enkelt) komplet dokument. Ved en `cancelDocument` er det ikke nødvendigt at overføre et komplet dokument. De minimale oplysninger, som vist i det følgende eksempel, er tilstrækkelige.

Eksempel på minimumsoplysninger for `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

fiscalResponse for a cancelDocument bør gemmes i POS-databasen til referenceformål.

fiscalResponse indeholder:

generiske oplysninger
landespecifikke oplysninger

Eksempel på 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="
   }
}

Generelle oplysninger

Disse findes i header-området i fiscalResponse.

Bemærk:

Indholdet af feltet "fiscalisationDocumentNumber" skal udskrives på dokumentet (DE).
Indholdet af feltet "PrintMessage" skal være trykt på kvitteringen.

Landespecifikke oplysninger

Landespecifikke oplysninger findes i området "AdditionalFields" og indeholder oplysninger, der skal udskrives på kvitteringen. (f.eks. QR-kode eller alternativt TSE-data i Tyskland).

Se dokumenteksemplerne for det pågældende land.

Bemærk: Hvis værdien "-1" returneres i fiscalResponse for cancelDocument i feltet

"fiscalDocumentNumber": -1,

the client has identified the corresponding document as non-fiskal.

Svar

Mulige svar:

Kode	Beskrivelse	Eksempel
200	Annulleringsdokumentet blev sendt uden fejl og gemt i documentStore.	fiscalResponse
404	Tyskland: Det angivne fiscalDocumentNumber kunne ikke findes. Transaktionen med det angivne fiscalDocumentNumber er endnu ikke oprettet (påbegyndt). Fejlfinding: createDocument skal udføres før cancelDocument	-
406	Den overførte dokumenttype understøttes ikke Fejlfinding: Angivelse af den korrekte dokumenttype	-
422	Dokumentindholdet er tomt eller forkert Fejlfinding: Udfør POST /api/v1/transactions/validateDocument eller POST /api/v1/transactions/validateDocumentString for en mere detaljeret fejlanalyse	-

Denne artikel er oversat automatisk.