Architecture technique de la facturation électronique
La facturation électronique repose sur une architecture à plusieurs couches qu'il est important de comprendre avant de développer une intégration :
- Couche données : votre ERP ou logiciel de facturation génère les données des factures (client, lignes, montants, TVA)
- Couche format : les données sont converties en format structuré (Factur-X/PDF, UBL/XML, CII/XML)
- Couche transmission : le fichier formaté est transmis via API à votre PDP ou au PPF
- Couche routage : la plateforme route la facture vers la plateforme du destinataire
- Couche statuts : les mises à jour de statuts (reçue, acceptée, refusée) sont renvoyées via des webhooks ou des callbacks API
L'intégration via API concerne principalement les couches format, transmission et statuts. La couche routage est gérée par les plateformes.
L'API du Portail Public de Facturation
Le PPF expose une API REST documentée sur son portail développeurs. Les principales ressources exposées :
- POST /factures : soumettre une nouvelle facture pour transmission
- GET /factures/{id} : récupérer le statut d'une facture
- GET /factures/recues : lister les factures reçues
- POST /annuaire : inscrire ou mettre à jour l'entrée dans l'annuaire centralisé
- POST /ereporting : transmettre les données de e-reporting
L'API du PPF utilise :
- Protocole HTTPS avec TLS 1.2 minimum
- Format JSON pour les métadonnées et les réponses
- Base64 pour l'encodage des fichiers de factures
- OAuth 2.0 pour l'authentification (avec ProConnect)
Documentation : La documentation complète de l'API du PPF est disponible sur le portail développeurs du PPF (api.portail-facturation.gouv.fr). Des exemples de code et des collections Postman sont fournis pour faciliter les premiers tests.
Les API des PDP
Chaque PDP immatriculée propose sa propre API REST pour l'intégration. Bien que les fonctionnalités soient similaires (emission, réception, statuts, e-reporting), les endpoints, les formats et les mécanismes d'authentification peuvent varier d'une PDP à l'autre.
Les fonctionnalités communes des API PDP :
| Fonctionnalité | Méthode HTTP typique | Description |
|---|---|---|
| Envoi facture | POST /invoices | Soumettre une facture pour émission |
| Statut facture | GET /invoices/{id}/status | Récupérer le statut courant |
| Réception factures | GET /invoices/received | Lister les factures reçues |
| Webhook statuts | Callback POST | Notification push des changements de statut |
| E-reporting | POST /reporting | Transmettre les données de e-reporting |
Authentification et sécurité
La sécurité des échanges API est critique car les factures contiennent des données sensibles :
Mécanismes d'authentification courants
- OAuth 2.0 (client credentials) : flux machine-to-machine adapté aux échanges automatisés. Le plus courant pour les API PDP.
- API Key : clé secrète transmise dans l'en-tête HTTP. Simple mais moins sécurisé qu'OAuth.
- mTLS (mutual TLS) : authentification bidirectionnelle par certificats. Niveau de sécurité maximum, utilisé pour certaines PDP.
Bonnes pratiques de sécurité
- Stockez les credentials API dans un coffre-fort de secrets (HashiCorp Vault, AWS Secrets Manager)
- Ne stockez jamais les API keys en dur dans le code source (risque de fuite via Git)
- Utilisez des comptes de service dédiés avec les permissions minimales nécessaires
- Implémentez des mécanismes de rotation régulière des clés
- Journalisez tous les appels API pour faciliter l'audit en cas d'incident
Formats des échanges API
Les échanges API pour la facturation électronique impliquent plusieurs formats :
Format des factures
- Factur-X : PDF/A-3 avec XML embarqué. Envoyé en base64 ou en multipart/form-data
- UBL 2.1 : fichier XML envoyé directement ou en base64
- CII (Cross Industry Invoice) : fichier XML envoyé directement ou en base64
Format des métadonnées
Les métadonnées accompagnant la facture sont généralement en JSON :
{
"invoiceType": "INVOICE",
"emitterSiren": "123456789",
"receiverSiren": "987654321",
"invoiceDate": "2026-05-01",
"invoiceNumber": "F2026-042",
"totalAmountExclTax": 10000.00,
"totalVatAmount": 2000.00,
"currency": "EUR",
"document": "base64encodedContent..."
}
Tests et environnement sandbox
Les tests en environnement sandbox sont indispensables avant la mise en production :
- Inscription au sandbox PPF/PDP : créez un compte de test et obtenez des credentials sandbox distincts de la production
- Tests unitaires : testez chaque endpoint individuellement (envoi, réception, statuts)
- Tests de bout en bout : simulez un cycle complet (émission → routage → réception → acceptation)
- Tests de cas limites : avoirs, rejets, factures en auto-liquidation, montants nuls
- Tests de charge : si vous avez des volumes importants, testez les performances de l'API sous charge
Comptez au minimum 4 à 8 semaines de tests avant la mise en production pour les intégrations complexes. Pour les intégrations simples (logiciel compatible avec connecteur préfabriqué), une semaine peut suffire.
Bonnes pratiques d'intégration
Pour réussir votre intégration API, adoptez ces bonnes pratiques :
- Implémentez des mécanismes de retry : les appels API peuvent échouer transitoirement. Implémentez des retries avec backoff exponentiel.
- Gérez les webhooks de statuts : plutôt que de poller l'API pour les mises à jour de statut, utilisez les webhooks si disponibles.
- Journalisez tous les échanges : conservez un log de toutes les requêtes et réponses API pour faciliter le débogage.
- Validez les factures avant envoi : intégrez un validateur Factur-X dans votre pipeline pour détecter les erreurs avant soumission à la PDP.
- Gérez les quotas API : les PDP peuvent avoir des limites de débit (rate limiting). Implémentez des mécanismes de throttling dans votre code.
- Documentez votre intégration : rédigez une documentation interne décrivant votre architecture d'intégration, les credentials utilisés et les procédures de maintenance.