Comment utiliser la SandBox ?

La sandbox (environement test) est, comme le système live de fiskaltrust, entièrement fonctionnelle. Vous pouvez y accéder depuis l’URL https://portal-sandbox.fiskaltrust.fr/ et enregistrer votre entreprise. La seule différence entre la sandbox et le système live est que la sandbox permet uniquement de se familiariser et d’essayer l’ensemble des fonctions du fiskaltrust.Portal et tout cela sans aucune obligation.

En utilisant la sandbox, le fiskaltrust.Service envoie toujours une signature supplémentaire pour chaque reçu, mentionnant l’utilisation de la sandbox. Chaque reçu imprimé en mode « sandbox » doit posséder cette signature.

Comment créer un établissement ?

Il est nécessaire de créer au moins un établissement afin de pouvoir utiliser le fiskaltrust.Service conforme aux lois françaises. En vous inscrivant sur le fiskaltrust.Portail, le premier établissement est créé automatiquement en fonction des données que vous avez saisies lors du processus d’enregistrement. Si nécessaire, vous devez les modifier ou corriger celles-ci lors de votre première connexion sur le fiskaltrust.Portail.

Tout d’abord, il vous faut vous assurer d’avoir entré un numéro de SIREN valide dans les données de base de votre entreprise. Vous pouvez vérifier / modifier le numéro, en cliquant sur le nom de votre société dans le menu latéral gauche du fiskaltrust.Portail puis sur la commande Données de base. Vous pouvez également suivre le lien suivant pour le sandbox https://portal-sandbox.fiskaltrust.fr/AccountProfile/Edit ou celui qui suit pour le système live https://portal.fiskaltrust.fr/AccountProfile/Edit.

Vous pouvez maintenant modifier ou corriger le champ SIREN. Vous devez entrer ici votre numéro de SIREN et cliquez sur le bouton à droite afin de le vérifier. En mode « sandbox », vous pouvez saisir n’importe quel nombre à 9 chiffres.

Pour la deuxième étape, rendez vous sur la commande Etablissement dans le menu de votre entreprise. Alternativement, suivez le lien suivant pour le sandbox: https://portal-sandbox.fiskaltrust.fr/AccountOutlet ou celui ci-après pour le système live: https://portal.fiskaltrust.fr/AccountOutlet.

Vous devez vérifier l’établissement déjà créé automatiquement à partir du système. Dans un deuxième temps, vous pouvez ajouter un nouvel établissement avec le bouton en haut à droite de l’écran. Pour les établissements existants comme pour les nouveaux, vous devez entrer le numéro de SIRET pour chaque point de vente dans le champ Location ID ainsi que l’adresse du point de vente. Le numéro d’établissement doit être le même que celui utilisé dans le SIRET (chiffres 10 à 13). Le numéro d’établissement doit être unique.

Dans le fiskaltrust.Portail, vous devez utiliser les numéros fournis par les autorités françaises. Le numéro de SIREN, a entrer dans les données de base, est composé de neuf chiffres. Le numéro de SIRET, utiliser pour créer un établissement, correspond au numéro de SIREN suivi de 5 chiffres uniques pour identifier l’établissement. En mode « sandbox », vous pouvez utiliser 5 chiffres aléatoires pour étendre le numéro de SIREN et former un numéro de SIRET.

Pour une utilisation ultérieure dans le fiskaltrust.Portail le SIRET doit être vérifié avec le bouton « Vérification des données » se trouvant à droite. SIREN et SIRET doivent impérativement avoir une coche verte sur le côté droit pour une utilisation future.

Qu’est-ce qu’un « zero receipt » (reçu zéro) ?

Un zero receipt est un support et un stockage de données universels. La caisse enregistreuse envoie un reçu avec un bloc d’articles vide (ftChargeItem) et un bloc de paiement vide (ftPayItem) qui contiennent logiquement un montant total de « 0 ».

Le fiskaltrust.SecurityMechanism envoie les blocs nécessaires dans la réponse, tels que l’en-tête du reçu, le bloc d’articles et le bloc de signature. Cette réponse est imprimée ou publiée électroniquement et doit être archivée.

Par exemple, un reçu d’ouverture ou de clôture sont des cas particuliers de zero receipt.

Qu’est-ce qu’un « start receipt » (reçu d’ouverture) ?

Le start receipt doit être envoyé avant la première utilisation du mécanisme de sécurité. Ce reçu ne reçoit une réponse significative du fiskaltrust.SecurityMechanism que la première fois afin de commencer les calculs opérationnels.

Qu’est-ce qu’un « stop receipt » (reçu de clôture) ?

Le « stop receipt » est requis pour la mise hors fonction programmée des mécanismes de sécurité et / ou des caisses enregistreuses. Le stop receipt permet de désactiver: le chainage des tickets, la numérotation séquentielle et le stockage des totaux. Il clôture également le journal de collecte des données.

Ce reçu a une réponse significative du fiskaltrust.SecurityMechanism seulement la première fois afin d’arrêter les calculs opérationnels et le fonctionnement d’une queue. Après avoir reçu un accusé de réception, la queue sera fermée. Il n’y aura pas de réponse positive de la caisse enregistreuse lorsqu’un reçu est envoyé à une queue fermée.

Une queue fermée ne peut pas être rouverte avec un « start receipt ». Au lieu de cela, une nouvelle queue doit être générée et initialisée avec un « start receipt ».

Comment créer une CashBox (local) ?

Pour créer une CashBox, certaines conditions doivent être remplies au préalable : 

  • Un numéro de SIREN valide doit être saisi et contrôlé dans les données de base de l’entreprise.
  • Un Etablissement valide doit être enregistré. Pour cela, l’adresse de l’établissement et son numéro de SIRET doivent être saisis et vérifiés. 

