Intégrer l'API Facturino en 1 après-midi

Développer la facturation électronique en interne, c'est entre 3 et 6 mois de travail et un budget de 50 000 à 150 000 EUR : parsing XML CII/UBL, génération PDF/A-3, validation Schematron, connexion aux Plateformes Agréées, gestion des 14 statuts DGFiP... Avec l'API Facturino, vous intégrez tout cela en une après-midi.

Ce guide vous accompagne étape par étape, du premier appel API jusqu'à l'envoi de votre première facture conforme via une Plateforme Agréée.

Étape 1 : obtenir votre clé API

À la création de votre compte Facturino, vous recevez automatiquement une clé de test préfixée fac_test_. Cette clé vous donne accès au sandbox : aucune facture n'est réellement envoyée, aucun email n'est émis, aucune donnée ne transite vers une PA.

Lorsque vous êtes prêt pour la production, générez une clé live préfixée fac_live_ depuis vos paramètres. Les deux environnements sont strictement isolés : une clé test ne peut jamais lire les données de production, et inversement.

// Authentification : header Authorization
const headers = {
  'Authorization': 'Bearer fac_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  'Content-Type': 'application/json'
};

Étape 2 : créer un client

Avant de facturer, il faut un destinataire. Pour pré-remplir les informations légales à partir d'un SIRET (raison sociale, adresse, numéro de TVA intracommunautaire via l'API Sirene de l'INSEE), utilisez d'abord POST /v1/customers/lookup, puis créez le client avec POST /v1/customers (le champ name est requis).

const response = await fetch('https://facturino.com/api/v1/customers', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    type: 'company',
    name: 'Acme SAS',
    siret: '99900000100015',
    email: 'comptabilite@acme.fr',
    address: {
      line1: '15 rue de la Paix',
      city: 'Paris',
      postalCode: '75002',
      country: 'FR'
    }
  })
});

const customer = await response.json();
// customer.id → "cus_a1b2c3d4e5f6..."

Étape 3 : créer une facture

Les montants sont exprimés en centimes d'euro (80000 = 800,00 EUR) et les taux de TVA en centièmes de pourcent (2000 = 20,00 %). Cette convention élimine toute ambiguïté liée aux nombres à virgule flottante.

const invoice = await fetch('https://facturino.com/api/v1/invoices', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    customerId: customer.id,
    buyer: {
      companyName: 'Acme SAS',
      siret: '99900000100015',
      address: {
        line1: '15 rue de la Paix',
        city: 'Paris',
        postalCode: '75002',
        country: 'FR'
      }
    },
    dates: { issued: '2026-04-07', due: '2026-05-07' },
    payment: {
      terms: 'Paiement à 30 jours',
      termsDays: 30,
      method: 'transfer',
      latePaymentRate: '10.00',
      collectionFee: '40.00'
    },
    lines: [
      {
        description: 'Développement API v2',
        quantity: '5',
        unit: 'day',
        unitPrice: 80000,     // 800,00 EUR
        vatRate: 2000,        // 20,00 %
        vatCode: 'S'
      },
      {
        description: 'Maintenance mensuelle',
        quantity: '1',
        unit: 'month',
        unitPrice: 15000,     // 150,00 EUR
        vatRate: 2000,
        vatCode: 'S'
      }
    ],
    notes: 'Merci pour votre confiance.'
  })
}).then(r => r.json());

// invoice.id → "inv_x9y8z7w6v5u4..."
// invoice.status → "draft"

Étape 4 : finaliser la facture

La finalisation est le moment clé. Facturino attribue un numéro séquentiel (transaction atomique, pas de trou de numérotation), valide tous les champs obligatoires et génère automatiquement le Factur-X : un PDF/A-3b contenant le XML CII conforme EN16931 et CIUS-FR.

const finalized = await fetch(
  `https://facturino.com/api/v1/invoices/${invoice.id}/finalize`,
  { method: 'POST', headers }
).then(r => r.json());

