Architecture

Un appel API en entrée, une facture normalisée, signée et soumise à la clairance en sortie. Voici tout ce qui se passe entre les deux.

En bref

EFact orchestre un pipeline : normalisation des données en XML UBL 2.1, signature électronique XAdES avec votre certificat qualifié, puis transmission à la DGI pour clairance et attribution du visa fiscal. Chaque étape correspond à un statut de la facture. Une fois signée, la facture est verrouillée, journalisée dans une piste d'audit et archivée 10 ans.

Statut de l'intégration DGI

La plateforme nationale d'e-facturation de la DGI n'est pas encore ouverte aux intégrations. L'étape « DGI » décrite sur cette page est aujourd'hui assurée par notre simulateur DGI, qui reproduit le flux de clairance officiel de bout en bout (soumission, validation de signature, référence, QR code, callbacks). Les statuts ACCEPTED / REJECTEDreflètent la décision du simulateur, pas encore celle de l'administration fiscale. Le basculement vers la plateforme officielle se fera sans aucun changement côté client.

Vue d'ensemble

Les SDK, les ERP et le tableau de bord entrent tous par la même bordure. L'authentification résout l'organisation avant que le pipeline ne touche la facture.

Client
Edge
Authentification
Pipeline
DGI

Clients: SDK officiels (Node.js, Python), ERP et SaaS en REST direct, et le tableau de bord pour les humains.
Edge: TLS, chaînes de filtres de sécurité, rate limiting à 300 requêtes/minute par clé.
Authentification: Clés API hachées pour l'API de facturation ; JWT validés auprès du fournisseur d'identité (OIDC) pour le tableau de bord.
Pipeline: Valide, normalise, signe et transmet - puis écrit dans la base de référence et dans la piste d'audit.
DGI: Transmission en mTLS ; les callbacks de clairance reviennent signés en HMAC. Aujourd'hui : le simulateur DGI (voir l'encadré ci-dessus).
Persistance: Base relationnelle comme système de référence, clés UUID, migrations versionnées.

Bordure et gateway

Chaque requête traverse la même bordure durcie.

TLS: Terminaison HTTPS uniquement.
Filtres séparés: Les routes du tableau de bord reçoivent le validateur JWT ; l'API de facturation authentifie ses propres clés. Tout ce qui n'est pas déclaré explicitement est refusé par défaut.
Rate limiting: 300 requêtes/minute par clé (token-bucket), avec un 429 structuré et un Retry-After en cas de dépassement.
Enveloppe uniforme: Chaque réponse, succès ou échec, est { code, message, data, errors }. Les SDK déballent data et lèvent des erreurs typées sinon.

Authentification

Deux plans, isolés par conception. Détails complets sur la page Sécurité.

Plan	Qui	Identifiant	Validation
API de facturation	Serveurs (SDK, ERP)	`efact_sk_...`	Hash SHA-256, organisation résolue depuis la clé
API tableau de bord	Humains	JWT (OIDC)	Signature, émetteur, expiration ; rôle depuis les claims

Pipeline de facturation

POST /v1/invoices exécute un pipeline synchrone et transactionnel : la facture retournée est déjà signée et en route vers la DGI.

Valider
Normaliser
Signer
Transmettre
Clairer

