Sandbox Plateforme Agréée : comment tester l'interop avant la production

Avant de mettre en production votre intégration Plateforme Agréée, le passage par la sandbox est indispensable. Voici un guide complet : que tester, comment, et quels pièges éviter.

Pourquoi une sandbox

Risques d'une mise en prod directe

• Factures mal formatées envoyées à de vrais clients
• Statuts mal interprétés côté votre logiciel
• Doublons ou idempotence mal gérée
• Surcharge du serveur PA en cas de batch initial massif

Une journée de test sandbox évite des semaines de litiges clients.

Niveaux de sandbox

Niveau 1 — Mock isolé

La PA expose un environnement complètement isolé, sans communication avec l'annuaire PPF ni les autres PA.

• ✅ Tester les formats Factur-X, UBL
• ✅ Tester l'auth (OAuth2, mTLS)
• ✅ Tester les statuts simples (received, rejected)
• ❌ Pas de test d'interopérabilité réelle

Niveau 2 — Sandbox connectée au PPF de test

La sandbox PA se connecte à un annuaire PPF de test opéré par la DGFiP.

• ✅ Tout le niveau 1
• ✅ Routage entre PA via annuaire de test
• ✅ Cycle complet émetteur → annuaire → récepteur
• ❌ Pas d'envoi réel à la DGFiP prod

Niveau 3 — Pre-prod connectée à PPF prod (rare)

Certaines PA proposent un mode "pre-prod" qui passe par l'annuaire PPF de production mais en mode dégradé / monitoré.

• ✅ Validation finale avant ouverture commerciale
• ⚠️ À utiliser avec parcimonie (impact prod potentiel)

Ce que tester en priorité

1. Authentification

• ✅ OAuth2 client_credentials : token valide
• ✅ Renouvellement avant expiration
• ✅ mTLS si exigé : certificat client accepté
• ✅ Permissions / scopes : invoice:write, invoice:read

2. Émission de facture

• ✅ Facture Factur-X valide (PDF/A-3 + XML CII)
• ✅ Facture UBL 2.1 valide
• ✅ Numérotation continue sans trous
• ✅ Devises EUR et autres
• ✅ Multi-TVA (5.5 %, 10 %, 20 %)
• ✅ Exonération TVA (autoliquidation, hors UE)

3. Statuts

