Preskoči na glavno vsebino

Objekt glave RetailForce DOM

Harald Krondorfer
  • Posodobljen

Ta članek obravnava objekt »Header« (»plačila«) oziroma elemente v objektu »Header« znotraj objekta »Document«.

Celoten opis modela RetailForce DOM (Document Object Model) ter opis posameznih elementov najdete v razdelku »Prenosi« na RetailForce website (Object model documentation.pdf) v ustreznem imeniku različic.

Objekt »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": {}
}

Objekt »Header« vsebuje naslednje informacije.

Podatki v stolpcu »Type«:

  • M ... obvezno („mandatory“)
  • M* ... obvezno v nekaterih državah ali pod določenimi pogoji
  • R ... priporočeno („priporočeno“)
  • O ... neobvezno
Element Tip Opis
uniqueClientId M Edinstvena identifikacijska številka stranke, ki ustreza identifikacijski številki terminala v RetailForce Cloud (se vrne/dodeli med zagonom prek PUT /api/v1/management/clients/byCloud).
applicationVersion R/M*

Različica programske opreme blagajne.

Pozor: Upoštevajte, da je v nekaterih državah (Francija) številka različice fiksna kot del certifikacijskega postopka. Če je navedena napačna številka različice (ki ne ustreza certificirani številki), dokumenta ni mogoče zaključiti (=napaka). Glejte tudi: Certificirana različica .

Podatki o državi:
ApplicationVersionId

R/M*

ID različice programske opreme blagajne.

Podrobnosti o državi:
ApplicationVersionPrevious

R/M*

ID prejšnje različice programske opreme za blagajno.

Podrobnosti o državi:
FiscalModuleVersion O/M* Različica fiskalnega modula (Trusted Fiscal Module), ki se uporablja za ustvarjanje zadevnega dokumenta. Če ga programska oprema ne posreduje, ga samodejno nastavi middleware.
FiscalCountryModuleVersion O/M* Različica državnega modula (Trusted Fiscal Country Module), ki se uporablja za ustvarjanje zadevnega dokumenta. Če ga programska oprema ne posreduje, ga samodejno nastavi middleware.
FiscalisationType O  
  podpis O Podpis
  fiskalni tiskalnik   Fiskalni tiskalnik
  spletno   Spletni
  podpis s spletno povezavo   Podpis s spletno povezavo
  brez fiskalizacije   Brez fiskalizacije
Vrsta davčne obdavčitve Italija O  
  tiskalnik O Telematski registrator
retailForceReceiptId O Globalno edinstvena številka potrdila (sestavljena iz terminalId in zaporedne številke potrdila). Lahko se ustvari ob ustvarjanju transakcije (z createDocument).
AdditionalFields O  
  additionalProp1-x O  
automaticVatCalculation O

Ta element sproži samodejni izračun različnih seštevkov na ravni pozicije.

0 noCalculation – avtomatski izračun se ne izvede

1 netValueCalculation – avtomatski izračun neto zneska in zneska Vat. Določiti je treba vsaj bruto znesek ter odstotek Vat oziroma identifikacijsko številko.

2 grossValueCalculation – avtomatski izračun bruto zneska in zneska davka. Navesti je treba vsaj neto vrednost ter stopnjo Vat/identifikacijsko številko.
AllowedVatDeviation O

Lahko se uporabi za izravnavo zaokroževalnih napak pri izračunu Vat.

Uporabljajte previdno! Če je vrednost nastavljena previsoko, se preverjanje izračuna Vat onemogoči!

Primer: »AllowedVatDeviation«: 0,05, omogoča 5-centno odstopanje med neto vrednostjo + davkom = bruto vrednostjo (+-0,05)
TerminalSlaveId O Določitev ID vhodnega terminala.
cashRegisterSerialNumber

O

 Serijska številka blagajniške naprave. To polje identificira konkretno fizično blagajniško opremo, ki se uporablja za obdelavo transakcije.
footerGraphicIndex O

Prek footerGraphicIndex se v nogo dokumenta vstavi vnaprej določen grafični element.

Podatki o državi:
AuditLogEntryType   Določa vrsto vnosa v revizijski dnevnik, kadar je dokument sam po sebi vnos v revizijski dnevnik.
amount   Znesek, povezan s headerjem dokumenta (npr. za namene revizijskega dnevnika).
identifier   Splošno identifikacijsko polje (npr. za namene revizijskega dnevnika).
DocumentGuid M Edinstven identifikator dokumenta z uporabo UUID / GUID. Uporablja se tudi kot povezava za digitalne potrdila.
DocumentId M Edinstvena, zaporedna številka dokumenta (računa) znotraj poslovalnice / podružnice / restavracije (v vseh blagajnah), ki jo dodeli blagajniški sistem (največ 40 znakov).
CreateDate M Čas nastanka dokumenta
BookDate M Čas rezervacije
AccountingDate O Možni datum knjiženja tega dokumenta v računovodstvu
ProcessStartDate R/M* Čas nastanka prvega prejemka v okviru celotnega procesa (npr. Nemčija: čas nastanka prvega naročila stranke v povezavi s tem prejemkom plačila – glej tudi »Posebnosti v gostinstvu«)
DocumentNumber R/M* Edinstvena, zaporedna številka dokumenta (= »številka potrdila«), ki jo dodeli blagajniški sistem.
documentNumberSeries O/M*

