Installation et prérequis

Prérequis infrastructure

Configuration matérielle (minimale)

Élément	Exigence
CPU	2 cœurs (Intel i3 / AMD Ryzen 3 ou équivalent)
RAM	4 Go DDR4
Stockage	15 Go SSD
Débit	~500 certifications / minute

Système d’exploitation

OS	Versions supportées
Linux (recommandé)	Ubuntu 22.04 LTS+, Debian 12+, RHEL 9+ (glibc 2.31+)
Windows	Windows 10/11, Windows Server 2019+
macOS	macOS 12+ (développement uniquement)

Recommandation : Linux (Ubuntu Server LTS) en production — stabilité, légèreté en ressources et configuration aisée du reverse proxy / TLS.

Réseau

Exigence	Détails
Port local	`23109/TCP` — accessible uniquement en localhost / réseau interne
Port HTTPS	`443/TCP` — exposé par le reverse proxy pour les appels du système de facturation
Accès Internet sortant	HTTPS (`443`) vers les serveurs SFEC + NTP (`UDP/123`)
Latence	< 200 ms vers les serveurs SFEC
Disponibilité	Connexion permanente requise (synchronisation SFEC + horodatage NTP)

Alimentation : prévoyez un onduleur (UPS, autonomie ≥ 30 min) et, en zone à coupures fréquentes, un groupe électrogène. Sans le TCC Server, aucune facture ne peut être émise.

Déploiement

Le TCC Server est livré comme exécutable natif (aucune JVM requise). Au lancement, sélectionnez l’environnement SFEC cible via le profil Spring --spring.profiles.active :

Profil	Environnement SFEC	Usage
`sandbox`	sandbox	Intégration et recette
`prod`	SFEC production	Exploitation réelle

Linux / macOS


# Rendre l'exécutable exécutable (une seule fois)
chmod +x tcc-server
 
# Environnement de test (sandbox)
 
./tcc-server --spring.profiles.active=sandbox
 
# Environnement de production
 
./tcc-server --spring.profiles.active=prod

Alternative multiplateforme : définissez la variable d’environnement SPRING_PROFILES_ACTIVE (sandbox ou prod) avant de lancer le serveur, sans passer d’argument au démarrage.

Le serveur démarre sur le port 23109.

Assistant de configuration (Setup Wizard)

Au premier lancement, ouvrez l’assistant dans un navigateur à l’adresse http://<IP_DU_SERVEUR>:23109/setup :

Identification du terminal

Renseignez le NIU, l’identifiant du terminal, le token de provisionnement (fourni par la DGI sur e-Facture) et l’endpoint SFEC (pré-rempli).

Réclamation des certificats

Le serveur obtient automatiquement le certificat client mTLS (communication sécurisée avec SFEC), la clé de signature et la clé de chiffrement. Aucune action manuelle.

Vérification de la connectivité

Le serveur teste la connexion mTLS vers la plateforme SFEC.

Compte administrateur

Créez le compte du tableau de bord : email, nom complet et mot de passe (≥ 12 caractères, avec au moins une majuscule, une minuscule, un chiffre et un caractère spécial).

Configuration par API (headless — sans navigateur)

L’intégralité du provisionnement peut se faire par API REST, sans ouvrir l’assistant navigateur — idéal pour un déploiement automatisé (script, Ansible, CI/CD, image machine préconfigurée).

Les deux méthodes sont équivalentes : l’assistant navigateur et l’API réalisent exactement le même provisionnement — réclamation du certificat mTLS, vérification de la connectivité SFEC, création de l’administrateur et génération de la première clé API.

1. Vérifier l’état du provisionnement

GET /api/v1/setup/status — aucune authentification. À appeler avant ou après un (re)déploiement.


curl http://<IP_DU_SERVEUR>:23109/api/v1/setup/status


{
  "setupCompleted": false,
  "adminExists": false,
  "activeApiKeyCount": 0,
  "currentStep": 1
}

2. Provisionner le device en un seul appel

POST /api/v1/setup — aucune authentification (renvoie 409 si déjà provisionné). L’opération est atomique : elle réclame le certificat mTLS, vérifie la connectivité SFEC, persiste la configuration, crée l’administrateur et génère la première clé API. En cas d’échec, tout est annulé — l’appel peut être rejoué sans risque.

curl (Linux / macOS)


curl -X POST http://<IP_DU_SERVEUR>:23109/api/v1/setup \
  -H 'Content-Type: application/json' \
  -d '{
    "niu": "M2024XXXXXXXXXXX",
    "token": "SFEC-CLAIM-TOKEN-ABC123",
    "terminalIdentifier": "TCC-CAISSE-01",
    "adminFullName": "Jean Dupont",
    "adminEmail": "admin@exemple.cg",
    "adminPassword": "MotDePasse!2026",
    "apiKeyName": "Caisse principale",
    "branchCode": "HQ",
    "allowedIps": "10.0.0.0/24"
  }'

Réponse 200 OK :


{
  "setupCompleted": true,
  "niu": "M2024XXXXXXXXXXX",
  "terminalIdentifier": "TCC-CAISSE-01",
  "mtlsClientSerialNumber": "01:AB:CD:...",
  "adminEmail": "admin@exemple.cg",
  "apiKey": "ak_rB9e2kJpL8mN4xQ5vT7yU3wZ1aD6gH8j",
  "message": "Setup completed. Save this API key now - it won't be shown again."
}

La clé API (apiKey) n’est renvoyée qu’une seule fois. Conservez-la immédiatement dans un gestionnaire de secrets. Une nouvelle clé pourra être générée plus tard depuis le tableau de bord ou via POST /api/v1/api-keys.

Champs de la requête

Champ	Obligatoire	Contrainte
`niu`	Oui	≤ 50 caractères
`token`	Oui	Token de provisionnement fourni par la DGI
`terminalIdentifier`	Oui	≤ 100 caractères
`adminFullName`	Oui	Nom complet de l’administrateur
`adminEmail`	Oui	Adresse e-mail valide
`adminPassword`	Oui	≥ 12 caractères, avec majuscule, minuscule, chiffre et caractère spécial
`sfecApiEndpoint`	Non	Endpoint SFEC (défaut : selon le profil `sandbox` / `prod`)
`apiKeyName`	Non	Nom de la 1ʳᵉ clé (défaut : `Default API Key`)
`branchCode`	Non	Code de succursale (multi-sites)
`allowedIps`	Non	IP / CIDR autorisés pour la clé (ex. `10.0.0.0/24`)

Créer une clé API

Connectez-vous au tableau de bord (http://<IP_DU_SERVEUR>:23109/dashboard), puis ouvrez Clients API (/dashboard/clients) :

Donnez un nom descriptif à la clé (ex. ERP-Production).
Optionnel : définissez un branchCode (multi-sites) et restreignez les IP autorisées.
Copiez la clé immédiatement — elle ne sera plus affichée par la suite.

Format de la clé : ak_<base64url> (ex. ak_dGhpcyBpcyBhIHRlc3Qga2V5).

Vérification de l’état du serveur : GET http://<IP_DU_SERVEUR>:23109/actuator/health.

Étape suivante → Authentification