How to use the SandBox

The sandbox is fully functional just like the live system of fiskaltrust. It can be accessed by using the URL https://portal-sandbox.fiskaltrust.fr/. In the sandbox you can register your company just like you would in the live-system, the simple difference is: It’s only for learning and trying out the functions of the fiskaltrust.Portal without any legal obligations.

While communicating with the sandbox, the fiskaltrust.Service always sends an additional signature for each receipt, indicating the sandbox usage. Each receipt printed in sandbox-mode must show this signature.

How to create an outlet

It is necessary to create at least one branch, in order to use the fiskaltrust.Service in accordance with French laws. By registering on the fiskaltrust.Portal, the first outlet is created automatically. Depending on the data you entered during the registration process you can change it at this point.

First, make sure you have entered a valid SIREN in the master data of your company. You can verify/change the number, by clicking on the company name in the left sidebar of the fiskaltrust.Portal and then on the subcategory “Master data”. For ease of access, you can follow the links below for the sandbox  https://portal-sandbox.fiskaltrust.fr/AccountProfile/Edit and for live https://portal.fiskaltrust.fr/AccountProfile/Edit.

You can now modify or correct the “SIREN” field. You must enter your SIREN number here and click the button on the right to verify it. In “sandbox” mode, you can enter any 9-digit number.

The second step is to click on the “Outlets” command in the company menu. For ease of access, you can follow the links below for the sandbox: https://portal-sandbox.fiskaltrust.fr/AccountOutlet or for the live system: https://portal.fiskaltrust.fr/AccountOutlet.

Next, you must verify the outlet that the system already created is correct. After verification, you can add a new outlet by using the button “Add new outlet”, located on the top right side of the screen. As for an existing outlet, in order to create a new outlet, you must enter the SIRET for the outlet in the data field Location ID and the address of the outlet. The outlet number is up counting and should be the same as used in the SIRET (digits 10 to 13). The Outlet number must be unique.

In the fiskaltrust.Portal, you must use the numbers provided by the French authorities. The SIREN number, to be entered in the master data, is composed of nine digits. The SIRET number, used to create an outlet, corresponds to the SIREN number followed by 5 unique digits to identify the establishment. In “sandbox” mode, you can use any 5 random digits to extend the SIREN number and form a SIRET number.

For further use in the fiskaltrust.Portail, the SIRET must be checked with the “Data verification” button on the right. SIREN and SIRET must have a green check mark on the right side of the field for continued use.

What is a zero receipt?

A zero receipt is a universal data carrier and storage. The cash register sends a receipt with an empty charge items block (ftChargeItem) and an empty pay items block (ftPayItem) which logically contain a total amount of “0”.

The fiskaltrust.SecurityMechanism sends the necessary blocks, such as the receipt header, the charge item block, and the signature block in the response. This response is either printed or issued electronically and has to be archived.

For example a start receipt or stop receipt is a special case of a zero receipt.

What is a start receipt?

The start receipt must be sent before the fiskaltrust.SecurityMechanism is used for the first time. This receipt receives a meaningful response from fiskaltrust.SecurityMechanism only the first time: in order to start operative calculations.

What is a stop receipt?

The stop receipt is required for scheduled decommissioning of the fiskaltrust.SecurityMechanism and/or cash registers. The stop receipt is used to switch off any further: receipt chaining, up-counters, and totalizer storage. It also concludes the data collection log.

This receipt has a meaningful response from fiskaltrust.SecurityMechanism only the one time in order to stop operative calculations and the operation of a queue. After receiving a stop receipt the queue will be closed. There will be no positive response from the fiskaltrust.SecurityMechanism to the cash register when a receipt is sent to a closed queue.

A closed queue cannot be reopened with a start receipt. Instead, a new queue must be created and initialised with a start receipt.

How to create a local CashBox

To create a CashBox, certain conditions must be met beforehand:

  • A valid SIREN number must be entered and checked in the basic data of the company.
  • A valid branch must be registered. For this, the address of the branch and its SIRET number must be entered and verified.