// finalized.status → "finalized"
// finalized.number → "FAC-2026-0042"
// Le PDF/A-3b + XML CII est généré automatiquement

Une fois finalisée, la facture est immuable. Impossible de revenir au statut brouillon. Pour corriger une erreur, il faut émettre un avoir (credit note).

Étape 5 : envoyer via la Plateforme Agréée

Un seul appel suffit pour transmettre la facture à la PA connectée par l'utilisateur, qui se charge du routage vers le destinataire et de la transmission des données à la DGFiP. Vous pouvez aussi télécharger la facture via l'API pour un dépôt manuel.

const sent = await fetch(
  `https://facturino.com/api/v1/invoices/${invoice.id}/send`,
  { method: 'POST', headers }
).then(r => r.json());

// sent.status → "sending"
// Puis automatiquement : "deposited" → "transmitted" → "available"

Étape 6 : écouter les changements de statut

Plutôt que de faire du polling, configurez un webhook pour recevoir les événements en temps réel. Facturino signe chaque payload avec HMAC-SHA256 pour garantir l'authenticité.

// Votre endpoint reçoit les événements automatiquement
// POST https://votre-app.com/webhooks/facturino

// Payload reçu :
{
  "id": "evt_abc123def456",
  "object": "event",
  "type": "invoice.available",
  "apiVersion": "2026-03-01",
  "created": "2026-04-07T15:30:00Z",
  "livemode": true,
  "data": {
    "id": "inv_x9y8z7w6v5u4",
    "object": "invoice",
    "status": "available",
    "previous_status": "transmitted",
    "livemode": true
  }
}

Gestion des erreurs

L'API retourne des erreurs au format Stripe-like, avec des informations structurées pour faciliter le débogage :

// Exemple d'erreur 422
{
  "error": {
    "type": "validation_error",
    "code": "missing_required_field",
    "message": "Le champ 'customerId' est requis.",
    "param": "customerId",
    "doc_url": "https://facturino.com/docs/api#invoices",
    "request_id": "req_abc123",
    "hint": "Créez d'abord un client avec POST /v1/customers"
  }
}

Conventions essentielles de l'API

• Montants : toujours en centimes d'euro (entiers). 10000 = 100,00 EUR
• Taux TVA : en centièmes de pourcent. 2000 = 20,00 %, 550 = 5,50 %
• Pagination : cursor-based avec starting_after, limit 25 par défaut (max 100)
• Idempotence : header Idempotency-Key pour éviter les doublons sur les requêtes POST
• Modifications : PATCH (jamais PUT) pour les mises à jour partielles
• Timestamps : ISO 8601 en UTC
• IDs : préfixés par type — inv_, cus_, quo_, crn_, pay_

Comparatif : combien coûte la facturation électronique ?

Approche	Délai	Coût	Maintenance
Développement interne	3-6 mois	50 000 - 150 000 EUR	Équipe dédiée permanente
Connexion PA directe	1-3 mois	20 000 - 50 000 EUR	Suivi des évolutions PA
API Facturino	1 après-midi	0 - 29 EUR/mois	Aucune — Facturino gère tout

Prochaines étapes

Vous avez intégré les bases en 6 étapes. Pour aller plus loin :

• Webhooks avancés : configurez des endpoints pour chaque type d'événement (43 types disponibles)
• Avoirs : émettez des credit notes avec le même workflow (POST /v1/credit-notes)
• Devis : créez des devis convertibles en factures en un clic (POST /v1/quotes)
• E-reporting : les transactions B2C et internationales sont déclarées automatiquement
• SDKs : utilisez nos bibliothèques Node.js, Python, PHP ou Go pour simplifier encore l'intégration

Le sandbox est gratuit et sans limite. Testez l'API en toute sécurité avec votre clé fac_test_, puis basculez en production quand vous êtes prêt.