Il presente articolo tratta l’oggetto Header (“payments”), ovvero gli elementi presenti nell’Header all’interno dell’oggetto Document.
Una descrizione completa del RetailForce DOM (Document Object Model), nonché una descrizione dei singoli elementi, è disponibile nella sezione Download del sito web di RetailForce (Documentazione sul modello a oggetti.pdf) nella rispettiva directory della versione.
Oggetto Header
{
"uniqueClientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"applicationVersion": "6.2.5",
"applicationVersionId": "string",
"applicationVersionPrevious": "string",
"fiscalModuleVersion": "1.8.8",
"fiscalCountryModuleVersion": "1.0.5",
"softwareName": "GreatesPOS",
"retailForceReceiptId": "W3D9C2Q1",
"additionalFields": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"automaticVatCalculation": "noCalculation",
"allowedVatDeviation": 0.01,
"terminalSlaveId": "Pad05",
"cashRegisterSerialNumber": "CR123456789",
"footerGraphicIndex": 5,
"auditLogEntryType": "other",
"amount": 0,
"identifier": "string",
"documentGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentId": "S962-000001287",
"createDate": "2023-04-27T17:27:12+01:00",
"bookDate": "2023-04-27T17:27:12+01:00",
"accountingDate": "2023-04-27T17:27:12+01:00",
"processStartDate": "2023-04-27T17:27:12+01:00",
"documentNumber": "000001287",
"documentNumberSeries": "Kassenbelege",
"cancellationDocument": false,
"failedToPay": false,
"documentReference": {
"referenceType": "[0] = Cancellation",
"storeNumber": "Restaurant 03",
"terminalNumber": "002",
"documentType": "[0] = Receipt",
"documentNumber": "000000895",
"documentNumberSeries": "Kassenbelege",
"fiscalDocumentNumber": 0,
"documentGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentId": "S962-000000895",
"documentBookDate": "2023-04-27T17:27:12+01:00",
"returnReasonType": "userMistake",
"returnReasonText": "Fehler passiert"
},
"isTraining": true,
"testCaseNumber": "string",
"documentType": "[0] = Receipt",
"documentTypeCaption": "Verkaufsbeleg",
"user": {
"id": "03",
"caption": "Bedienung 03",
"firstName": "Franz",
"lastName": "Österreicher",
"taxNumber": "123456789",
"dateOfEntry": "2022-10-01T08:00:00+01:00"
},
"salesPerson": {
"id": "04",
"caption": "Kassier 04",
"firstName": "Sandra",
"lastName": "Hurtig",
"taxNumber": "987654321",
"dateOfEntry": "2022-10-01T08:00:00+01:00"
},
"allocationGroups": [
"Tisch 127"
],
"partner": {
"id": "ABC1234567",
"caption": "Kunde",
"isBusiness": false,
"partnerType": "[0] = Customer",
"partnerClassification": "Privatkunde",
"vatNumber": "n.a.",
"taxNumber": "n.a.",
"identificationType": "passport",
"partnerIdentification": "ABC1234567",
"addressType": "BillingAddress",
"additionalIdentifications": {
"lotteryId": "1234567",
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"street": "Musterstraße",
"streetNumber": "186",
"postalCode": "1010",
"city": "Wien",
"community": "n.a.",
"countryCode": "AT"
},
"notes": "Anmerkungen",
"customerCount": 1,
"paymentTerms": {
"dueDateDays": 0,
"discount": 0,
"discountDueDays": 0,
"latePaymentPenaltyRate": 0
},
"servicePeriodStart": "2023-04-27T17:27:12+01:00",
"servicePeriodEnd": "2023-04-27T17:27:12+01:00",
"positionCount": 1,
"documentIssueType": "paper",
"coupon": {
"header": [
{
"text": "string",
"barcodeType": "QrCode",
"barcode": "https://retailforce.cloud"
}
],
"grafic": "string",
"footer": [
{
"text": "string",
"barcodeType": "QrCode",
"barcode": "https://retailforce.cloud"
}
]
},
"serviceType": "string",
"isEcommerceTransaction": true,
"taxPositions": [
{
"vatIdentification": 0,
"vatLabel": "string",
"vatPercent1": 0,
"vatPercent2": 0,
"vatAmount": 0,
"vatAmount2": 0,
"netAmount": 0,
"grossAmount": 0
}
],
"fiscalResponse": {
"fiscalCountry": "[1] = Austria",
"certificationType": "string",
"fiscalisationType": "string",
"supportedPlatformTypes": "string",
"overpaymentNotAllowed": "boolean",
"documentTypeBusinessTransactionTypeSupport": "string",
"fiscalDocumentNumber": "0",
"taxPositions": [
{
"vatIdentification": 0,
"vatLabel": "string",
"vatPercent1": 0,
"vatPercent2": 0,
"vatAmount": 0,
"vatAmount2": 0,
"netAmount": 0,
"grossAmount": 0
}
],
"fiscalDocumentStartTime": 0,
"processStartTime": 0,
"errorDescription": "string",
"cashRegisterId": "string",
"signature": "string",
"userMessage": "string",
"printMessage": "string",
"requestTime": "2023-04-27T17:27:12+01:00",
"requestCompletionTime": "2023-04-27T17:27:12+01:00",
"qrCode": "string",
"printingFields": {},
"AdditionalFields": {}
},
"fiscalDocumentNumber": 0,
"fiscalDocumentRevision": 0,
"FiscalDocumentStartTime": 0,
"positions": [
{
"positionNumber": 0,
"positionReference": {
"positionNumber": 0,
"referenceType": "[0] = Cancellation",
"storeNumber": "string",
"terminalNumber": "string",
"documentType": "[0] = Receipt",
"documentNumber": "string",
"documentNumberSeries": "string",
"fiscalDocumentNumber": 0,
"documentGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentId": "string",
"documentBookDate": "2023-04-27T17:27:12+01:00",
"returnReasonType": "userMistake",
"returnReasonText": "string"
},
"cancellationPosition": true,
"deletedPosition": false,
"type": "[0] = Item",
"itemCaption": "Sample Item",
"itemId": "ITEM-001",
"itemType": "[0] = Article",
"quantity": 1.0,
"quantityUnit": { "id": "Stk" },
"businessTransactionType": "[0] = Revenue",
"netValue": 10.0,
"grossValue": 12.0,
"taxValue": 2.0,
"ItemDateOfEntry": "2021-08-08T12:00:00+01:00",
"additionalFields": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"createDate": "2023-04-27T17:27:12+01:00",
"externalIdentifier": [
"string"
],
"user": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string",
"dateOfEntry": "2021-08-08T12:00:00+01:00"
},
"salesPerson": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string",
"dateOfEntry": "2021-08-08T12:00:00+01:00"
},
"FiscalAdditionalFields": {}
}
],
"payments": [
{
"amount": 12.0,
"currencyIsoCode": "EUR",
"caption": "string",
"uniqueReadablePaymentIdentifier": "string",
"foreignAmount": 0,
"foreignAmountExchangeRate": 0,
"additionalFields": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"paymentType": "creditCard",
"createDate": "2023-04-27T17:27:12+01:00",
"vatIdentification": 0,
"vatPercent": 0,
"taxValue": 0,
"externalIdentifier": [
"string"
],
"user": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string",
"dateOfEntry": "2021-08-08T12:00:00+01:00"
},
"salesPerson": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string",
"dateOfEntry": "2021-08-08T12:00:00+01:00"
},
"paymentTerminalReferenceId": "string",
"cardData": {
"receiptCopyCount": 0,
"receipt": [
"string"
],
"cardNumberMasked": "string",
"identificationToken": "string",
"merchantCopyCount": 0,
"merchantReceipt": [
"string"
],
"cardType": "VISA",
"authorizationCode": "AUTH123",
"terminalId": "TERM-A1",
"merchantId": "MERCH-B2",
"transactionId": "TRANS-C3",
"providerSignature": "string",
"providerTransactionId": "string",
"providerSignatureMessage": "string",
"transactionDate": "2023-04-27T17:27:12+01:00",
"transactionNumber": "string"
}
}
],
"additionalHeader": [
"string"
],
"additionalFooter": [
"string"
],
"FiscalAdditionalFields": {}
}L’oggetto Header contiene le seguenti informazioni.
Informazioni nella colonna “Tipo”:
- M ... obbligatorio ("mandatory")
- M* ... obbligatorio in determinati paesi o a determinate condizioni
- R ... raccomandato (“raccomandato”)
- O ... facoltativo
| Elemento | Tipo | Descrizione | |
| uniqueClientId | M | ID univoco del cliente, corrispondente all’ID del terminale in RetailForce Cloud (viene restituito/assegnato durante la messa in servizio tramite PUT /api/v1/management/clients/byCloud). | |
| applicationVersion | R/M* |
Versione del software del registratore di cassa.
Attenzione:
si prega di notare che in alcuni paesi (Francia) il numero di versione è fissato nell’ambito del processo di certificazione. Se viene specificato un numero di versione errato (non corrispondente a quello certificato), non è possibile completare il documento (= errore). Si prega inoltre di fare riferimento a: Versione certificata
.
Dettagli sul Paese:
|
|
| ApplicationVersionId | R/M* |
ID della versione del software del registratore di cassa. Dettagli sul Paese:
|
|
| ApplicationVersionPrevious | R/M* |
ID della versione precedente del software del registratore di cassa. Dettagli sul Paese:
|
|
| FiscalModuleVersion | O/M* | Versione del modulo fiscale (Trusted Fiscal Module) utilizzato per generare il rispettivo documento. Impostata automaticamente dal middleware se non trasmessa dal software. | |
| FiscalCountryModuleVersion | O/M* | Versione del modulo nazionale (Trusted Fiscal Country Module) utilizzato per generare il documento in questione. Viene impostata automaticamente dal middleware qualora non venga trasmessa dal software. | |
| FiscalisationType | O | ||
| firma | O | Firma | |
| Stampante fiscale | Stampante fiscale | ||
| online | Online | ||
| firmaConConnessioneOnline | Firma con connessione online | ||
| senza fiscalizzazione | Nessuna fiscalizzazione | ||
| Tipo di fiscalizzazione: Italia | O | ||
| stampante | O | Registratore telematico | |
| retailForceReceiptId | O | Numero di ricevuta univoco a livello globale (composto da terminalId e numero progressivo della ricevuta). Può essere generato al momento della creazione di una transazione (con createDocument). | |
| AdditionalFields | O | ||
| additionalProp1-x | O | ||
| automaticVatCalculation | O |
Questo elemento attiva il calcolo automatico di vari campi di somma a livello di posizione. 0 noCalculation - non viene effettuato alcun calcolo automatico 1 netValueCalculation - calcolo automatico dell’importo netto e dell’importo del Vat. È necessario specificare almeno l’importo lordo e l’aliquota Vat o il codice identificativo. 2 grossValueCalculation - Calcolo automatico dell’importo lordo e dell’importo dell’imposta. Devono essere specificati almeno il valore netto e l’aliquota Vat o il codice identificativo. |
|
| AllowedVatDeviation | O |
Può essere utilizzato per compensare eventuali problemi di arrotondamento nel calcolo del Vat. Si raccomanda di utilizzarlo con cautela: se impostato su un valore elevato, la verifica del calcolo del VAT viene disabilitata. Esempio: "AllowedVatDeviation": 0,05, consente uno scostamento di 5 centesimi tra valore netto + valore dell’imposta = valore lordo (+-0,05) |
|
| TerminalSlaveId | O | Specificazione dell’ID di un terminal di input. | |
| cashRegisterSerialNumber | O |
Numero di serie del dispositivo registratore di cassa. Questo campo identifica l’hardware fisico specifico del registratore di cassa utilizzato per elaborare la transazione. | |
| footerGraphicIndex | O |
Tramite footerGraphicIndex viene inserito un elemento grafico predefinito nel piè di pagina di un documento. Dettagli relativi al Paese:
|
|
| AuditLogEntryType | Specifica il tipo di voce del registro di audit quando il documento stesso costituisce una voce del registro di audit. | ||
| importo | Un importo associato all’header del documento (ad esempio, ai fini del registro di controllo). | ||
| identifier | Un campo di identificazione generale (ad esempio, ai fini del registro di audit). | ||
| DocumentGuid | M | Identificatore univoco del documento basato su UUID/GUID. Utilizzato anche come riferimento per le ricevute digitali. | |
| DocumentId | M | Numero univoco e sequenziale del documento (ricevuta) all’interno della filiale / succursale / ristorante (su tutti i registri), assegnato dal sistema di cassa (max. 40 caratteri). | |
| CreateDate | M | Data e ora di creazione del documento | |
| BookDate | M | Data di registrazione | |
| AccountingDate | O | Data di registrazione contabile possibile per questo documento | |
| ProcessStartDate | R/M* | Data di creazione della prima ricevuta nell’ambito dell’intero processo (ad es. Germania: data di creazione del primo ordine del cliente relativo alla presente ricevuta di pagamento – si veda anche «Caratteristiche specifiche del settore della ristorazione») | |
| DocumentNumber | R/M* | Numero univoco e sequenziale del documento (="numero di ricevuta"), assegnato dal sistema di cassa. | |
| documentNumberSeries | O/M* |
Nome della serie numerica associata al numero di ricevuta (DocumentNumber). Dettagli per paese:
|
|
| cancellationDocument | M |
Flag che specifica se il presente documento viene utilizzato per annullare un altro documento (emesso in precedenza) true – Documento di annullamento false - Nessun documento di annullamento |
|
| FailedToPay | O |
Un flag booleano (true/false) che indica se il pagamento associato al documento non è andato a buon fine. |
|
| documentReference | O/M* | Utilizzato per fare riferimento a un altro documento. | |
| {...} | |||
| IsTraining | O/M* | Flag per contrassegnare i documenti di formazione/dimostrazione (generati in modalità formazione/dimostrazione del registratore di cassa). | |
| TestCaseNumber | O/M* |
Campo per specificare un numero di caso di test a fini di certificazione. Dettagli sul Paese:
|
|
| DocumentType | O | Specificazione del tipo di documento | |
| documentTypeCaption | M* |
Descrizione del tipo di documento. Serve essenzialmente a fornire una descrizione più dettagliata o a chiarire il contenuto. Dettagli relativi al Paese:
|
|
| utente | O/M* |
Informazioni relative all’utente (del registratore di cassa). Dettagli sul Paese:
|
|
| {...} | |||
| SalesPerson | O/M* |
Informazioni relative al personale di vendita. Dettagli sul Paese:
|
|
| {...} | |||
| AllocationGroups [] | O/M* |
Utilizzato per assegnare le ricevute a elementi specifici (ad es. tavoli nel settore della ristorazione). Si veda anche: Processo di gestione degli ordini a lungo termine nel settore della ristorazione. Dettagli per paese:
|
|
| partner | O/M* |
Informazioni sui rispettivi partner (commerciali) della società emittente del documento. Dettagli per paese:
|
|
| addressType | (nell’ partner oggetto) Nuovo campo facoltativo per specificare il tipo di indirizzo (ad es. indirizzo di fatturazione). |
||
| {...} | |||
| Nota | O | Registrazione di note aggiuntive | |
| CustomerCount | O/M* |
Numero di clienti associati al presente documento (ad es., nel settore della ristorazione, il numero di ospiti alla cassa/al tavolo) Dettagli sul Paese:
|
|
| PaymentTerms | O | Termini di pagamento / condizioni di pagamento | |
| {...} | |||
| ServicePeriodStart | O |
Inizio del periodo di servizio (in particolare per le fatture) Dettagli sul Paese:
|
|
| ServicePeriodEnd | O |
Fine del periodo di servizio (in particolare per le fatture) Dettagli sul Paese:
|
|
| PositionCount | O/M* |
Numero di voci contenute nella ricevuta (tutte le voci, comprese articolo, testo, prenotazione, subtotale, totale) Si veda anche l’oggetto “Posizione”. Dettagli per paese:
|
|
| DocumentIssueType | O/M* |
Definisce il tipo di emissione della ricevuta.
Dettagli sul Paese:
|
|
| coupon | O | Possibilità di stampare coupon aggiuntivi e altri elementi sulla ricevuta. | |
| {...} | |||
| serviceType | O/M* |
Specificazione del tipo di servizio nel settore della ristorazione (servizio al tavolo, al bancone). Valori possibili (rispettare la convenzione CamelCase!)
Dettagli sul Paese:
|
|
| IsEcommerceTransaction | O/M* |
Indicazione che si tratta di una transazione di e-commerce (true / false). Dettagli sul Paese:
|
|
| TaxPositions | R |
Specificazione di tutte le posizioni Vat del documento. È necessario specificare tutte le posizioni IVA oppure nessuna. Per ottenere le posizioni IVA dal documento (qualora questa proprietà non sia stata impostata), utilizzare GetTaxPositions(Document, boolean).
Nota per l’Austria:
si raccomanda di utilizzare questo array per trasmettere le posizioni fiscali di una ricevuta, al fine di evitare problemi di arrotondamento all’interno del protocollo di registrazione dei dati (“DEP7”).
|
|
| {...} | |||
| fiscalResponse | - |
Risposta del servizio di fiscalizzazione a seguito delle operazioni di trasmissione createDocument e storeDocument. Si raccomanda di persistere il contenuto di fiscalResponse nel database del registratore di cassa.
Nota:
alcuni campi dell’oggetto fiscalResponse, dopo l’esecuzione della funzione createDocument
, devono essere inclusi nel documento JSON (che dovrà essere trasmesso a storeDocument
). Si raccomanda di NON includere l’intero oggetto fiscalResponse!
|
|
| {...} | |||
| fiscalDocumentNumber | M* |
Numero del documento fiscale (assegnato dal RetailForce system o dalla rispettiva unità di fiscalizzazione – ad es. TSE in Germania)
Attenzione:
si prega di notare che nei sistemi fino alla versione v1.7.7 l’informazione fiscalDocumentNumber veniva restituita nel campo fiscalisation
DocumentNumber dell’oggetto fiscalResponse. Si veda anche l’articolo: «Transazione non avviata
». Nella versione v1.7.7 è stato introdotto un campo aggiuntivo fiscalDocumentNumber (stringa) nell’oggetto fiscalResponse.
|
|
| fiscalDocumentRevision | O/M* |
Numero di revisione del documento fiscale (assegnato dal RetailForce system o dalla rispettiva unità di fiscalizzazione – ad esempio TSE in Germania)
Attenzione:
si prega di notare che nei sistemi fino alla v1.7.7 la proprietà fiscalDocumentRevision veniva restituita nel campo fiscalisation
DocumentRevision nell’header dell’oggetto fiscalResponse. Si veda anche l’articolo: «Transazione indicata non avviata
». A partire dalla v1.7.7, la proprietà all’interno dell’oggetto fiscalResponse è stata rinominata fiscalDocumentRevision ed è ora restituita esclusivamente nell’array AdditionalFields dell’oggetto fiscalResponse-Germany.
|
|
| fiscalDocumentStartTime | M* | Ora di creazione del documento fiscale (assegnata dal sistema RetailForce o dalla rispettiva unità di fiscalizzazione – ad es. TSE in Germania) | |
| DocumentPosition | M | Informazioni relative alla rispettiva voce dello scontrino/documento (il contenuto dipende dal tipo di documento e dalla voce – documentType, positionType) | |
| {...} | |||
| pagamenti | O/M* | Informazioni relative al pagamento (l’utilizzo dipende dal tipo di documento – documentType) | |
| {...} | |||
| AdditionalHeader | O |
L'array AdditionalHeader può essere utilizzato per impostare righe aggiuntive di testo libero nell'header del documento. Dettagli per paese:
Nota: attualmente questo array è supportato solo in Italia. È possibile compilarlo anche in altri Paesi, ma non avrà alcun effetto. |
|
| AdditionalFooter | O |
L'array AdditionalFooter può essere utilizzato per impostare righe aggiuntive di testo libero nel Footer del documento. Dettagli per paese:
Nota: attualmente questo array è supportato solo in Italia. Può essere compilato anche in altri Paesi, ma non ha alcun effetto. |
|
| FiscalAdditionalFields | O | ||
Questo articolo è stato tradotto automaticamente.
Commenti
0 commenti
Accedi per aggiungere un commento.