• ✅ received (PA accuse réception)
• ✅ submitted (envoyée à l'annuaire)
• ✅ delivered (livrée au destinataire)
• ✅ rejected (refus, lire le motif)
• ✅ approved (validée par le client)
• ✅ paid (marqué payé)

4. Réception

• ✅ Webhooks de réception fonctionnels
• ✅ Téléchargement des factures fournisseurs
• ✅ Vérification de signature Factur-X
• ✅ Stockage et indexation côté votre logiciel

5. Cas d'erreur

• ✅ Format invalide → 400, lire errors[]
• ✅ SIREN inconnu → 422
• ✅ Token expiré → 401, renouvellement transparent
• ✅ Rate limit → 429, backoff
• ✅ PA indisponible → 503, retry

6. Idempotence

• ✅ Envoi 2 fois la même facture avec même Idempotency-Key → traité une seule fois
• ✅ Envoi 2 fois avec clé différente → 2 factures distinctes

Scénarios de test à dérouler

Scénario 1 — Cycle nominal

1. Authentification OAuth2 → token reçu
2. POST /invoices avec facture Factur-X valide → 201
3. Webhook received reçu
4. Webhook submitted reçu
5. Webhook delivered reçu (sandbox simule la livraison)
6. GET /invoices/{id}/status → delivered

Scénario 2 — Refus

1. POST /invoices avec montant TTC ≠ HT + TVA
2. Réponse 422 avec détail erreur
3. Correction et nouvelle soumission avec Idempotency-Key différent
4. Webhook received reçu cette fois

Scénario 3 — Charge

1. Envoi de 500 factures en parallèle sur sandbox
2. Vérifier que toutes sont reçues
3. Mesurer le temps de réponse moyen
4. Vérifier l'absence de doublons

Scénario 4 — Réception massive

1. La sandbox simule la réception de 100 factures fournisseurs
2. Vos webhooks doivent tous être appelés
3. Vous devez toutes les télécharger et les indexer
4. Vérifier qu'aucune n'est perdue en cas de redémarrage

Scénario 5 — Token expiré pendant un batch

1. Démarrer un batch de 1 000 factures
2. Forcer l'expiration du token (sandbox permet souvent ça)
3. Vérifier le renouvellement transparent et la reprise du batch
4. Aucune facture en doublon, aucune perdue

Scénario 6 — PA indisponible

1. Sandbox simule un crash PA (souvent via header spécial)
2. Vos retries doivent fonctionner avec backoff
3. Reprendre après "redémarrage" simulé
4. Aucune facture perdue

Factures de test recommandées

Profil 1 — Facture simple B2B France

<rsm:CrossIndustryInvoice>
  <ram:ID>TEST-2026-0001</ram:ID>
  <ram:TypeCode>380</ram:TypeCode>
  <ram:IssueDateTime>20260601</ram:IssueDateTime>
  <ram:LineTotalAmount>1000.00</ram:LineTotalAmount>
  <ram:TaxRate>20.00</ram:TaxRate>
  <ram:TaxAmount>200.00</ram:TaxAmount>
  <ram:GrandTotalAmount>1200.00</ram:GrandTotalAmount>
  ...
</rsm:CrossIndustryInvoice>

Profil 2 — Multi-TVA

Lignes mixant 5.5 %, 10 %, 20 %.

Profil 3 — Autoliquidation UE

Client allemand, autoliquidation, mention obligatoire "Autoliquidation - article 196 directive 2006/112".

Profil 4 — Acompte + finale

Facture d'acompte 30 %, puis facture finale référençant l'acompte.

Profil 5 — Avoir

Facture rectificative négative référençant une facture initiale.

Profil 6 — Multi-devise

Facture en USD avec conversion EUR pour la TVA.

Check-list avant passage en prod

Code

• Tous les scénarios précédents passent en sandbox
• Tests automatisés (intégration) en CI/CD
• Logs structurés et exhaustifs
• Monitoring sur erreurs et latence

Sécurité

• Secrets en gestionnaire (pas en dur)
• Rotation périodique configurée
• Pas de log de tokens en clair
• SIRENs masqués dans logs publics

Conformité

• Documentation à jour
• Procédure de rollback définie (si gros bug en prod)
• Plan de support premier mois (équipe dédiée pendant 4-6 semaines)
• Communication aux clients (pré-lancement informatif)

Métier

• Comptabilité briefée
• Service client formé aux nouveaux statuts (disputed, rejected)
• Procédure de relance impayés revue
• Indicateurs de pilotage en place

Pièges fréquents en sandbox

Sandbox trop permissive

Certaines PA sandboxes acceptent des factures mal formées que la prod refuserait. Vérifier la conformité avec un validateur Factur-X officiel indépendant.

Statuts simulés mal réalistes

Sandbox passe parfois trop vite de submitted à delivered. En prod, ça peut prendre plusieurs minutes. Votre code doit gérer la latence variable.

Pas de test de charge

Sandbox limitée à quelques dizaines de requêtes/min. Pour les volumes prod, demander un environnement de charge dédié à votre PA.

Webhooks non testés

Beaucoup d'équipes testent l'émission mais oublient la réception des factures fournisseurs. À tester avec autant de rigueur.

Mauvais paramétrage SIREN

Sandbox accepte parfois des SIRENs fictifs. En prod, votre SIREN est validé strictement, et le routage échoue si mal renseigné.

Durée de tests recommandée

En résumé

• Trois niveaux de sandbox : mock isolé, sandbox + PPF test, pre-prod
• Tester systématiquement : auth, émission, statuts, réception, erreurs, idempotence
• 6 scénarios clés à dérouler : nominal, refus, charge, réception massive, token expiré, PA down
• 6 profils de facture à couvrir : simple, multi-TVA, autoliquidation, acompte, avoir, multi-devise
• Check-list code/sécurité/conformité/métier avant mise en prod
• Pièges : sandbox permissive, statuts simulés, pas de charge, webhooks oubliés
• Durée : 1 jour (freelance) à 3-6 mois (grand compte)