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 :

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.

WindowsInstallation Windows

1. Téléchargez e-mecef-driver-x86_64-pc-windows-gnu.exe
2. Placez le fichier dans un répertoire de votre choix (ex : C:\eltrade\)
3. Créez un fichier .env dans le même répertoire (voir Configuration)
4. Lancez l'exécutable en tant qu'administrateur ou configurez-le comme service Windows
5. Vérifiez le démarrage : ouvrez http://127.0.0.1:38917/health dans le navigateur

macOSInstallation macOS

1. Téléchargez le binaire correspondant à votre architecture (Apple Silicon ou Intel)
2. Rendez-le exécutable :

chmod +x e-mecef-driver-aarch64-apple-darwin

3. Créez le fichier de configuration (voir Configuration)
4. Au premier lancement, macOS peut demander une autorisation de sécurité (Préférences Système → Sécurité)
5. Vérifiez le démarrage : curl http://127.0.0.1:38917/health

LinuxInstallation Linux

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

# Création du répertoire de configuration
mkdir -p ~/.config/mcf-driver
cp .env.example ~/.config/mcf-driver/.env

# Lancement
e-mecef-driver

Pour un démarrage automatique, créez un service systemd (voir la documentation avancée).

Configuration

La configuration du driver se fait via un fichier .env. Créez ce fichier à côté du binaire (ou dans le répertoire de configuration de la plateforme).

# Exemple de fichier .env
DEVICE_PORT=
DEVICE_VID=03EB
DEVICE_PID=6119
DEVICE_BAUD=115200

DRIVER_PORT=38917
DRIVER_HOST=127.0.0.1

LICENSE_SERVER_URL=https://votre-serveur-licence.com
LICENSE_FILE=./license.json

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 qui pilote le driver local. Elle comporte trois onglets : Tableau de bord, Paramètres et Service.

Tableau de bord

L'onglet principal affiche l'état en temps réel du système sous forme de trois cartes :

• Driver — état En cours / Arrêté et numéro de version.
• Appareil MCF — Connecté, Non connecté, ou Mode mock (simulé) si MCF_MOCK=true.
• Licence — validité, plan, NIM, quota de factures (émises / max / restantes) et date d'expiration.

Les boutons Démarrer, Arrêter et Actualiser permettent de contrôler le processus driver. Lorsque la licence est absente ou invalide, un formulaire d'activation apparaît directement dans le tableau de bord (champs clé de licence et NIM).

Paramètres

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

• Chemin vers le binaire driver (avec sélecteur de fichier).
• 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, si le driver est en cours d'exécution, il redémarre automatiquement pour appliquer la nouvelle configuration.

Gestion du service système

L'onglet Service permet d'installer le driver comme service système (démarrage automatique au boot), sans avoir à le lancer manuellement. Le gestionnaire utilisé dépend de la plateforme :

• macOS — LaunchAgent launchd (plist utilisateur).
• Linux — service utilisateur systemd.
• Windows — entrée HKCU\Run dans le registre.

Les actions disponibles sont : Installer, Désinstaller, Démarrer et Arrêter le service, selon son état courant.

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 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

Ou via la GUI → Paramètres → Mode cloud (WebSocket) : sélecteur Local / Cloud, champs URL WSS et Clé API.

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