Introduction

Le Driver MCF (Machine de Certification Fiscale) est un service local qui s'exécute sur le poste de travail et assure la communication entre votre logiciel de facturation et le terminal MCF Eltrade CC300. Il fonctionne en deux modes : mode local (API REST sur http://127.0.0.1:38917) et mode cloud (client WebSocket sortant vers le serveur SFE, pour les contextes SaaS multi-tenant où les opérateurs travaillent sur mobile ou tablette).

Architecture

Le système se compose de trois briques qui communiquent entre elles :

Le binaire unifié e-mecef contient le driver et la GUI. Mode local : le SFE appelle le driver en HTTP. Mode cloud : le driver se connecte au cloud SFE via WebSocket et reçoit les factures à certifier.

Installation du Driver

Téléchargez le binaire correspondant à votre système d'exploitation depuis la page de téléchargements. Le binaire unifié e-mecef contient à la fois le driver et la GUI.

WindowsInstallation Windows

1. Téléchargez e-mecef-windows-x64.exe
2. Placez le fichier dans un répertoire de votre choix (ex : C:\eltrade\)
3. Double-cliquez pour lancer la GUI, ou installez comme service Windows (voir Tableau de bord)
4. La GUI s'ouvre — utilisez la section Service système dans le tableau de bord pour installer le service
5. Une fois le service installé et démarré, vérifiez : http://127.0.0.1:38917/health

macOSInstallation macOS

1. Téléchargez le bundle e-mecef.app (recommandé) ou le binaire correspondant à votre architecture
2. Pour le bundle .app : glissez-le dans le dossier Applications
3. Pour le binaire : rendez-le exécutable avec chmod +x e-mecef-macos-arm64
4. Au premier lancement, macOS peut demander une autorisation de sécurité (Préférences Système → Sécurité)
5. Lancez la GUI et installez le service via le dashboard

LinuxInstallation Linux

# Téléchargement et installation
chmod +x e-mecef-linux-x64
sudo mv e-mecef-linux-x64 /usr/local/bin/e-mecef

# Lancement de la GUI
e-mecef

# Installation du service (depuis la GUI ou en ligne de commande)
e-mecef --driver-only  # Mode driver seul (pour systemd)

Pour un démarrage automatique, installez le service via la GUI ou créez manuellement un service systemd.

Configuration

La configuration du driver se fait via la GUI (onglet Paramètres) ou manuellement via un fichier .env. Le fichier est automatiquement créé par la GUI dans le répertoire de configuration de la plateforme.

Détection automatique du port série

Si DEVICE_PORT est vide, le driver recherche automatiquement le MCF par son identifiant USB (VID:PID). La route GET /ports retourne la liste des ports disponibles pour faciliter le diagnostic.

Activation de la licence

Pour émettre des factures certifiées, le driver doit être activé avec une clé de licence valide. L'activation lie la licence à la machine (via son NIM — Numéro d'Identification de la Machine).

Procédure d'activation

Activation via l'API

Vous pouvez également activer la licence directement via l'API REST :

POST http://127.0.0.1:38917/license/activate
Content-Type: application/json

{
  "key": "ABCDE-FGHIJ-KLMNO-PQRST",
  "nim": "NIM-de-la-machine"
}

Interface graphique (GUI)

La GUI est une application de bureau native intégrée au binaire unifié. Elle comporte deux onglets : Tableau de bord et Paramètres.

Tableau de bord

L'onglet Tableau de bord est l'interface principale. Il regroupe le monitoring en temps réel et la gestion du service système :

Paramètres

L'onglet Paramètres permet de configurer tous les aspects du driver :

• Port série MCF (ex. COM3 ou /dev/ttyUSB0), VID, PID et vitesse de communication (baudrate).
• Adresse et port HTTP du serveur local (hôte + port).
• URL du serveur de licence et chemin vers le fichier license.json.
• Mode mock MCF — case à cocher pour activer le simulateur sans matériel.
• Mode cloud (WebSocket) — sélecteur Local / Cloud, URL WSS et clé API (voir section dédiée ci-dessous).

Après enregistrement, les modifications prendront effet au prochain démarrage du driver. Redémarrez le service via le tableau de bord pour appliquer les changements.

Mode cloud (WebSocket)

Par défaut, le driver expose une API REST sur http://127.0.0.1:38917 (mode local). En activant le mode cloud, il initie lui-même une connexion WebSocket permanente vers le serveur SFE. Cette connexion est sortante — aucun port à ouvrir, fonctionne derrière n'importe quel NAT ou firewall.

Pourquoi le mode cloud ?

En mode cloud, les opérateurs peuvent être sur mobile, tablette ou un browser distant — ils ne peuvent jamais atteindre 127.0.0.1 d'un autre réseau. Le mode cloud résout ce problème : le driver établit lui-même la connexion vers le serveur SFE, qui peut ensuite pousser des factures à certifier depuis n'importe quel appareil connecté à Internet.

Flux de certification

Configuration

Activez le mode cloud via la GUI → Paramètres → Mode cloud (WebSocket) : sélecteur Local / Cloud, champs URL WSS et Clé API. Enregistrez puis redémarrez le service via le dashboard.