Once these two conditions are met, a CashBox can be created in following 5 steps:

Step One:
Create a Signature Creation Unit (SCU) in the Configuration menu. Click on the “Create” button to start. Add a description of the SCU (for your reference) and select the correct outlet. Then click on the “Save” button to conclude the creation of the SCU.

Step Two:
Create a queue for your Outlet. Go to the Configuration menu and open the subcategory “Queue”. By clicking on the button “Create new Queue” you start the creation. Add a description of the Queue (for your reference) and accept the preselected SQLite-Package. The Package version should be the latest 1.2 package (without the “-dev” suffix). The “Location Id” must be the same as the one selected in the previous step.  Add a unique CashBox identification.

Save this configuration and in the following window click the “HTTP” button to add an http-URL. Do not change any of the other values. Finally, save the configuration.

Step Three:
Return to the Configuration menu and open the subcategory “Queue”. Find the recently created Queue in the list and on the far right hand side are four configuration buttons. Click on the first one (the square with the arrow in it). Choose the SCU that you created in the first step and click on “Save and close”.

Be careful while executing this step, the SCU will be fixed to this Queue and cannot be changed in the future.

Step Four:
Return to the Configuration menu and open the subcategory “CashBox”. In the CashBox of the configuration menu you must click on the “+ Add” button. Enter a description and select the same outlet selected in the previous steps. After clicking on save, you will find a new CashBox in the list. Click on the button with the pointing hand on it. Now drag and drop the recently created queue from the column on the right side to the column on the left side. Verify that it is the correct outlet that is selected and click on save.

Step Five:
Click on the rebuild configuration button (refresh circle arrows) in the row of the relevant CashBox.

Now you can download one of the three launchers and install the fiskaltrust.Service on your local machine.

How to create a cloud CashBox

The service for the cloud-solution is not free of charge, but you can try the service in the sandbox without incurring any cost.

To create a cloud CashBox, certain conditions must be met beforehand:

  • A valid SIREN number must be entered and checked in the basic data of the company.
  • A valid branch must be registered. For this, the address of the branch and its SIRET number must be entered and verified.

Once these two conditions are met, a cloud CashBox can be created in following 4 steps:

Step One:
Open the Shop menu on the left hand sidebar on the fiskaltrust.Portal. Then click on “Products”. Select the outlet in the field “Location Id” (located at the top of the page) for which you use ChaîneCloud. This is important because the outlet can not be changed afterwards!

Add one “ChaîneCloud” (Product-N° 4652-201) to the shopping cart. The icon for your shopping cart is located at the top of the window and by clicking on the shopping cart icon, you can proceed to the checkout by clicking on the “Checkout” button.

Step Two:
Choose the payment method option which you will use. (In sandbox mode, choose Direct debit transfer.) Then click on the green button “Binding order”. After the order was successfully placed, you will receive an email with the order confirmation and the invoice for the purchased product(s).

You can see the state of your order(s) under the Shop menu subsection “Orders” and/or “Invoice”.

Step Three:
The CashBox will be created automatically within several minutes after the order is confirmed. You will find it in the Configuration menu, subcategory “CashBox”. The name starts with “fiskaltrust.ChaîneCloud” and has an upcounting number on the end.

Step Four:
Click on the rebuild configuration button (refresh circle arrows) in the row of the relevant CashBox.

Hint:
For easier identification, you can change the description of the CashBox and/or Queue in the Configuration menu.

How to handle the request/response of the fiskaltrust.Service

When a ticket is sent to the fiskaltrust.Service, all of the data is secured by the fiskaltrust.SecurityMechanism. Therefore the request is processed and some security data or data required by national laws is sent back as response.

To begin the process, a receipt needs to be created by the POS-System. To accomplish this, some information from the POS-System itself and some information from the header of the receipt has to be gathered in a JSON-format.

See the below example assuming a coffee and a cheesecake is sold to a client in a restaurant and the bill is paid with cash.

