Skip to main content

Basic document transfer process

Harald Krondorfer
  • Updated

Creation of the fiscal module

To transfer fiscal documents (fiscal data) you've first to create a fiscal module. This can be done in several ways:

  • If you use the trusted fiscal service (windows or linux service), the fiscal module will be automatically created for you by the fiscal service.
  • If you plan to do the integration of the fiscal module with direct .net dll integration you have to intantiate the fiscal module by your own. A detailled description can be found below:
    Create / instantiate the fiscal module
Attention: The fiscal module initializes a few submodules and should not be newly created for every receipt (e.g. self test of tss hardware (germany) needs at least 30sec.). In addition, the method is to call CloudConnect before transferring documents, otherwise cloud archiving will fail (only necessary if cloud archiving is enabled).

Transfer of documents

To transfer fiscal documents to the fiscal module you need at least 2 steps:

  • CreateDocument
  • StoreDocument

Independently of the country we recommend to call method CreateDocument in every case.

Attention: CreateDocument must be called at the beginning of a document (when you register an article). This is absolutely necessary in order to implement fiscalization legally (e.B.: in Germany). You have to set FiscalResponse of the document to store with the FiscalResponse you got when you call the CreateDocument method.

Sample Receipt document as json:

{
"UniqueClientId": "c1062c55-57c4-4ed2-9c53-aff1762326a4",
"DocumentGuid": "5efa5306-fe53-452d-9c81-68329475eee0",
"DocumentId": "2021-02-02T05:31:08.9450964+01:00",
"CreateDate": "2021-02-02T05:31:08.9450964+01:00",
"BookDate": "2021-02-02T05:31:08.9450964+01:00",
"DocumentNumber": null,
"CancellationDocument": false,
"DocumentReference": null,
"IsTraining": false,
"DocumentType": 0,
"DocumentTypeCaption": null,
"User": {
   "Id": "1234",
   "Caption": "Testuser"
},
"AllocationGroups": [],
"Partner": null,
"FiscalResponse": null, 
"FiscalDocumentNumber": 0, // set fiscaldocument of create document here
"FiscalDocumentRevision": 0, // set fisacldocument revision of create document here
"Positions": [
   {
      "ItemCaption": "Blume grün", // the caption of the item
      "ItemShortCaption": null,
      "Discounts": [],
      "Type": 0,
      "UseSubItemVatCalculation": true,
      "SubItems": null,
      "Quantity": 1.0,
      "QuantityUnit": null,
      "ItemId": "000714", // the item id
      "BaseNetValue": 3.61, // base value (without discounts)
      "BaseGrossValue": 4.3,
      "BaseTaxValue": 0.69,
      "GTIN": null,
      "BusinessTransactionType": 0,
      "VatIdentification": 1, 
      "VatPercent": 19.0, 
      "NetValue": 3.61, // net value (quantity * price)
      "GrossValue": 4.3, // gross value of the position
      "TaxValue": 0.69,
      "AccountingIdentifier": null,
      "PositionNumber": 0,
      "PositionReference": null,
      "CancellationPosition": false
   }
],
"Payments": [
   {
      "Amount": 5.0, // payment with over payment
      "IsCash": false,
      "CurrencyIsoCode": "EUR",
      "Caption": null,
      "UniqueReadablePaymentIdentifier": null,
      "ForeignAmount": 0.0,
      "ForeignAmountExchangeRate": 0.0
   },
   {
      "Amount": -0.7, // cash return (second payment)
      "IsCash": false,
      "CurrencyIsoCode": "EUR",
      "Caption": null,
      "UniqueReadablePaymentIdentifier": null,
      "ForeignAmount": 0.0,
      "ForeignAmountExchangeRate": 0.0
   }
]
}

This receipt contains:

  • one item position with item "000714", "Blume grün", with a price of 4,3 EUR gross (1 piece).
  • 2 payments, a position with 5 EUR in cash and the return of 0.7 eur
Note: To see how a document should be assmebled you can have a look at the fiscal service client sample (c#) which you can found in the download section (http://www.retailforce.cloud/downloads). It also show's the resulting JSON when you start the sample application. Please be sure to have the fiscal service installed and started on the same machine.

To cancel a previous created document you can call the method:

  • CancelDocument
Attention: Each created document (with CreateDocument) has to be closed with StoreDocument or cancelled with CancelDocument.

To validate a document in front of transferring it to the fiscal module you can you call

  • ValidateDocument
Information: The document itself will always be validated before it will be stored (also if it is cancelled). If a validation error occurs the StoreDocument method will fail with an exception.

Processes in detail

Sales process Retail

The sale of goods, for example in retail, is as follows:

Operator Cash register system RetailForce Fiscalisation Service
1. The operator (cash register user) enters the first item that the customer wishes to purchase.    
  2. The cash register system sends a request to the fiscal service (createDocument) to register the start of the corresponding transaction.  
    3. Fiscal Service receives request from the upstream system and processes it in accordance with country-specific requirements (e.g. signing, etc.).
    4. Fiscal Service sends a response (fiscalResponse) to the upstream system.
  5. The cash register system (upstream system) receives the response and stores parts of it (or the entire response object) for further use (reference) when the transaction is completed.  
6. The operator scans all of the customer's items and initiates the payment process.    
 

7. Once all transaction data has been determined (items, payment method, etc.), the POS system generates the transaction payload (JSON) and sends another request to the fiscal service (storeDocument), which completes (saves) the transaction.

Certain information from the fiscalResponse received during createDocument must be included in the payload (‘fiscalDocumentNumber’, “fiscalDocumentStartTime” and, if applicable, country-specific elements such as ‘fiscalDocumentRevision’ in Germany).

Attention: only the elements listed above may be included in payload and NOT the entire fiscalRespons object!
  
    8. Fiscal Service receives requests from the upstream system and processes them in accordance with country-specific requirements (e.g. signing, etc.).
    9. Fiscal Service sends a response (fiscalResponse) to the upstream system.
  10. The cash register system receives the fiscalResponse, extracts the information required for document creation (e.g. document signature, QR code, etc.) and prints the document.  
11. Operator hands the printed receipt to the customer    

Sales process in retail with transaction cancellation

If, as described above, during step 6, i.e. AFTER sending createDocument (step 2) and BEFORE sending storeDocument (step 7), the POS system sends a cancelDocument INSTEAD OF a storeDocument.

Attention: cancelDocument is used to cancel (abandon) an incomplete transaction and NOT (!) to reflect returns.

Returns are processed in the same way as normal sales transactions, using createDocument and storeDocument.

 

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk