Aller au contenu

TP Intégration FISCAL

Objectif : formaliser l’usage de FISCAL depuis une application consommatrice : appels API certification (Mode 1) et/ou facture formelle (Mode 2). Ce TP s’appuie sur le Guide d’utilisation FISCAL (dépôt principal : core/GUIDE_UTILISATION_FISCAL.md — Documentation source core) et s’applique à tous les projets qui facturent (SuperGest, Mediconnect, YOBALÉ, DAWALALE, RAGNAR, etc.).

Durée cible : ½ journée à 1 journée.

Étape 0 – Pré‑requis

  • Avoir lu la section « Projets clients & Core » et compris le rôle de FISCAL dans l’écosystème.
  • Avoir un backend minimal (TP Backend dynors-core ou un module existant) capable d’envoyer des requêtes HTTP (RestTemplate / WebClient).
  • FISCAL doit être démarré en local ou accessible (URL configurable : fiscal.api.base-url).

Référence : FISCAL – Bibliothèque Projets. Contrat détaillé : core/GUIDE_UTILISATION_FISCAL.md (dépôt principal) — voir Documentation source (core).

Étape 1 – Mode 1 – Certification POS (certify)

Objectif : appeler POST /api/v1/fiscal/certify comme le ferait une caisse (SuperGest, Mediconnect pharmacie, etc.).

  1. Client HTTP : créer un service (ex. FiscalCertifyClient) qui appelle FISCAL :
  2. URL : {fiscal.base-url}/api/v1/fiscal/certify

  3. Méthode : POST, body JSON.

  4. Payload minimal (voir guide FISCAL § 2) :

  5. idempotencyKey : clé unique par vente (ex. TERMINAL-01-20260309-00001). Ne jamais réutiliser en cas de retry.
  6. tenantCode, countryCode (ex. SN ou FR), sellerId (NINEA / SIRET), terminalId.
  7. items : tableau de lignes (productCode, description, quantity, unitPrice, vatRate).

Exemple de corps :

{
  "idempotencyKey": "TP-01-20260309-00001",
  "tenantCode": "tp-demo",
  "countryCode": "SN",
  "sellerId": "007123456XY",
  "terminalId": "TP-01",
  "items": [
    { "productCode": "PROD-A", "description": "Article A", "quantity": 2, "unitPrice": 5000, "vatRate": 0.18 }
  ],
  "fullInvoiceRequested": false
}

  1. Réponse : récupérer ticketNumber, dfeNumber, dfeStatus, totalAmount, qrPayload (pour affichage ou impression ticket).

  2. Idempotence : rappeler avec la même idempotencyKey → FISCAL doit renvoyer la même certification (pas de doublon).

Objectif : un endpoint (ex. POST /api/demo/certify) ou un test qui envoie une certification et affiche le numéro de ticket + montant.

Étape 2 – Récupération d’une certification (optionnel)

  • Appeler GET /api/v1/fiscal/certify/by-key/{idempotencyKey} pour retrouver une certification déjà créée (utile en cas de caisse offline puis reconnexion).

Étape 3 – Mode 2 – Facture formelle B2B (optionnel)

Objectif : créer une facture formelle via POST /api/v1/fiscal/invoices (comme YOBALÉ, DAWALALE, RAGNAR).

  1. Consulter le guide FISCAL § 3 (Mode 2) pour le contrat exact (émetteur, destinataire, lignes, pays pour la juridiction).
  2. Créer un client ou un service qui envoie une facture de test :
  3. issuer / recipient avec InvoiceParty (nom, adresse, pays, taxId).
  4. lines : description, quantity, unitPrice.
  5. tenantCode, invoiceDate.
  6. Enchaîner si l’API le permet : création → finalisation → export PDF (voir guide § 4 et § 5).

Objectif : obtenir un numéro de facture et, si possible, un PDF.

Étape 4 – Intégration dans votre module métier

  • Brancher le client FISCAL dans un cas d’usage réel de votre TP ou projet :
  • ex. « À la création d’une vente, appeler certify et stocker ticketNumber dans la vente ».
  • ex. « À la clôture d’une commande B2B, créer une facture et finaliser ».
  • Utiliser dynors-logging pour tracer les appels (tenant, idempotencyKey, ticketNumber ou invoiceNumber).

Références