Valider: Schéma et règles métier : ICE, devise, lignes.
Normaliser: Mapping vers XML UBL 2.1, validation contre le XSD officiel, canonicalisation et hash SHA-256.
Signer: Signature XAdES avec le certificat PKCS#12 de l'organisation (RSA/SHA-256).
Transmettre: Soumission en mTLS (au simulateur DGI aujourd'hui).
Clairer: La plateforme de clairance valide, puis assigne une référence et un QR code.

Tout ou rien: Les étapes de validation, normalisation et signature partagent une seule transaction. Si l'une échoue, tout est annulé : aucune facture à moitié traitée n'existe jamais.
Totaux serveur: HT, TVA et TTC sont calculés côté serveur à partir des lignes. Le backend est la source de vérité, pas l'appelant.
Immuabilité: Une fois la facture sortie de PENDING, son contenu est verrouillé. Toute modification ou annulation renvoie 409.

Cycle de vie d'une facture

Les intégrateurs interrogent GET /v1/invoices/{id}/status: un objet léger avec le statut, la référence DGI, le payload QR et les éventuels détails d'erreur.

PENDING

Créée, en attente de traitement.

SIGNED

Normalisée en UBL 2.1 et signée numériquement.

TRANSMITTED

Soumise à la DGI, en attente de clairance.

ACCEPTED

Cleared - référence DGI et QR code assignés.

REJECTED

Refusée par la DGI (code d'erreur et message structurés).

FAILED

Erreur de traitement ou de soumission irrécupérable.

CANCELLED

Annulée par l'appelant avant signature.

Le chemin nominal est PENDING → SIGNED → TRANSMITTED → ACCEPTED ou REJECTED. Une facture peut être annulée depuis PENDING, et une erreur de soumission irrécupérable la place en FAILED.

Résilience et auto-réparation

La plateforme part du principe que la plateforme gouvernementale peut être lente, indisponible ou perdre des messages, et garantit qu'aucune facture n'est jamais silencieusement perdue.

Rattrapage: Re-soumet les factures SIGNED de plus de 2 minutes : couvre les crashs entre le commit et la soumission, ainsi que les erreurs DGI transitoires.
Polling de secours: Ré-interroge la DGI pour les factures bloquées en TRANSMITTED depuis plus de 5 minutes : couvre les callbacks perdus.
Callbacks idempotents: Chaque évènement DGI est dédupliqué par identifiant : retries et rejeux ne peuvent jamais appliquer une transition deux fois.
Côté SDK: Les SDK officiels réessaient les appels sûrs avec backoff exponentiel et jitter, honorent Retry-After, et ne réessaient jamais create.

Artefacts de facture

Les artefacts sont conservés pendant la période d'archivage légal de 10 ans.

Artefact	Endpoint	Contenu
XML signé	`GET /v1/invoices/{id}/xml`	Le document UBL 2.1 signé XAdES, l'original légal
PDF	`GET /v1/invoices/{id}/pdf`	Rendu lisible par un humain
QR code	`GET /v1/invoices/{id}/qr`	Le QR de clairance DGI

Piste d'audit

Chaque transition de statut - déclenchée par l'API, un callback DGI, un planificateur ou un administrateur - écrit une ligne immuable : statut précédent, nouveau statut, acteur, code de motif, motif et métadonnées. Le journal est en ajout seul et interrogeable via l'API (permission AUDIT_READ).

Monitoring et opérations

Santé: Sondes de santé avec des indicateurs dédiés : peut-on joindre la plateforme de clearance, et des factures se bloquent-elles ?
Métriques: Métriques de requêtes et compteurs métier (soumissions, résultats de callbacks, reprises de polling), collectées en continu.
Logs masqués: Signatures, payloads QR, mots de passe et clés privées sont masqués par motif au niveau de la couche de log, avant toute écriture.

Couche de données

Base relationnelle: Système de référence transactionnel.
Clés UUID: Partout : aucun identifiant énumérable.
Migrations: Versionnées et immuables. L'historique du schéma est lui-même une piste d'audit : les migrations ne sont jamais éditées, seulement ajoutées.
Colonnes sensibles: Chiffrées en AES-256-GCM. Voir Sécurité.

Environnements

Le simulateur DGI intégré reproduit le flux de clairance de bout en bout - soumission, vérification de signature, callbacks signés HMAC, scénarios accept/reject - pour tester tout le cycle de vie avant la mise en service de la plateforme nationale.

Environnement	Objet	Cible DGI
Production	`https://api.efact.ma`	DGI production (mTLS) - mock sandboxé jusqu'à l'ouverture de l'intégration officielle
Local / intégrateur	Surcharge `baseUrl` du SDK	Simulateur DGI (cycle de vie complet, signature et callbacks inclus)

Contrat d'API

L'API est définie par un contrat OpenAPI versionné ; les SDK officiels sont générés depuis ce contrat live, donc toujours alignés sur l'API. La plateforme repose sur des standards ouverts : UBL 2.1, XAdES, OAuth2/OIDC.

Questions fréquentes

Comment EFact transforme-t-il une facture en document conforme DGI ?

EFact orchestre un pipeline : normalisation des données en XML UBL 2.1, signature électronique XAdES avec votre certificat qualifié, puis transmission à la DGI pour clairance et attribution du visa fiscal. Chaque étape correspond à un statut de la facture, et le document signé ainsi que ses artefacts sont archivés.

Qu'est-ce que le simulateur DGI d'EFact ?

La plateforme nationale de la DGI n'étant pas encore ouverte aux intégrations en juillet 2026, EFact utilise un simulateur qui reproduit le flux de clairance officiel : soumission, validation de signature, référence, code QR et callbacks. Le basculement vers la plateforme officielle se fera sans changement côté client.

Comment EFact garantit-il l'intégrité des factures ?

Une fois signée ou transmise, une facture est verrouillée et son contenu ne peut plus changer. Chaque transition de statut est inscrite dans un journal d'audit append-only, et les documents sont archivés en stockage immuable pendant 10 ans, ce qui assure une piste d'audit fiable conforme aux exigences fiscales marocaines.