Sandbox et mode test : développer sans risque

Tester une intégration de facturation électronique en production, c'est risquer de créer de vraies factures, d'envoyer de vrais emails et de transmettre des données à une Plateforme Agréée. Le sandbox Facturino élimine ce risque : un environnement de test complet, isolé, gratuit et pré-rempli avec des données réalistes.

Qu'est-ce que le sandbox ?

Le sandbox est un environnement miroir de la production. Même API, mêmes endpoints, même format de réponse, mêmes règles de validation. La seule différence : rien ne sort de Facturino.

Aucune facture n'est transmise à une Plateforme Agréée
Aucun email n'est envoyé (les envois sont loggués dans la console sandbox)
Aucun webhook ne touche la production (URLs de destination séparées)
Aucune donnée fiscale n'est déclarée

Pour utiliser le sandbox, il suffit d'utiliser votre clé API préfixée fac_test_. Celle-ci est générée automatiquement à la création de votre compte, sur tous les plans (y compris le plan gratuit).

Données de test pré-chargées

À l'activation de votre sandbox, Facturino crée automatiquement un jeu de données réalistes pour vous permettre de commencer immédiatement :

5 clients fictifs avec des SIRETs valides (préfixe 999, valides au format Luhn mais inexistants dans le registre Sirene)
10 produits avec différents taux de TVA (20 %, 10 %, 5,5 %)
20 factures exemple dans différents statuts (brouillon, finalisée, envoyée, payée, en retard...)

Ces données vous permettent de tester immédiatement la lecture, la pagination, le filtrage et les différents workflows sans rien créer au préalable.

// Lister les clients de test pré-chargés
const customers = await fetch('https://facturino.com/api/v1/customers', {
  headers: {
    'Authorization': 'Bearer fac_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
  }
}).then(r => r.json());

// customers.data → 5 clients avec SIRET 999xxxxxxxxxxxxx
// customers.has_more → false

Simuler les statuts DGFiP

En production, les statuts d'une facture sont mis à jour par la Plateforme Agréée au fur et à mesure du cycle de vie. En sandbox, vous pouvez simuler n'importe quel statut manuellement pour tester votre intégration.

// Simuler que la facture a été approuvée par le destinataire
await fetch(
  `https://facturino.com/api/v1/sandbox/simulate-status/${invoiceId}`,
  {
    method: 'POST',
    headers,
    body: JSON.stringify({ status: 'approved' })
  }
);

Les statuts que vous pouvez simuler couvrent tout le cycle de vie :

Statut	Description
`deposited`	Déposée sur la PA
`transmitted`	Émise (transmise au destinataire)
`available`	Mise à disposition du destinataire
`received`	Prise en charge par le destinataire
`approved`	Approuvée par le destinataire
`refused`	Refusée par le destinataire
`suspended`	Suspendue (en attente d'action)
`rejected`	Rejetée par la PA (erreur technique)
`paid`	Intégralement payée
`partially_paid`	Partiellement payée
`overdue`	En retard de paiement

Chaque simulation déclenche les mêmes webhooks qu'en production, avec le même format de payload et la même signature HMAC-SHA256. Cela vous permet de valider votre endpoint webhook de bout en bout.

Webhooks en sandbox

Le sandbox dispose de sa propre configuration de webhooks. Vous pouvez configurer des URLs de destination différentes pour le test et la production. C'est particulièrement utile pour :

Pointer vers localhost pendant le développement (via un tunnel comme ngrok)
Utiliser un serveur de staging pour les tests d'intégration
Valider votre logique de vérification de signature sans risque

Pas de limites en sandbox

En mode test, les requêtes GET ne sont pas comptabilisées dans votre quota API. Vous pouvez lire, lister et filtrer autant que nécessaire sans impact sur votre forfait. Les requêtes d'écriture (POST, PATCH, DELETE) sont également illimitées en sandbox.

En production, les limites dépendent de votre plan : 1 000 appels/mois (gratuit), 10 000 (Essential) ou 50 000 (Pro).

Réinitialiser le sandbox

Si vos données de test deviennent encombrantes après de nombreux tests, vous pouvez réinitialiser le sandbox. La réinitialisation est toujours complète : elle efface l'ensemble des données de test et recharge le jeu initial (5 clients, 10 produits, 20 factures). L'endpoint n'accepte aucun paramètre — le corps de la requête doit être vide.

// Réinitialisation complète du sandbox (corps vide)
await fetch('https://facturino.com/api/v1/sandbox/reset', {
  method: 'POST',
  headers
});

De test à production en une ligne

Le passage du sandbox à la production ne nécessite qu'un seul changement : remplacer votre clé API. Le code, les endpoints et les structures de données sont strictement identiques.

// Développement (sandbox)
const API_KEY = 'fac_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

// Production — même code, seule la clé change
const API_KEY = 'fac_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

Nous recommandons de stocker la clé dans une variable d'environnement pour automatiser le basculement :

// .env.development
FACTURINO_API_KEY=fac_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

// .env.production
FACTURINO_API_KEY=fac_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

// Dans votre code
const API_KEY = process.env.FACTURINO_API_KEY;

Workflow recommandé

Développez en sandbox : utilisez fac_test_ pour implémenter et tester toute votre intégration
Testez tous les scénarios : simulez chaque statut, testez les erreurs, validez vos webhooks
Validez en staging : déployez sur un environnement de pré-production (toujours avec fac_test_)
Passez en production : remplacez la clé par fac_live_ et déployez

Le sandbox est gratuit sur tous les plans, y compris le plan gratuit. Aucune carte bancaire n'est requise pour commencer à tester. Créez votre compte et commencez à intégrer l'API en quelques minutes.