Ou manuellement dans le fichier .env :

DRIVER_MODE=cloud
DRIVER_WSS_URL=wss://app.sfe.com/mcf/ws
DRIVER_API_KEY=sk_org_xxxxxxxxxxxx   # clé API fournie par l'admin SFE

Authentification

La clé API (DRIVER_API_KEY) est transmise lors de la poignée de main WebSocket (handshake HTTP/1.1 Upgrade), dans l'en-tête standard Authorization :

GET /mcf/ws HTTP/1.1
Host: app.sfe.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: <clé générée automatiquement>
Sec-WebSocket-Version: 13
Authorization: Bearer sk_org_xxxxxxxxxxxx

Le serveur SFE doit vérifier cet en-tête avant d'accepter l'upgrade (répondre 401 Unauthorized si absent ou invalide). Une fois la connexion établie, aucun header supplémentaire n'est nécessaire — les messages JSON circulent librement sur le canal ouvert.

Reconnexion automatique

En cas de déconnexion, le driver se reconnecte automatiquement avec un exponential backoff (1 s → 2 s → 4 s → … → 60 s). Les factures reçues pendant la déconnexion restent en statut PENDING_MCF côté cloud et sont traitées dès que le driver se reconnecte.

Protocole de messages

Le WebSocket expose exactement les mêmes opérations que l'API HTTP. Tous les messages suivent le format uniforme { type, status, data|error }.

Serveur → Driver (facture)

{ "type": "BILL", "invoiceId": "uuid", "payload": { ...BillInput... } }
{ "type": "PONG" }

Driver → Serveur (succès)

{
  "type": "BILL_RESULT",
  "invoiceId": "uuid",
  "status": "success",
  "data": {
    "qr_code": "BFSECEF01;...",
    "security_code": "MOCKSIG000001",
    "nim": "XX01000001-1",
    "ifu": "0000000000001",
    "invoice_number": "SFEMOCK001/1",
    "datetime": "20260512210432",
    "bill_counter": "1",
    "total_counter": "1",
    "bill_type": "FV",
    "mcf_reference": "XX01000001-1-1"
  }
}

Driver → Serveur (erreur)

{ "type": "BILL_RESULT", "invoiceId": "uuid", "status": "error", "error": "Licence invalide" }

{ "type": "PING" }   // heartbeat toutes les 30 s

Le driver envoie un PING JSON toutes les 30 s. Le serveur doit répondre PONG. Si la connexion est perdue, le driver se reconnecte automatiquement (exponential backoff).

Référence API

Le driver expose une API REST sur http://127.0.0.1:38917. Les routes protégées nécessitent une licence valide.

¹ En mode MCF_MOCK=true, la vérification de licence est désactivée pour toutes les routes protégées.

Exemple : créer une facture

Requête minimale avec un article et un paiement en espèces :

POST http://127.0.0.1:38917/bill
Content-Type: application/json

{
  "isf": "SFE-2026-000042",
  "invoice_number": "FAC-2026-000042",
  "client_type": "PM",
  "client_ifu": "1234567890123",
  "client_name": "Entreprise ACME SARL",
  "price_mode": "TTC",
  "vt": "FV",
  "products": [
    {
      "label": "Prestation de service informatique",
      "tax": "B",
      "price": 150000,
      "quantity": 1,
      "itype": "LOCSER"
    }
  ],
  "payments": [
    {
      "mode": "V",
      "amount": 150000
    }
  ]
}

Réponse en cas de succès :

HTTP/1.1 200 OK

{
  "qr_code": "BFSECEF01;XX01000001-1;MOCKSIG000001;0000000000001;20260511143000",
  "security_code": "MOCKSIG000001",
  "nim": "XX01000001-1",
  "ifu": "0000000000001",
  "invoice_number": "SFE-2026-000042",
  "datetime": "20260511143000",
  "bill_counter": "1",
  "total_counter": "1",
  "bill_type": "FV",
  "mcf_reference": "XX01000001-1-1"
}

Exemple : créer une facture d'avoir

Pour émettre un avoir sur une facture déjà certifiée, utilisez la valeur mcf_reference retournée par le POST /bill original comme champ rn. Le format attendu est {NIM}-{TC} (ex : AB01000001-1-50). Ne pas utiliser invoice_number — le MCF stocke sa propre référence interne et rejettera tout autre valeur.

POST http://127.0.0.1:38917/bill
Content-Type: application/json

{
  "isf": "SFE-2026-000043",
  "invoice_number": "AV-2026-000001",
  "rt": "FA",
  "receipt_nature": "RAN",
  "rn": "XX01000001-1-1",
  "price_mode": "TTC",
  "products": [
    {
      "label": "Prestation de service informatique",
      "tax": "B",
      "price": 150000,
      "quantity": 1,
      "itype": "LOCSER"
    }
  ],
  "payments": [
    {
      "mode": "E",
      "amount": 150000
    }
  ]
}

Modèles

BillInput — Corps de la requête POST /bill

BillResponse — Réponse de POST /bill

ProductInput — Article de facture

PaymentInput — Paiement

AdditionalInfoEntry — Champ d'information supplémentaire (36h)

FAQ & Dépannage