Прескачане към основното съдържание

Header-object RetailForce DOM

Harald Krondorfer
  • Обновено

Тази статия разглежда обекта „Header“ („плащания“) или елементите в „Header“ в рамките на обекта „Document“.

Пълно описание на RetailForce DOM (Document Object Model), както и описание на отделните елементи, можете да намерите в раздела „Изтегляния“ на RetailForce website (Object model documentation.pdf) в съответната директория с версии.

Обект „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": {}
}

Обектът „Header“ съдържа следната информация.

Информация в колоната „Type“:

  • M ... задължително („mandatory“)
  • M* ... задължително в определени държави или при определени условия
  • R ... препоръчително („препоръчително“)
  • O ... по избор
Елемент Тип Описание
uniqueClientId M Уникален ID на клиента, съответстващ на ID-то на терминала в RetailForce Cloud (се връща/присвоява по време на пускането в експлоатация чрез PUT /api/v1/management/clients/byCloud).
applicationVersion R/M*

Версия на софтуера на касовия апарат.

Внимание: Моля, имайте предвид, че в някои държави (Франция) номерът на версията е фиксиран като част от процеса на сертифициране. Ако е посочен неправилен номер на версията (който не съответства на сертифицирания номер), не е възможно да се попълни документа (=грешка). Моля, вижте също: Сертифицирана версия .

Подробности за държавите:
ApplicationVersionId

R/M*

ID на версията на софтуера за касовия апарат.

Подробности за държавата:

  • Канада – Québec: Задължително поле. ID на версията на софтуера, предоставен/генериран от Revenu Québec. Съответства на полето „idVersi “. Моля, обърнете внимание на „Версии на софтуера Канада / Québec “!
ApplicationVersionPrevious

R/M*

ID на предишната версия на софтуера за касови апарати.

Данни за страната:

  • Канада – Québec: Задължително поле. Версия на родителския софтуер (предходна версия). Съответства на полето „versiParn “. Моля, обърнете внимание на „Версии на софтуера Канада / Québec “!
FiscalModuleVersion O/M* Версия на фискалния модул (Trusted Fiscal Module), използван за генериране на съответния документ. Задават се автоматично от middleware-то, ако не са предадени от софтуера.
FiscalCountryModuleVersion O/M* Версия на държавния модул (Trusted Fiscal Country Module), използван за генериране на съответния документ. Задават се автоматично от middleware, ако не са предадени от софтуера.
FiscalisationType O  
  подпис O Подпис
  фискален принтер   Фискален принтер
  онлайн   Онлайн
  подпис с онлайн   Подпис с онлайн връзка
  без фискализация   Без фискализация
Тип фискализация Италия O  
  принтер O Телематичен касов апарат
retailForceReceiptId O Глобално уникален номер на касовата бележка (състоящ се от terminalId и пореден номер на касовата бележка). Може да бъде създаден при създаване на транзакция (с createDocument).
AdditionalFields O  
  additionalProp1-x O  
automaticVatCalculation O

Този елемент задейства автоматичното изчисляване на различни полета със суми на ниво позиция.

0 noCalculation – не се извършва автоматично изчисление

1 netValueCalculation – автоматично изчисляване на нетната сума и сумата на Vat. Трябва да бъдат посочени поне брутната сума и процентът на Vat/идентификационният номер.

2 grossValueCalculation – автоматично изчисляване на брутната сума и сумата на данъка. Трябва да бъдат посочени поне нетната стойност и процентът на Vat/идентификационният номер на Vat.
AllowedVatDeviation O

Може да се използва за компенсиране на закръглявания при изчисляването на Vat.

Моля, използвайте с внимание! Ако е зададена висока стойност, проверката на изчислението на Vat се деактивира!

Пример: „AllowedVatDeviation”: 0,05, позволява отклонение от 5 цента между нетната стойност + стойността на ДДС = брутна стойност (+-0,05)
TerminalSlaveId O Определяне на ID-то на терминал за въвеждане.
cashRegisterSerialNumber

O

 Сериен номер на касовото устройство. Това поле идентифицира конкретния физически хардуер на касовото устройство, използван за обработка на транзакцията.
footerGraphicIndex O

Чрез footerGraphicIndex в долния колонтитул на документа се поставя предварително дефиниран графичен елемент.

Данни за държавата:

  • Италия: управлява функцията „Footer Graphico“ на устройствата EPSON RT.
