Documentation MCF : installation et API REST

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 ou Datamega FIS-NANO. Selon l'édition, une même installation peut piloter plusieurs profils indépendants avec une licence commune. L'édition standard gère 1 MCF ; toute capacité à partir de 2 MCF est disponible uniquement sur commande. 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. Ce téléchargement public prend en charge 1 MCF. Pour plusieurs MCF, commandez une édition personnalisée auprès de notre équipe.
2. Placez le fichier dans un répertoire de votre choix (ex : C:\e-mecef\)
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 puis décompressez l'archive universelle e-mecef-mac-install.zip, compatible Intel et Apple Silicon
2. Ouvrez le Terminal dans le dossier décompressé puis exécutez ./install-macos.sh
3. Au premier lancement, macOS peut demander une autorisation de sécurité (Préférences Système → Sécurité)
4. 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.

Capacité et profils multi-MCF

MCF_CAPACITY est intégrée au binaire lors de sa compilation. La définir dans le fichier .env ne change donc pas la capacité. Utilisez MCF_COUNT pour activer uniquement le nombre nécessaire. Si cette valeur dépasse la capacité, la GUI et le driver refusent la configuration avec une erreur explicite.

MCF_COUNT=2

MCF1_NAME=Caisse principale
MCF1_DEVICE_KIND=eltrade
MCF1_DEVICE_PORT=COM8
MCF1_DRIVER_HOST=127.0.0.1
MCF1_DRIVER_PORT=38917
MCF1_DRIVER_MODE=local

MCF2_NAME=Caisse Datamega
MCF2_DEVICE_KIND=datamega
MCF2_DEVICE_PORT=COM7
MCF2_DRIVER_HOST=127.0.0.1
MCF2_DRIVER_PORT=38918
MCF2_DRIVER_MODE=cloud
MCF2_DRIVER_WSS_URL=wss://e-sfe.bf/api/mcf-ws
MCF2_DRIVER_API_KEY=cle_api_propre_au_profil_2

LICENSE_SERVER_URL=https://e-mecef.bf

Chaque profil actif doit utiliser un port série, un port HTTP et un journal d'opérations distincts. Chaque profil cloud utilise aussi sa propre clé API. La licence et son compteur de factures restent communs. Les anciennes variables sans préfixe configurent encore le premier profil lorsqu'aucune variable MCF1 équivalente n'est définie.

Détection automatique du port série

Si MCF<n>_DEVICE_PORT est vide, le driver recherche automatiquement le MCF par son identifiant USB (VID:PID). Avec MCF<n>_DEVICE_KIND=auto, il distingue aussi Eltrade et Datamega. 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).
• Nombre de profils actifs et capacité maximale affichés sous la forme 1/1 ou 2/6.
• Un module, un port série, une adresse et un port HTTP propres à chaque profil actif.
• 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 par profil — 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, chaque profil actif expose une API REST sur son propre port, à partir de http://127.0.0.1:38917 (mode local). En activant le mode cloud, le profil initie sa propre 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 → profil MCF → 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 :

MCF1_DRIVER_MODE=cloud
MCF1_DRIVER_WSS_URL=wss://e-sfe.bf/api/mcf-ws
MCF1_DRIVER_API_KEY=sk_mcf_1_xxxxxxxxxxxx   # clé propre au profil

Authentification

La clé API (MCF<n>_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 /api/mcf-ws HTTP/1.1
Host: e-sfe.bf
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: <clé générée automatiquement>
Sec-WebSocket-Version: 13
Authorization: Bearer sk_mcf_1_xxxxxxxxxxxx
X-MCF-Profile-Id: mcf-1

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, chaque profil 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

Chaque profil actif expose une API REST sur son port configuré. Le premier utilise par défaut http://127.0.0.1:38917. Les profils suivants utilisent 38918, 38919, etc. Les routes protégées nécessitent la licence commune valide.

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

Validation et idempotence

POST /bill valide le JSON et les règles du référentiel E-MeCeF Burkina avant l'accès au terminal. Une requête invalide renvoie HTTP 400 avec le code VALIDATION_ERROR et des erreurs détaillées par champ.

Fournissez un en-tête Idempotency-Key stable. Une opération fiscalement refusée renvoie OPERATION_REJECTED ; corrigez la demande puis utilisez une nouvelle clé. Une erreur de transport après envoi renvoie RESULT_INDETERMINATE et doit être rapprochée avant toute nouvelle certification.

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