1) The header of a receipt:
This is general information for the receipt itself. The fields shown here are the minimal data set necessary. All possible fields are described in the middleware documentation.

{
  "ftCashboxId": "487b7a77-fbc3-414f-8b3a-57930fb58f97",
  "ftPosSystemId": "058c4299-1657-5ad2-8ce3-fbbeb317a7b3",
  "cbTerminalId": "term01",
  "cbReceiptReference": "ticket 2020-4456",
  "cbReceiptMoment": "2020-04-05 10:49:20",
  "ftReceiptCase": "5067112530745229313",

2) The list of products sold:
This is an array of products or lines items for a ticket. In the fiskaltrust.Universe, these are called ChargeItems. The data set shown below, is the absolute necessary set to be compliant with the French law. All the fields and possible values are described in depth in the middleware documentation.

"cbChargeItems": [
    {
      "Quantity": 1.0,
      "Description": "Café, espresso double",
      "Amount": 5.2,
      "VATRate": 20.0,
      "VATAmount": 0.87,
      "ftChargeItemCase": "5067112530745229315",
      "Moment": "2020-04-05 10:49:50",
"ftChargeItemCaseData": "{\"NetAmount\": 4.33}"
    },
    {
      "Quantity": 1.0,
      "Description": "Cheescake",
      "Amount": 7.9,
      "VATRate": 20.0,
      "VATAmount": 1.32,
      "ftChargeItemCase": "5067112530745229315",
      "Moment": "2020-04-05 10:49:50",
      "ftChargeItemCaseData": "{\"NetAmount\": 6.58}"
    }
  ],

3) How the ticket is payed:
In the fiskaltrust.Universe, this block is called PayItems. This a list of all the means of payment, used by the client. The example shown below is only the obligatory dataset, more information can be found in the middleware documentation.

  "cbPayItems": [
    {
      "Quantity": 1.0,
      "Description": "Cash",
      "Amount": 13.1,
      "ftPayItemCase": "5067112530745229313",
      "Moment": "2020-04-05 10:50:20"
    }
  ]
}

Depending on the protocol used, the whole receipt is sent in the payload as JSON-string with SOAP or REST. The type of protocol defines which credentials you have to send in the header of the request. Usually, it is the CashBoxID and an AccessToken. Both can be found in the Configuration menu in the fiskaltrust.Portal.

The fiskaltrust.Service will answer this request with a response as JSON-string like this:

{
  "ftCashBoxID": "487b7a77-fbc3-414f-8b3a-57930fb58f97",
  "ftQueueID": "0f68a617-c0cd-4249-9c48-c48da217ff77",
  "ftQueueItemID": "d4bfd2b0-973f-4e1a-90de-c63884cde8db",
  "ftQueueRow": 298886,
  "cbTerminalID": "term01",
  "cbReceiptReference": "posAction444",
  "ftCashBoxIdentification": "RueHelder_1(2)",
  "ftReceiptIdentification": "ft48F82#T293614",
  "ftReceiptMoment": "2020-04-05T11:03:58.4319402Z",
  "ftSignatures": [
    {
      "ftSignatureFormat": 3,
      "ftSignatureType": 5067112530745229313,
      "Caption": "www.fiskaltrust.fr",
      "Data": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...MEQCIC7YDBVwEoBqGtlMfUznu4ExAYZ3t6qph5_nIJXuOelHAiBge_EPSeCirPma881ElrNvGf2sGYfCPo5nkYZujs1P4w"
    },
    {
      "ftSignatureFormat": 1,
      "ftSignatureType": 5067112530745229312,
      "Caption": "S A N D B O X",
      "Data": "0f68a617-c0cd-4249-9c48-c48da217ff77"
    }
  ],
  "ftState": 5067112530745229312
}