AuditLogEntryType   Определя типа на записа в одитния дневник, когато самият документ представлява запис в одитния дневник.
amount   Сума, свързана със заглавната част на документа (например за целите на одиторския дневник).
identifier   Общо поле за идентификация (например за целите на одиторския дневник).
DocumentGuid M Уникален идентификатор на документа, използващ UUID / GUID. Използва се също като линк за електронни разписки.
DocumentId M Уникален, последователен номер на документа (разписката) в рамките на клона / филиала / ресторанта (за всички касови апарати), присвоен от касовата система (макс. 40 символа).
CreateDate M Време на създаване на документа
BookDate М Време на резервацията
AccountingDate O Възможна дата на записване на този документ в счетоводството
ProcessStartDate R/M* Време на създаване на първия документ за постъпление в рамките на целия процес (например Германия: Време на създаване на първата клиентска поръчка, свързана с настоящия документ за постъпление – вижте също „Специфични характеристики за ресторантьорството“)
DocumentNumber R/M* Уникален, последователен номер на документа (= „номер на разписката“), присвоен от касовата система.
documentNumberSeries O/M*

Наименование на серията номера на касовия номер (DocumentNumber).

Данни за страната:

  • Испания: documentNumberSeries трябва да бъде посочено като задължително в Испания (повече информация: „Номера и серии на фактурите в Испания “).
    • буквено-цифров (макс. 20 символа)
    • използвайте следния набор от символи: 0123456789ABCDEFGHJKLMNPQRSTUVXYZ,
    • избягвайте буквите I, Ñ, O и W, за да подобрите четливостта,
    • не използвайте малки букви,
    • използвайте само един символ за интервали,
    • изравняване на текста вляво, без начални интервали,
    • не трябва да се използват акценти,
    • може да се използва тире „-“.
cancellationDocument M

Flag дали настоящият документ се използва за анулиране на друг (издаден по-рано) документ

true – Документ за анулиране

false – Няма документ за анулиране
FailedToPay

O

 Boolean flag (true/false), който показва дали плащането по документа е неуспешно.
documentReference O/M* Използва се за препратка към друг документ.
  {...}    
IsTraining O/M* Flag за маркиране на документи за обучение/демонстрация (генерирани в режим на обучение/демонстрация на касовия апарат).
TestCaseNumber

O/M*

Поле за посочване на номер на тестов случай за целите на сертифицирането.

Данни за държавата:

  • Канада – Québec: Номер на тестовия случай в среда DEV или ESSAI. Повече информация в статията „Комуникация с WEB-SRM “.
documentType O Посочване на типа на документа
documentTypeCaption M*

Описание на типа на документа. Служи основно за по-добро описание или пояснение.

Данни за държавата:

  • Австрия: в Австрия (AT) documentTypeCaption трябва да бъде зададен съответно.
    • Начална разписка,
    • месечна разписка,
    • Годишна разписка,
    • Окончателна разписка
потребител O/M*

Информация за потребителя (на касовия апарат).

Данни за държавата:
  {...}    
SalesPerson O/M*

Информация за търговския персонал.

Данни за държавата:
  {...}    
AllocationGroups [] O/M*

Използва се за присвояване на разписки към конкретни обекти (например маси в ресторантьорството).

Вижте също: Дългосрочен процес на поръчки в ресторантьорството.

Подробности за страната:

  • Канада – Québec: Елементът е свързан с полето „noTabl “ в схемата на WEB-SRM. Допуска се само 1 запис с максимум 5 буквено-цифрови символа.
партньор O/M*

Информация за съответните (бизнес) партньори на компанията, издала документа.

Данни за страната:

  • Канада – Québec: Задължително поле при B2B транзакции
  • Португалия: Задължително поле при B2B транзакции
addressType   (В partner обект) Ново незадължително поле за посочване на типа на адреса (например адрес за фактуриране).
  {...}    
бележки O Записване на допълнителни бележки
CustomerCount O/M*

Брой клиенти, свързани с този документ (например в ресторантьорството – броят на гостите на касата/масата)

Данни за държавата:

  • Канада – Québec: Елементът е свързан с полето „nbClint “ в схемата на WEB-SRM.
PaymentTerms O Условия за плащане
  {...}    
ServicePeriodStart O

Начало на периода на услугата (особено за фактури)

Данни за държавата:

  • Португалия: Задължително е да се посочи периодът на услугата за фактурите („documentType”: „[1] = Invoice”)
ServicePeriodEnd O

Край на периода на услугата (особено за фактури)

Данни за страната:

  • Португалия: Задължително е да се посочи периодът на услугата за фактури („documentType”: „[1] = Invoice”)
PositionCount O/M*

Брой позиции, съдържащи се в разписката (всички позиции, включително артикул, текст, резервация, subTotal, total)

Вижте също „Позиционен обект“.

Данни за държавата:

  • Франция: Задължително поле.
