Zum Hauptinhalt gehen

Header-Objekt RetailForce DOM

Harald Krondorfer
  • Aktualisiert

Dieser Artikel behandelt das Header-Objekt ("payments"), bzw. die Elemente im Header innerhalb des Dokumenten-Objekts (Document object).

Eine vollständige Beschreibung des RetailForce DOM (Document Object Model), sowie eine Beschreibung der einzelnen Elemente, finden sie im Downloads-Bereich der RetailForce Website (Object model documentation.pdf) im jeweilige Versions-Verzeichnis.

Header Objekt

Nachfolgend ist das gesamte Dokumenten-Schema, inkl. Beispieldaten, dargestellt. Die Sub-Objekte (positions, payments,...) sind in in den verlinkten Artikeln näher beschrieben (Links auch innerhalb des Schemas).

{
  "uniqueClientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "applicationVersion": "6.2.5",
  "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",
  "footerGraphicIndex": "5",
  "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,
  "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,
  "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",
    "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,
      "vatAmount": 0,
      "netAmount": 0,
      "grossAmount": 0
    }
  ],
  "fiscalResponse": {
    "fiscalCountry": "[1] = Austria",
    "fiscalDocumentNumber": "0",
    "taxPositions": [
      {
        "vatIdentification": 0,
        "vatLabel": "string",
        "vatPercent1": 0,
        "vatAmount": 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",
    "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,
      "type": "[0] = Item",
      "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": 0,
      "currencyIsoCode": "string",
      "caption": "string",
      "uniqueReadablePaymentIdentifier": "string",
      "foreignAmount": 0,
      "foreignAmountExchangeRate": 0,
      "additionalFields": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "paymentType": "cash",
      "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"
        ]
      }
    }
  ],
  "additionalHeader": [
    "string"
  ],
  "additionalFooter": [
    "string"
  ],
  "FiscalAdditionalFields": {}
}

Das Header-Objekt beinhaltet nachfolgende Angaben.

