Con il
- funzione POST /api/v1/transactions/cancelDocument
viene trasmessa al servizio fiscale la richiesta di annullamento di una transazione. La registrazione dell’annullamento, nonché le relative modalità, dipendono dal Paese. Tale funzione viene utilizzata per interrompere una transazione prima del suo completamento. Ad esempio:
- il cliente desidera acquistare alcuni articoli nel negozio
- il cassiere inizia a scansionare gli articoli (il POS invia PUT /api/v1/transactions/createDocument)
- il cliente si accorge di aver smarrito il portafoglio e non può effettuare l’acquisto
- il cassiere interrompe la transazione ed elimina tutti gli articoli scansionati (il POS invia un POST /api/v1/transactions/cancelDocument per chiudere la transazione aperta in precedenza tramite il comando PUT /api/v1/transactions/createDocument)
Risultato
Se l’elaborazione va a buon fine (200), il rispettivo client del servizio fiscale risponde con una «fiscalResponse» e chiude la transazione aperta con «createDocument».
Utilizzo
- Ogni volta che un documento viene chiuso nel sistema di registrazione elettronica (registratore di cassa) tramite annullamento.
Prerequisiti
- La chiamata a `cancelDocument` deve essere preceduta dalla chiamata all’endpoint PUT /api/v1/transactions/createDocument
- I dati della risposta di createDocument devono essere integrati nella struttura JSON di cancelDocument. Si veda la sezione seguente.
Processo di trasmissione
Come descritto, un `cancelDocument` richiede un `createDocument` precedente. La `fiscalResponse` di `createDocument` contiene i seguenti campi:
"fiscalisationDocumentNumber": 0,
"fiscalisationDocumentRevision": 0,
"fiscalDocumentStartTime": 0,
Le informazioni contenute in tali campi devono essere incluse nella struttura JSON trasmessa con `cancelDocument`. Tali campi contengono valori generati da un dispositivo hardware fiscale obbligatorio (dispositivo tecnico di sicurezza “TSE” in Germania) e vengono utilizzati per il concatenamento delle transazioni.
Attenzione: si prega di tenere conto delle seguenti caratteristiche particolari:
Il fiscalResponse di createDocument restituisce i campi fiscalisationDocumentNumber e fiscalisationDocumentRevision. In cancelDocument, tuttavia, tali campi devono essere trasmessi con
"fiscalDocumentNumber": 24,
"fiscalDocumentRevision": 1,
senza il suffisso «isation»! Si prega inoltre di notare: transazione non avviata
Esempio:
L’esempio seguente mostra una semplice ricevuta per la Germania (documentType = [0] = ricevuta), che viene inviata all’endpoint 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"
}
]
}Esempio di informazioni minime per `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
La fiscalResponse relativa a un’operazione cancelDocument deve essere archiviata nel database del POS a scopo di riferimento.
La fiscalResponse contiene:
- informazioni generiche
- informazioni specifiche per paese
Esempio di 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="
}
}Informazioni generiche
Tali informazioni sono riportate nell’area dell’header della «fiscalResponse».
Nota bene:
- Il contenuto del campo «fiscalisationDocumentNumber» deve essere stampato sul documento (DE).
- Il contenuto del campo «PrintMessage» deve essere stampato sulla ricevuta.
Informazioni specifiche per paese
Le informazioni specifiche per paese sono riportate nell’area «AdditionalFields» e contengono dati che devono essere stampati sulla ricevuta (ad es. codice QR o, in alternativa, dati TSE in Germania).
Si prega di fare riferimento agli esempi di documenti del rispettivo Paese.
Nota: se nel campo «fiscalResponse» della funzione «cancelDocument» viene restituito il valore «-1»,
"fiscalDocumentNumber": -1,
il client ha identificato il documento corrispondente come non fiscale.
Risposta
Risposte possibili:
| Codice | Descrizione | Esempio |
| 200 | Il documento di annullamento è stato trasmesso correttamente e senza errori. | fiscalResponse |
| 404 |
Germania: impossibile individuare il fiscalDocumentNumber specificato. La transazione con il fiscalDocumentNumber specificato non è stata ancora creata (avviata). Risoluzione dei problemi:
|
- |
| 406 |
Il tipo di documento trasmesso non è supportato Risoluzione dei problemi:
|
- |
| 422 |
Il contenuto del documento è vuoto o errato Risoluzione dei problemi:
|
- |
Questo articolo è stato tradotto automaticamente.
Commenti
0 commenti
Accedi per aggiungere un commento.