Ime številčne serije številke potrdila (DocumentNumber).

Podrobnosti o državi:

  • Španija: v Španiji je treba obvezno navesti documentNumberSeries (več informacij: »Številke računov in serije v Španiji «).
    • alfanumerično (največ 20 znakov)
    • uporabite naslednji nabor znakov: 0123456789ABCDEFGHJKLMNPQRSTUVXYZ,
    • za boljšo berljivost se izogibajte črkam I, Ñ, O in W,
    • ne uporabljajte malih črk,
    • za presledke uporabite le en znak,
    • besedilo poravnajte levo, brez vodilnih presledkov,
    • akcentov ne uporabljajte,
    • vezaj »-« se lahko uporablja.
cancellationDocument M

Flag, ali se ta dokument uporablja za razveljavitev drugega (prej izdanega) dokumenta

true – dokument o razveljavitvi

false – Ni dokumenta o preklicu
FailedToPay

O

 Boolean flag (true/false), ki označuje, ali je prišlo do napake pri plačilu za dokument.
documentReference O/M* Uporablja se za sklicevanje na drug dokument.
  {...}    
IsTraining O/M* Flag za označevanje dokumentov za usposabljanje/predstavitev (ustvarjenih v načinu usposabljanja/predstavitve blagajne).
TestCaseNumber

O/M*

Polje za navedbo številke testnega primera za namene certifikacije.

Podrobnosti o državi:

  • Kanada – Québec: Številka testnega primera v okolju DEV ali ESSAI. Več informacij v članku »Komunikacija z WEB-SRM «.
documentType O Določitev vrste dokumenta
documentTypeCaption M*

Opis vrste dokumenta. Služi predvsem za boljši opis ali pojasnilo.

Podatki o državi:

  • Avstrija: v Avstriji (AT) je treba documentTypeCaption ustrezno nastaviti.
    • Začetni račun,
    • mesečni prejemek,
    • Letni potrdilo,
    • končni potrdilo
uporabnik O/M*

Podatki o uporabniku (blagajne).

Podatki o državi:
  {...}    
SalesPerson O/M*

Podatki o prodajnem osebju.

Podatki o državi:
  {...}    
AllocationGroups [] O/M*

Uporablja se za dodeljevanje prejemkov določenim stvarem (npr. mizam v gostinstvu).

Glej tudi: Dolgotrajni postopek naročanja v gostinstvu.

Podrobnosti po državah:

  • Kanada – Québec: Element je povezan s poljem »noTabl « v shemi WEB-SRM. Dovoljen je le 1 vnos z največ 5 alfanumeričnimi znaki.
partner O/M*

Podatki o posameznih (poslovnih) partnerjih podjetja, ki je izdalo dokument.

Podrobnosti o državi:

  • Kanada – Québec: Obvezno polje v primeru transakcij B2B
  • Portugalska: Obvezno polje v primeru transakcij med podjetji (B2B)
addressType   (v partner objektu) Novo neobvezno polje za določitev vrste naslova (npr. naslov za izstavitev računa).
  {...}    
opombe O Zabeleževanje dodatnih opomb
CustomerCount O/M*

Število strank v zvezi s tem dokumentom (npr. v gostinstvu število gostov na blagajni/mizi)

Podatki o državi:

  • Kanada – Québec: Element je povezan s poljem »nbClint « v shemi WEB-SRM.
PaymentTerms O Pogoji plačila / plačilni pogoji
  {...}    
ServicePeriodStart O

Začetek obdobja storitve (zlasti za račune)

Podatki o državi:

  • Portugalska: Obvezno je navesti obdobje storitve za račune („documentType“: „[1] = Invoice“)
ServicePeriodEnd O

Konec obdobja storitve (zlasti za račune)

Podrobnosti o državi:

  • Portugalska: Obvezno je navesti obdobje storitve za račune („documentType“: „[1] = Invoice“)
PositionCount O/M*

Število postavk na računu (vse postavke, vključno s postavko, besedilom, rezervacijo, vmesnim seštevkom in skupnim zneskom)

Glej tudi Objekt pozicije.

Podrobnosti o državi:

  • Francija: Obvezno polje.
DocumentIssueType O/M*

Opredeljuje vrsto izdaje potrdila.

  • paper – tiskani dokument
  • digitalReceipt – elektronski dokument (npr. e-pošta)
  • paperAndDigitalReceipt – izdaja v tiskani in elektronski obliki
  • notIssued – dokument ni bil izdan