Informationen in der Spalte "Typ":

  • M ... erforderlich ("mandatory)
  • M* ... erforderlich in bestimmten Ländern, oder unter bestimmten Voraussetzungen
  • R ... empfohlen ("recommended")
  • O ... optional
Element Typ Beschreibung
uniqueClientId M Eindeutige ID des Clients, entspricht der Terminal-ID in der RetailForce Cloud (wird bei der Inbetriebnahme via PUT /api/v1/management/clients/byCloud zurückgegeben / zugewiesen).
applicationVersion R/M*

Version der Kassensoftware.

Achtung: beachten Sie dass in manchen Ländern (Frankreich) die Versions-Nummer im Rahmen der Zertifizierung fixiert wird. Bei einer fehlerhaften (nicht der zertifizierten Nummer entsprechenden) Angabe, ist kein Abschließen des Dokuments möglich (=Fehler). Beachten Sie hierzu auch: Zertifizierte Version.
fiscalModuleVersion O/M*

Version des Fiskal-Moduls (Trusted Fiscal Module), welche zur Erzeugung des jeweiligen Dokumentes verwendet wurde. Wird automatisch von der Middleware gesetzt, sofern nicht von der Software übermittelt.
fiscalCountryModuleVersion O/M*

Version des Länder-Moduls (Trusted Fiscal Country Module), welche zur Erzeugung des jeweiligen Dokumentes verwendet wurde. Wird automatisch von der Middleware gesetzt, sofern nicht von der Software übermittelt.
softwareName O/M*

Name der Kassensoftware, mit welcher das jeweilige Dokument erzeugt wurde. Wird automatisch von der Middleware gesetzt, sofern nicht von der Software übermittelt.
retailForceReceiptId O

Global eindeutige Belegnummer (bestehend aus terminalId und Belegnummer-Folgenummer). Kann bei der Erstellung eines Vorgangs (mit createDocument) erstellt werden.
additionalFields O

 
  additionalProp1-x O

 
automaticVatCalculation O

Über dieses Element wir die automatische Berechnung verschiedener Summen-Felder auf Positions-Ebene ausgelöst.

0 noCalculation - es findet keine automatische Berechnung statt

1 netValueCalculation - automatische Berechnung von Netto- und MwSt.-Betrag. Mindestens Bruttobetrag, sowie MwSt.-Prozentsatz/ -Kennung müssen angegeben werden.

2 grossValueCalculation - Automatische Berechnung von Brutto- und Steuerbetrag. Mindestens Nettowert und MwSt.-Prozentsatz/ -Kennung müssen angegeben werden.
allowedVatDeviation O

Kann verwendet werden, um Rundungsprobleme bei der MwSt.-Berechnung auszugleichen.

Bitte mit Vorsicht verwenden! Wenn auf einen hohen Wert eingestellt, wird die Überprüfung der Mehrwertsteuerberechnung deaktiviert!

Beispiel: "allowedVatDeviation": 0.05, erlaubt 5 Cent Abweichung zwischen Nettowert + Steuerwert = Bruttowert(+-0,05)
terminalSlaveId O

Angabe der ID eines Eingabeterminals.
footerGraphicIndex O

Über footerGraphicIndex wird ein vordefiniertes grafisches Element in der Fußzeile eines Dokumentes platziert.

Länderinformation:
documentGuid M Eindeutige Kennung des Dokuments mittels UUID / GUID. Wird auch als Verknüpfung für digitale Belege verwendet.
documentId M Eindeutige, fortlaufende Nummer des Dokuments (Beleges) innerhalb der Filiale / Niederlassung / Restaurant (kassenübergreifend), vom Kassensystem vergeben (max. 40 Zeichen).
createDate M Zeitpunkt der Dokumentenerfassung
bookDate M Buchungszeitpunkt
accountingDate O Mögliches Buchungsdatum für dieses Dokument in der Buchhaltung
processStartDate R/M* Erstellungszeitpunkt des ersten Beleges innerhalb des gesamten Prozesses (z.B. Deutschland: Erstellungszeitpunkt der ersten Kundenbestellung im Zusammenhang mit dem vorliegenden Zahlungsbeleg - siehe auch "Besonderheiten Gastronomie")
documentNumber R Eindeutige, fortlaufende Nummer des Dokuments (="Belegnummer"), vom Kassensystem vergeben.
documentNumberSeries O/M*

Bezeichnung des Nummernkreises der Belegnummer (documentNumber).

Länderinformation:
  • Spanien: documentNumberSeries muss in Spanien verpflichend angegeben werden.
    • alphanumerisch (max. 20 Zeichen)
    • verwenden Sie den folgenden Zeichensatz: 0123456789ABCDEFGHJKLMNPQRSTUVXYZ,
    • vermeiden Sie die Buchstaben I, Ñ, O und W, um die Lesbarkeit zu verbessern,
    • verwenden Sie keine Kleinbuchstaben,
    • bei Leerräumen nur ein Zeichen verwenden,
    • Textausrichtung links, ohne beginnende Leerzeichen,
    • Akzentzeichen sollen nicht verwendet werden,
    • Bindestrich "-" darf verwendet werden.
cancellationDocument M

Flag, ob das vorliegende Dokument verwendet wird, um ein anderes (früher ausgestelltes) Dokument zu stornieren

true - Storno-Dokument

false - kein Storno-Dokument 
documentReference O/M*

Wird verwendet, um auf ein anderes Dokument zu referenzieren.
  {...}

 

  
isTraining O/M*

Flag, um Tranings- / Demo-Dokumente zu markieren (Erzeugt im Trainings- / Demo-Modus der Kasse).
documentType M

Angabe des Dokumenten-Typs
documentTypeCaption M*

Bezeichnung des Dokumenten-Typs. Dient im Wesentlichen zur besseren Beschreibung, bzw. zur Erläuterung.

Länderinformation:
  • Österreich: in Österreich (AT) muss die documentTypeCaption entsprechend gesetzt werden.
    • Startbeleg,
    • Monatsbeleg,
    • Jahresbeleg,
    • Schlussbeleg
user O/M*

Angaben zum (Registrierkassen-) Benutzer.

Länderinformation:
  {...}    
salesPerson O/M*

Angaben zum Verkaufspersonal.

Länderinformation:
  {...}    
allocationGroups [] O/M*

Wird verwendet um Belege bestimmten Dingen (z.B. Tischen in der Gastronomie) zuzuweisen.

Beachten Sie dazu auch: Langanhaltender Bestellprozess Gastronomie.
partner O/M*

Informationen zum jeweiligen (Geschäfts-)Partnern des Dokument-Ausstellenden Unternehmens.

Länderinformation:
  • Québec/Kanada: Pflichtangabe bei B2B-Transaktionen
  {...}    
notes O

Erfassung von Zusatznotizen
customerCount O/M*

Kundenanzahl betreffend dieses Dokument (z.B. in der Gastronomie, die Anzahl der Gäste an der Kasse/am Tisch)
paymentTerms O

Zahlungsbedingungen / Zahlungskonditionen
  {...}    
servicePeriodStart O

Beginn des Leistungszeitraums (insbesondere bei Rechnungen)
servicePeriodEnd O

Ende des Leistungszeitraums (insbesondere bei Rechnungen)
positionCount O/M*

Anzahl der im Beleg enthaltenen Positionen (alle Positionen, inkl. item, text, booking, subTotal, total)

Siehe auch Positions-Objekt.

Länderinformation:
  • Frankreich: Pflichtangabe.
documentIssueType O/M*

Definiert die Art der Belegausgabe.

  • paper - gedrucktes Dokument
  • digitalReceipt - elektronisches Dokument (z.B. Email)
  • paperAndDigitalReceipt - Ausgabe in gedruckter und elektronischer Form
  • notIssued - Dokument wurde nicht ausgestellt
Länderinformation:
  • Kanada - Québec: Pflichtangabe.
coupon O

Möglichkeit, zusätzliche Coupons und andere Elemente am Beleg anzudrucken.
  {...}

 

  
serviceType O/M*

Angabe des Service-Types in der Gastronomie (Tisch-, Tresen-Service).

Länderinformation: 
  • Kanada - Québec: Pflichtangabe in der Gastronomie (RBF - Restaurants, Bars, Food-Trucks). Detaillierung der "activity".
isEcommerceTransaction O/M*

Angabe, ob es sich um eine E-Commerce-Transaction handelt (true / false).

Länderinformation: 
  • Kanada - Québec: Pflichtangabe.
taxPositions R

Angabe aller MwSt. Positionen des Dokuments.

Es müssen entweder alle oder keine MwSt.-Positionen angegeben werden.

Um die Steuerpositionen aus dem Dokument zu erhalten (wenn diese Eigenschaft nicht gesetzt wurde), verwenden Sie GetTaxPositions(Document, Boolean).

Hinweis Österreich: wir empfehlen, diesen Array zu verwenden, um die Steuerpositionen eines Beleges zu übermitteln, um Rundungsprobleme innerhalb des Datenerfassungsprotokolls ("DEP7") zu vermeiden.
  {...}    
fiscalResponse -

Antwort des Fiskalisierungs-Services nach Übermittlung createDocument und storeDocument.

Wir empfehlen, den Inhalt fiscalResponse in der Kassen-Datenbank zu speichern.

Hinweis: bestimmte Elemente des fiscalResponse Objektes, nach Aufruf der Funktion createDocument, müssen in das JSON-Dokument (welches an storeDocument geschickt werden soll), aufgenommen werden. Bitte inkludieren Sie NICHT das gesamte fiscalResponse Objekt!
  {...}    
fiscalDocumentNumber M*

Fiskal-Dokumentennummer (vergeben vom RetailForce System, bzw. von der jeweiligen Fiskalisierungseinheit - z.B. TSE in Deutschland)

Achtung: bitte beachten Sie, dass in Systemen bis v1.7.7 die Informationen fiscalDocumentNumber im Feld fiscalisationDocumentNumber des fiscalResponse Objektes zurück gegeben wurde. Siehe auch Artikel: "Given Transaction not started". In v1.7.7 wurde ein zusätzliches Feld fiscalDocumentNumber (string) im fiscalResponse Objekt eingeführt.
fiscalDocumentRevision O/M*

Überarbeitungsnummer des Fiskal-Dokuments (vergeben vom RetailForce System, bzw. von der jeweiligen Fiskalisierungseinheit - z.B. TSE in Deutschland)

Achtung: bitte beachten Sie, dass in Systemen bis v1.7.7 die fiscalDocumentRevision im Feld fiscalisationDocumentRevision im Header der fiscalResponse zurückgegeben wurde. Siehe auch Artikel: "Given Transaction not started". Ab v1.7.7 wurde die Eigenschaft innerhalb des fiscalResponse Objektes umbenannt in fiscalDocumentRevision und wird nur mehr im additionalFields Array der fiscalResponse-Germany zurückgegeben.
FiscalDocumentStartTime M* Zeitpunkt der Erstellung des Fiskal-Dokumentes (vergeben vom RetailForce System, bzw. von der jeweiligen Fiskalisierungseinheit - z.B. TSE in Deutschland)
positions M Angaben zur jeweiligen Beleg- / Dokumenten Position (Inhalt abhängig vom Typ des Dokuments und der Position - documentType, positionType)
  {...}    
payments O/M* Angaben zur Zahlung (Verwendung abhängig vom Typ des Dokuments - documentType)
  {...}    
additionalHeader O  
additionalFooter O  
FiscalAdditionalFields O  

 

Verwandte Beiträge

Kommentare

0 Kommentare

Bitte melden Sie sich an, um einen Kommentar zu hinterlassen.

Powered by Zendesk