Niniejszy artykuł dotyczy obiektu header („payments”) oraz elementów zawartych w headerze obiektu Document.
Pełny opis modelu obiektowego dokumentu (RetailForce DOM) RetailForce, a także opis poszczególnych elementów, można znaleźć w sekcji „Pliki do pobrania” na stronie internetowej RetailForce (dokument „Object model documentation.pdf”) w odpowiednim katalogu wersji.
Obiekt „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": {}
}Obiekt „Header” zawiera następujące informacje.
Informacje w kolumnie „Typ”:
- M … wymagane („obowiązkowe”)
- M* … wymagane w niektórych krajach lub pod pewnymi warunkami
- R ... zalecane („zalecane”)
- O … opcjonalne
| Element | Typ | Opis | |
| uniqueClientId | M | Unikalny ID klienta, odpowiadający identyfikatorowi terminala w RetailForce Cloud (zwracany/przypisywany podczas uruchamiania za pomocą żądania PUT /api/v1/management/clients/byCloud). | |
| applicationVersion | R/M* |
Wersja oprogramowania kasy fiskalnej.
Uwaga:
Należy pamiętać, że w niektórych krajach (np. we Francji) numer wersji jest ustalony w ramach procesu certyfikacji. Jeśli podany zostanie nieprawidłowy numer wersji (niezgodny z numerem certyfikowanym), nie będzie możliwe uzupełnienie dokumentu (=błąd). Proszę zapoznać się również z sekcją: Wersja certyfikowana
.
Szczegóły dotyczące kraju:
|
|
| ApplicationVersionId | R/M* |
ID wersji oprogramowania kasy fiskalnej. Szczegóły dotyczące kraju:
|
|
| ApplicationVersionPrevious | R/M* |
ID poprzedniej wersji oprogramowania kasowego. Szczegóły dotyczące kraju:
|
|
| FiscalModuleVersion | O/M* | Wersja modułu fiskalnego (zaufanego modułu fiskalnego) użytego do wygenerowania danego dokumentu. Ustawiana automatycznie przez middleware, jeśli nie została przekazana przez oprogramowanie. | |
| FiscalCountryModuleVersion | O/M* | Wersja modułu krajowego (zaufanego modułu fiskalnego kraju) wykorzystanego do wygenerowania danego dokumentu. Ustawiana automatycznie przez middleware, jeśli nie została przekazana przez oprogramowanie. | |
| FiscalisationType | O | ||
| podpis | O | Podpis | |
| fiscalPrinter | Drukarka fiskalna | ||
| online | Online | ||
| podpis z połączeniem internetowym | Podpis z połączeniem internetowym | ||
| brak rejestracji fiskalnej | Brak fiskalizacji | ||
| Typ fiskalizacji: Włochy | O | ||
| drukarka | O | Rejestrator telematyczny | |
| retailForceReceiptId | O | Globalnie unikalny numer paragonu (składający się z terminalId oraz kolejnego numeru paragonu). Może zostać wygenerowany podczas tworzenia transakcji (za pomocą funkcji createDocument). | |
| AdditionalFields | O | ||
| additionalProp1-x | O | ||
| automaticVatCalculation | O |
Element ten uruchamia automatyczne obliczanie różnych pól sumarycznych na poziomie pozycji. 0 noCalculation – nie odbywa się żadne automatyczne obliczanie 1 netValueCalculation – automatyczne obliczanie kwoty netto i kwoty podatku Vat. Należy podać co najmniej kwotę brutto oraz stawkę Vat lub numer identyfikacyjny. 2 grossValueCalculation – automatyczne obliczanie kwoty brutto i kwoty podatku. Należy podać co najmniej wartość netto oraz stawkę Vat lub identyfikator. |
|
| AllowedVatDeviation | O |
Można wykorzystać w celu skompensowania błędów zaokrąglenia w obliczeniach podatku Vat. Prosimy o ostrożność! Ustawienie wysokiej wartości powoduje wyłączenie sprawdzania poprawności obliczeń podatku Vat! Przykład: „AllowedVatDeviation”: 0,05 – dopuszcza odchylenie o 5 centów między wartością netto a wartością podatku, co daje wartość brutto (+-0,05) |
|
| TerminalSlaveId | O | Określenie ID terminala wejściowego. | |
| cashRegisterSerialNumber | O |
Numer seryjny urządzenia kasowego. Pole to identyfikuje konkretny sprzęt kasowy użyty do przetworzenia transakcji. | |
| footerGraphicIndex | O |
Za pomocą parametru „footerGraphicIndex” w Footerze dokumentu umieszczany jest z góry zdefiniowany element graficzny. Szczegóły dotyczące kraju:
|
|
| AuditLogEntryType | Określa typ wpisu w dzienniku audytowym, gdy sam dokument stanowi wpis w dzienniku audytowym. | ||
| amount | Kwota powiązana z nagłówkiem dokumentu (np. na potrzeby dziennika audytowego). | ||
| identifier | Ogólne pole identyfikacyjne (np. na potrzeby dziennika audytowego). | ||
| DocumentGuid | M | Unikalny identyfikator dokumentu oparty na UUID / GUID. Służy również jako link do cyfrowych paragonów. | |
| DocumentId | M | Unikalny, sekwencyjny numer dokumentu (paragonu) w obrębie oddziału / filii / restauracji (we wszystkich kasach), przypisany przez system kasowy (maks. 40 znaków). | |
| CreateDate | M | Czas utworzenia dokumentu | |
| BookDate | M | Data rezerwacji | |
| AccountingDate | O | Możliwa data księgowania niniejszego dokumentu | |
| ProcessStartDate | R/M* | Czas utworzenia pierwszego dowodu wpływu w ramach całego procesu (np. Niemcy: czas utworzenia pierwszego zamówienia klienta związanego z niniejszym dowodem wpływu – zob. również „Cechy szczególne gastronomii”) | |
| DocumentNumber | R/M* | Unikalny, kolejny numer dokumentu (= „numer pokwitowania”), nadany przez system kasowy. | |
| documentNumberSeries | O/M* |
Nazwa serii numeracyjnej numeru paragonu (DocumentNumber). Szczegóły dotyczące poszczególnych krajów:
|
|
| cancellationDocument | M |
Flag wskazująca, czy niniejszy dokument służy do unieważnienia innego (wcześniej wydanego) dokumentu true – dokument unieważniający false – brak dokumentu unieważniającego |
|
| FailedToPay | O |
Boolean flag (true/false), wskazująca, czy płatność za dokument nie powiodła się. |
|
| documentReference | O/M* | Służy do odwołania się do innego dokumentu. | |
| {...} | |||
| IsTraining | O/M* | Flag służąca do oznaczania dokumentów szkoleniowych lub demonstracyjnych (generowanych w trybie szkoleniowym lub demonstracyjnym kasy). | |
| TestCaseNumber | O/M* |
Pole służące do podania numeru przypadku testowego na potrzeby certyfikacji. Szczegóły dotyczące kraju:
|
|
| documentType | O | Określenie typu dokumentu | |
| documentTypeCaption | M* |
Opis typu dokumentu. Służy przede wszystkim lepszemu opisaniu lub wyjaśnieniu. Informacje dotyczące poszczególnych krajów:
|
|
| użytkownik | O/M* |
Informacje dotyczące użytkownika (kasy fiskalnej). Dane dotyczące kraju:
|
|
| {...} | |||
| SalesPerson | O/M* |
Informacje dotyczące personelu sprzedaży. Szczegóły dotyczące kraju:
|
|
| {...} | |||
| AllocationGroups [] | O/M* |
Służy do przypisywania paragonów do konkretnych elementów (np. stolików w gastronomii). Zobacz również: Proces realizacji zamówień długoterminowych w gastronomii. Szczegóły dotyczące kraju:
|
|
| partner | O/M* |
Informacje dotyczące odpowiednich partnerów (biznesowych) firmy wystawiającej dokument. Szczegóły dotyczące kraju:
|
|
| addressType | (w partner obiekcie) Nowe pole opcjonalne służące do określenia typu adresu (np. adres rozliczeniowy). |
||
| {...} | |||
| uwagi | O | Rejestrowanie dodatkowych uwag | |
| CustomerCount | O/M* |
Liczba klientów dotycząca niniejszego dokumentu (np. w gastronomii – liczba gości przy kasie/stole) Szczegóły dotyczące kraju:
|
|
| PaymentTerms | O | Warunki płatności / zasady płatności | |
| {...} | |||
| ServicePeriodStart | O |
Początek okresu świadczenia usługi (zwłaszcza w przypadku faktur) Informacje o kraju:
|
|
| ServicePeriodEnd | O |
Koniec okresu świadczenia usługi (zwłaszcza w przypadku faktur) Szczegóły dotyczące kraju:
|
|
| PositionCount | O/M* |
Liczba pozycji zawartych w dokumencie (wszystkie pozycje, w tym pozycja, tekst, rezerwacja, suma częściowa, suma całkowita) Zob. również obiekt pozycji. Szczegóły dotyczące kraju:
|
|
| DocumentIssueType | O/M* |
Określa rodzaj wystawienia pokwitowania.
Dane dotyczące kraju:
|
|
| coupon | O | Możliwość wydrukowania dodatkowych kuponów i innych elementów na paragonie. | |
| {...} | |||
| serviceType | O/M* |
Określenie rodzaju obsługi w gastronomii (obsługa przy stoliku, przy ladzie). Możliwe wartości (należy zachować konwencję CamelCase!)
Szczegóły dotyczące kraju:
|
|
| IsEcommerceTransaction | O/M* |
Wskazanie, czy jest to transakcja e-commerce (true / fałsz). Szczegóły dotyczące kraju:
|
|
| TaxPositions | R |
Wskazanie wszystkich pozycji Vat w dokumencie. Należy określić wszystkie pozycje Vat lub nie określać żadnej. Aby uzyskać pozycje podatkowe z dokumentu (gdy ta właściwość nie została ustawiona), należy użyć funkcji GetTaxPositions(Document, boolean).
Uwaga dotycząca Austrii:
Zalecamy korzystanie z tej tablicy do przesyłania pozycji podatkowych paragonu, aby uniknąć problemów z zaokrągleniem w protokole rejestracji danych („DEP7”).
|
|
| {...} | |||
| fiscalResponse | - |
Odpowiedź serwisu fiskalizacyjnego po przesłaniu funkcji createDocument i storeDocument. Zalecamy zapisanie zawartości obiektu fiscalResponse w bazie danych kasy fiskalnej.
Uwaga:
niektóre elementy obiektu fiscalResponse, po wywołaniu funkcji createDocument
, muszą zostać uwzględnione w dokumencie JSON (który należy przesłać do funkcji storeDocument
). Prosimy NIE dołączać całego obiektu fiscalResponse!
|
|
| {...} | |||
| fiscalDocumentNumber | M* |
Numer dokumentu fiskalnego (przypisany przez RetailForce system lub przez odpowiednią jednostkę fiskalną – np. TSE w Niemczech)
Uwaga:
Prosimy pamiętać, że w systemach do wersji v1.7.7 informacja fiscalDocumentNumber była zwracana w polu fiscalisation
DocumentNumber obiektu fiscalResponse. Zobacz również artykuł: „Podana transakcja nie została rozpoczęta
”. W wersji v1.7.7 w obiekcie fiscalResponse wprowadzono dodatkowe pole fiscalDocumentNumber (string).
|
|
| fiscalDocumentRevision | O/M* |
Numer rewizji dokumentu fiskalnego (przypisany przez RetailForce system lub przez odpowiednią jednostkę fiskalną – np. TSE w Niemczech)
Uwaga:
Proszę pamiętać, że w systemach do wersji v1.7.7 wartość „fiscalDocumentRevision” była zwracana w polu „fiscalisation
DocumentRevision” w hederze obiektu „fiscalResponse”. Zobacz również artykuł: „Podana transakcja nie została rozpoczęta
”. Od wersji v1.7.7 właściwość w obiekcie „fiscalResponse” została przemianowana na „fiscalDocumentRevision” i jest obecnie zwracana wyłącznie w tablicy „AdditionalFields” obiektu „fiscalResponse-Germany”.
|
|
| fiscalDocumentStartTime | M* | Czas utworzenia dokumentu fiskalnego (przypisany przez RetailForce system lub przez odpowiednią jednostkę fiskalną – np. TSE w Niemczech) | |
| pozycje | M | Informacje dotyczące danej pozycji paragonu/dokumentu (zawartość zależy od typu dokumentu i pozycji – documentType, positionType) | |
| {...} | |||
| płatności | O/M* | Informacje dotyczące płatności (zastosowanie zależy od typu dokumentu – documentType) | |
| {...} | |||
| AdditionalHeader | O |
Tablica AdditionalHeader może służyć do ustawienia dodatkowych wierszy tekstu dowolnego w nagłówku dokumentu. Szczegóły dotyczące poszczególnych krajów:
Uwaga: Obecnie ta tablica jest obsługiwana wyłącznie we Włoszech. Można ją wypełnić również w innych krajach, jednak nie będzie to miało żadnego skutku. |
|
| AdditionalFooter | O |
Tablica AdditionalFooter służy do ustawiania dodatkowych wierszy tekstu dowolnego w Footer dokumentu. Szczegóły dotyczące poszczególnych krajów:
Uwaga: Obecnie ta tablica jest obsługiwana wyłącznie we Włoszech. Można ją wypełnić również w innych krajach, jednak nie będzie to miało żadnego skutku. |
|
| FiscalAdditionalFields | O | ||
Ten artykuł został przetłumaczony automatycznie.
Komentarze
Komentarze: 0
Zaloguj się, aby dodać komentarz.