Podatki o državi:

  • Kanada – Québec: Obvezno polje.
coupon O Možnost tiskanja dodatnih kuponov in drugih elementov na računu.
  {...}    
serviceType O/M*

Določitev vrste storitve v gostinstvu (strežba pri mizi, strežba na pultu).

Možne vrednosti (upoštevajte CamelCase!)

  • CounterService – Postrežba na pultu
  • DeliveryByOperator – Dostava s strani ponudnika
  • OrderThroughDigitalPlatform – Dostava prek digitalne platforme (tretja stranka)
  • TableService – strežba pri mizi / strežba pri mizi

Podrobnosti o državi:

  • Kanada – Québec: Obvezno polje v gastronomiji (RBF – restavracije, bari, food trucki). Podrobnosti o »dejavnosti«.
    Mapiranje (RetailForce DOM – WEB-SRM):
    • CounterService – »CMP«
    • DeliveryByOperator – »LVR«
    • Naročilo prek digitalne platforme – »LVT«
    • Postrežba pri mizi – »TBL«
IsEcommerceTransaction O/M*

Navedba, ali gre za transakcijo v e-trgovini (true / false).

Podatki o državi:

  • Kanada – Québec: Obvezno polje v primeru transakcij e-trgovine.
TaxPositions R

Navedba vseh Vat-položajev v dokumentu.

Določiti je treba bodisi vse bodisi nobene Vat-položaje.

Za pridobitev davčnih položajev iz dokumenta (če ta lastnost ni bila nastavljena) uporabite GetTaxPositions(Document, boolean).

Opomba za Avstrijo: Priporočamo uporabo tega niza za prenos davčnih postavk računa, da se izognete težavam z zaokroževanjem v protokolu za beleženje podatkov („DEP7“).
  {...}    
fiscalResponse -

Odgovor fiskalne službe po pošiljanju createDocument in storeDocument.

Priporočamo, da vsebino fiscalResponse shranite v bazo podatkov blagajne.

Opomba: nekateri elementi objekta fiscalResponse morajo biti po klicu funkcije createDocument vključeni v dokument JSON (ki ga je treba poslati v storeDocument ). Prosimo, NE vključujte celotnega objekta fiscalResponse!
  {...}    
fiscalDocumentNumber M*

Številka fiskalnega dokumenta (dodeli jo RetailForce system ali ustrezna fiskalna enota – npr. TSE v Nemčiji)

Pozor: Upoštevajte, da so v sistemih do različice v1.7.7 podatki fiscalDocumentNumber bili vrnjeni v polju fiscalisation DocumentNumber objekta fiscalResponse. Glejte tudi članek: »Dana transakcija ni bila začeta «. V različici v1.7.7 je bilo v objektu fiscalResponse uvedeno dodatno polje fiscalDocumentNumber (string).
fiscalDocumentRevision O/M*

Številka revizije davčnega dokumenta (dodeljena s strani RetailForce system ali zadevne davčne enote – npr. TSE v Nemčiji)

Pozor: Upoštevajte, da je bila v sistemih do različice v1.7.7 lastnost fiscalDocumentRevision vrnjena v polju fiscalisation DocumentRevision v headerju objekta fiscalResponse. Glejte tudi članek: »Dana transakcija ni bila začeta «. Od različice v1.7.7 je bila lastnost znotraj objekta fiscalResponse preimenovana v fiscalDocumentRevision in se zdaj vrne le v nizu AdditionalFields objekta fiscalResponse-Germany.
fiscalDocumentStartTime M* Čas nastanka davčnega dokumenta (določi ga RetailForce system ali ustrezna davčna enota – npr. TSE v Nemčiji)
pozicije M Podatki o posamezni postavki na računu/dokumentu (vsebina je odvisna od vrste dokumenta in postavke – documentType, positionType)
  {...}    
plačila O/M* Podatki o plačilu (uporaba je odvisna od vrste dokumenta – documentType)
  {...}    
AdditionalHeader O

AdditionalHeader se lahko uporabi za nastavitev dodatnih vrstic prostega besedila v glavi dokumenta.

Podrobnosti po državah:

Opomba: Trenutno je ta niz podprt le v Italiji. Izpolniti ga je mogoče tudi v drugih državah, vendar nima nobenega učinka.
AdditionalFooter O

AdditionalFooter se lahko uporabi za nastavitev dodatnih vrstic prostega besedila v nogi dokumenta.

Podrobnosti po državah:

Opomba: Trenutno je ta niz podprt le v Italiji. Izpolniti ga je mogoče tudi v drugih državah, vendar nima nobenega učinka.
FiscalAdditionalFields O  

 

Ta članek je bil samodejno preveden.

Sorodni sklopi

Komentar

0 komentarjev

Za dodajanje komentarja prosimo kliknite Vpis.

Založba Zendesk