Most of this information (shown in bold) must be printed on the receipt, but best practice is to print everything. Each signature sent back by the fiskaltrust.Service must be printed. Therefore, the fields Caption and Data are obligatory and must be shown on the receipt. There can be more than one signature. If this occurs each signature must be printed. Signatures with a type 3, contain a JWT, displayed as an encoded QR-Code in the Data-field, which must be printed before the footer, on the receipt.

How to void a ticket?

Any data sent to the fiskaltrust.Service cannot be deleted afterwards. For this reason, all changes must done by sending a new receipt. In this example we use a ticket to “void”, but this can be used for any type of receipt. For example, if you bill a simple coffee for a client you must send a ticket to fiskaltrust.Service:

{
  "ftCashboxId": "cashbox-identification",
  "ftPosSystemId": "pos-system-identification",
  "cbTerminalId": "terminal-identification",
  "cbReceiptReference": "pos-action-identification",
  "cbReceiptMoment": "receipt-moment",
  "ftReceiptCase": "0x4652000000000001",
  "cbChargeItems": [
    {
      "Quantity": 1.0,
      "Description": "Café",
      "Amount": 2.2,
      "VATRate": 10.0,
      "VATAmount": 0.2,
      "ftChargeItemCase": "0x4652000000000002",
      "Moment": "moment-chargeitem",
      "ftChargeItemCaseData": "{\"NetAmount\": 2}"
    }
  ],
  "cbPayItems": [
    {
      "Quantity": 1.0,
      "Description": "Cash",
      "Amount": 2.2,
      "ftPayItemCase": "0x4652000000000001",
      "Moment": "moment-payitem"
    }
  ]
}

This is a normal request with one charge item for the coffee and one pay item for the cash payment. Please be aware that all security relevant data is masked with general words (e.g. ftCashBoxId, ftPosSystemId, …)

To continue our example, the client leaves the restaurant without paying. You now need to cancel this ticket, because you didn’t receive any payment. To accomplish this, you must send the same ticket with negative values to the fiskaltrust.Service.

{
  "ftCashboxId": "cashbox-identification",
  "ftPosSystemId": "pos-system-identification",
  "cbTerminalId": "terminal-identification",
  "cbReceiptReference": "pos-action-identification",
  "cbReceiptMoment": "receipt-moment",
  "ftReceiptCase": "0x4652000000040001",
  "cbPreviousReceiptReference": "number of voided ticket",
  "cbChargeItems": [
    {
      "Quantity": -1.0,
      "Description": "Café",
      "Amount": -2.2,
      "VATRate": 10.0,
      "VATAmount": -0.2,
      "ftChargeItemCase": "0x4652000000000002",
      "Moment": "moment-chargeitem",
      "ftChargeItemCaseData": "{\"NetAmount\": -2}"
    }
  ],
  "cbPayItems": [
    {
      "Quantity": -1.0,
      "Description": "Cash",
      "Amount": -2.2,
      "ftPayItemCase": "0x4652000000000001",
      "Moment": "moment-payitem"
    }
  ]
}

Two things have to be changed on the receipt. The field ftReceiptCase stays the same than the original but gets the flag for voided ticket set. (The value 4 on position 12).

And the field cbPreviousReceiptReference should be added. The value has to be the number of the voided receipt.

How to handle degraded mode?

If the receipt can not be signed by the fiskaltrust.SecurityMechanism the POS-System must print mode dégradé on the receipt.

When the fiskaltrust.Service can sign the receipts again all the receipts signed with the “degraded” mode, have to be entered (manually/automatically), sent to the fiskaltrust.SecurityMechanism and printed again, as regular receipts. Then the degraded and the new receipts must be archived together.

A good practice is to send a message in the technical log with the following content:

{
  "code": 70,
  "description": "Start of degraded mode",
  "moment": "2020-03-22T06:10:52.6395741Z"
}

to document the beginning of the degraded mode. When normal functionality returns, the following message should be sent to the technical log, to document the event.

{
  "code": 120,
  "description": "End of degraded mode",
  "moment": "2020-03-22T09:23:22.6015741Z"
}