DocumentIssueType O/M*

Определя вида на издаване на разписката.

  • paper – печатен документ
  • digitalReceipt – електронен документ (например имейл)
  • paperAndDigitalReceipt – издаване в печатна и електронна форма
  • notIssued – документът не е издаден

Данни за държавата:

  • Канада – Québec: Задължително поле.
coupon O Възможност за отпечатване на допълнителни купони и други елементи върху касовата бележка.
  {...}    
serviceType O/M*

Спецификация на типа услуга в гастрономията (обслужване на маса, на бар).

Възможни стойности (да се спазва CamelCase!)

  • CounterService – Обслужване на бара
  • DeliveryByOperator – Доставка от оператор
  • OrderThroughDigitalPlatform – Доставка чрез дигитална платформа (трета страна)
  • TableService – Обслужване на маса / обслужване на маса

Данни за страната:

  • Канада – Québec: Задължително поле в гастрономията (RBF – ресторанти, барове, фургони за хранене). Подробности за „дейност“.
    Съответствие (RetailForce DOM – WEB-SRM):
    • CounterService – „CMP“
    • DeliveryByOperator – „LVR“
    • Поръчка чрез дигитална платформа – „LVT“
    • Обслужване на маса – „TBL“
IsEcommerceTransaction O/M*

Показва дали става въпрос за електронна търговска транзакция (true / false).

Данни за държавата:

  • Канада – Québec: Задължително поле при транзакции за електронна търговия.
TaxPositions R

Спецификация на всички позиции по Vat в документа.

Трябва да бъдат посочени или всички, или нито една позиция за Vat.

За да извлечете позициите по ДДС от документа (когато това свойство не е зададено), използвайте GetTaxPositions(Document, boolean).

Забележка за Австрия: Препоръчваме използването на този масив за предаване на позициите по ДДС на касовата бележка, за да се избегнат проблеми със закръгляването в протокола за записване на данни („DEP7“).
  {...}    
fiscalResponse -

Отговор на фискалната служба след предаване на createDocument и storeDocument.

Препоръчваме съдържанието на fiscalResponse да се съхранява в базата данни на касовия апарат.

Забележка: определени елементи от обекта fiscalResponse, след извикване на функцията createDocument , трябва да бъдат включени в JSON документа (който трябва да бъде изпратен към storeDocument ). Моля, НЕ включвайте целия обект fiscalResponse!
  {...}    
fiscalDocumentNumber M*

Номер на фискалния документ (присвоен от RetailForce system или от съответната фискална единица – например TSE в Германия)

Внимание: Моля, имайте предвид, че в системите до версия v1.7.7 информацията fiscalDocumentNumber се връщаше в полето fiscalisation DocumentNumber на обекта fiscalResponse. Вижте също статията: „Дадената транзакция не е стартирана “. В версия v1.7.7 в обекта fiscalResponse беше въведено допълнително поле fiscalDocumentNumber (string).
fiscalDocumentRevision O/M*

Номер на ревизия на фискалния документ (присвоен от RetailForce system или от съответната фискална единица – например TSE в Германия)

Внимание: Моля, имайте предвид, че в системите до версия v1.7.7 fiscalDocumentRevision се връщаше в полето fiscalisation DocumentRevision в header-то на fiscalResponse. Вижте също статията: „Дадената транзакция не е започнала “. От версия v1.7.7 нататък свойството в обекта fiscalResponse беше преименувано на fiscalDocumentRevision и сега се връща само в масива AdditionalFields на fiscalResponse-Germany.
fiscalDocumentStartTime M* Време на създаване на фискалния документ (присвоено от RetailForce system или от съответната фискална единица – например TSE в Германия)
позиции M Информация за съответната позиция в касовата бележка/документа (съдържанието зависи от типа на документа и позицията – documentType, positionType)
  {...}    
плащания O/M* Информация за плащането (използването зависи от типа на документа – documentType)
  {...}    
AdditionalHeader O

Масивът AdditionalHeader може да се използва за задаване на допълнителни редове със свободен текст в заглавната част на документа.

Подробности за страните:

Забележка: Към момента този масив се поддържа само в Италия. Може да се попълва и в други държави, но няма ефект.
AdditionalFooter O

Масивът AdditionalFooter може да се използва за задаване на допълнителни редове със свободен текст в долния Footer на документа.

Подробности за страната:

Забележка: Към момента този масив се поддържа само в Италия. Може да се попълва и в други държави, но няма ефект.
FiscalAdditionalFields O  

 

Тази статия е преведена автоматично.

Подобни статии

Коментари

0 коментара

Влезте в услугата, за да оставите коментар.

Powered by Zendesk