Une fois ces deux conditions remplies, une Cashbox peut être créée en suivant les étapes de la documentation ici.

Vous pouvez maintenant télécharger l’un des trois « Launcher » et installer fiskaltrust.Service sur votre machine locale. 

Comment créer une CashBox (cloud) ?

Le service pour la solution cloud est payant, mais vous pouvez l’essayer gratuitement dans la « sandbox ».

Pour créer une CashBox, certaines conditions doivent être remplies au préalable : 

  • Un numéro de SIREN valide doit être saisi et contrôlé dans les données de base de l’entreprise. 
  • Un établissement valide doit être enregistré. Pour cela, l’adresse de l’établissement et son numéro de SIRET doivent être saisis et vérifiés. 

Une fois ces deux conditions remplies, une Cashbox peut être créée en suivant les étapes de la documentation ici.

Astuce : 
Pour une identification plus facile, vous pouvez modifier la description de la caisse et / ou de la file d’attente dans le menu de configuration.

Comment gérer request/reponse du fiskaltrust.Service

Lorsqu’un ticket est envoyé au fiskaltrust.Service, toutes les données sont sécurisées par le fiskaltrust.SecurityMechanism. Par conséquent, la demande est traitée et certaines données de sécurité ou données requises par la loi sont renvoyées en réponse.

Tout d’abord, le ticket doit être créé par le POS-System. Pour cela, certaines informations du POS-System lui-même ainsi que les informations d’en-tête du ticket doivent être rassemblées au format JSON. Par exemple, supposons qu’il soit vendu un café et une part de Cheesecake à un client dans un restaurant et que le paiement soit fait en espèces.

1) L’en-tête d’un ticket :
Il s’agit d’ informations générales pour le ticket lui-même. Les champs affichés ici regroupent l’ensemble des données minimum nécessaires. Tous les champs possibles sont décrits dans la documentation de l’interface.

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

2) La liste des produits vendus :
Il s’agit d’un tableau de lignes produits pour un ticket, dans le fiskaltrust.Univers cela s’appelle ChargeItems. L’ensemble des données présenté ci-après comprend l’ensemble des données absolument nécessaire afin d’être conforme aux lois françaises. Tous les champs et valeurs possibles sont décrits en détail dans la documentation de l’interface.

"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) Comment le ticket est payé:
Dans le fiskaltrust.Univers, ce tableau est appelé PayItems. Il s’agit d’une liste de tous les moyens de paiement pouvant être utilisés par un client. Dans l’exemple ci-dessous, seul les données obligatoires est affichées, plus d’informations peuvent être trouvées dans la documentation de l’interface.

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

En fonction du protocole utilisé, le ticket entier est envoyé dans le payload sous forme de JSON-String avec SOAP ou REST. Le type de protocole définit les informations d’identification que vous devez envoyer dans l’en-tête de la demande. Il s’agit généralement du CashBoxID et d’un AccessToken. Les deux peuvent être trouvés dans le menu Configuration du fiskaltrust.Portail.

Le fiskaltrust.Service répondra à cette demande avec une réponse sous forme de JSON-String comme ceci:

{
  "ftCashBoxID": "487a5a77-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
}

La plupart des informations (indiquées en gras) doivent être imprimées sur le ticket, mais le mieux consiste néanmoins à tout imprimer. Chaque signature renvoyée par le fiskaltrust.Service doit être imprimée. Par conséquent, les champs Caption et Data doivent obligatoirement apparaître sur le ticket. Il peut y avoir plusieurs signatures. Si cela se produit, chaque signature doit être imprimée. La signature avec le type 3 contient un JWT sous la forme d’un QR-Code déjà encodé dans le champ de données; celui-ci doit être imprimé sur le ticket avant le pied de page.

Comment annuler un ticket ?

Aucune donnée envoyée au fiskaltrust.Service ne peut être supprimée à postériori. Pour garantir cela, un nouveau reçu est créé pour toutes les modifications effectuées. Dans l’exemple ci-dessous, nous utilisons un ticket pour annuler, mais cela peut être utilisé pour tout type de reçu.

Exemple:

En facturant un simple café à un client, vous devez envoyer un ticket à 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"
    }
  ]
}

Il s’agit d’une demande correcte avec un élément de facturation pour le café et un élément de paiement pour le règlement en espèces. Veuillez noter que toutes les données relatives à la sécurité sont masquées par des mots généraux (par exemple ftCashBoxId, ftPosSystemId, …)

Maintenant, les clients quittent le restaurant sans payer. Vous devez annuler ce ticket, car vous ne recevez aucun paiement. Pour cela, vous envoyez le même ticket avec des valeurs négatives au 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"
    }
  ]
}

Deux choses doivent être modifiées sur le reçu. Le champ ftReceiptCase reste identique à l’original mais obtient un indicateur pour l’ensemble du tickets annulé. (La valeur 4 en position 12).

Et le champ cbPreviousReceiptReference doit être ajouté. La valeur doit être le numéro du reçu annulé.

Comment gérer le mode dégradé ?

Si le reçu ne peut pas être signé par le fiskaltrust.SecurityMechanism le POS-System doit imprimer mode dégradé sur le reçu.

Lorsque le fiskaltrust.Service peut à nouveau signer les reçus, tous ces reçus « dégradés » doivent être saisis (manuellement / automatiquement), envoyés au fiskaltrust.SecurityMechanism et imprimés à nouveau comme reçus normaux. Ensuite, les reçus dégradés et les nouveaux reçus doivent être archivés ensemble.

Une bonne pratique consiste à envoyer un message dans le journal technique avec le contenu suivant :

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

pour documenter le début du mode dégradé. Lorsque le fonctionnement normal est rétabli, le message suivant doit être envoyé au journal technique, afin de documenter également cette situation.

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