API et Swagger

L'API REST v1 expose le cœur de SHAU Factur : créer des clients, des devis et des factures, émettre une facture (numérotation continue, document figé), enregistrer des paiements et télécharger l'archive Factur-X (PDF/A-3 + XML CII conforme EN 16931). Côté achats, l'endpoint /factures-recues assure la réception des factures électroniques : une plateforme y dépose les factures adressées à votre entreprise, et les statuts acheteur (approuvée, refusée, payée) s'y posent. Les règles de gestion sont identiques à l'application : totaux recalculés côté serveur en centimes, isolation stricte par compte.

Cas d'usage typiques : facturer depuis votre back-office ou votre site, brancher un outil no-code, récupérer les archives Factur-X pour votre comptable, raccorder la réception à votre plateforme (voir Recevoir les factures fournisseurs).

1. 1

   Ouvrez Réglages → API — Clés d'accès

   Depuis l'application, connecté à votre compte.

2. 2

   Créez une clé et nommez-la d'après son usage

   « Zapier », « script compta »… Un nom clair simplifie la révocation.

3. 3

   Copiez la clé immédiatement

   Elle commence par sfk_live_ et n'est affichée qu'une seule fois. Stockez-la dans un gestionnaire de secrets.

Chaque appel porte l'en-tête Authorization: Bearer sfk_live_…. Les montants sont des centimes entiers (7 500 = 75,00 €), les quantités des millièmes (2 000 = 2), les taux de TVA des dix-millièmes (850 = 8,5 %). Les erreurs renvoient un objet { erreur: { code, message } } avec un message en français.

Quotas par clé : 120 requêtes/minute (écritures : 30/min, génération de PDF et émission : 10/min), suivis par les en-têtes X-RateLimit-*.

Sur une facture, statut suit l'émission, l'envoi et les paiements ; un avoir ne le modifie jamais. Le champ en lecture situation donne l'état de règlement calculé à partir du reste dû (total TTC − paiements − avoirs émis) : statut (dont payee, soldee, annulee_par_avoir), en_retard, reste_du_cents et avoirs_cents. Il vaut null pour un devis.

Un cabinet, ou tout compte qui gère des sociétés, retrouve leurs identifiants dans GET /api/v1/moi (champ entreprises, sociétés non archivées). Pour créer un client, un devis ou une facture, envoyez entreprise_id : il est obligatoire dès que le compte a des sociétés, et refusé s'il n'en a pas (erreur 422). Le client apparaît ensuite dans la liste de cette société ; le devis ou la facture prend le régime de TVA, le territoire et les délais de la société, apparaît dans les listes de cette société et, pour une facture, est numérotée dans la séquence de cette société à l'émission.

Le client d'un devis ou d'une facture doit être rattaché à la société du document : un client d'une autre société du compte, ou un client sans société, est refusé (erreur 422 validation, « client_id : ce client n'est pas rattaché à la société du document »), comme dans l'application. Les clients d'une société se listent par GET /api/v1/clients?entreprise_id=. Un compte sans société n'est pas concerné.

GET /api/v1/clients, GET /api/v1/devis et GET /api/v1/factures acceptent le filtre ?entreprise_id= (UUID, sinon erreur 422), et les listes de devis et de factures le filtre ?client_id= (UUID, sinon erreur 422) ; chaque client et chaque document porte son entreprise_id.

Créer une facture brouillon :

curl -X POST https://factur.shau.fr/api/v1/factures \
  -H "Authorization: Bearer sfk_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "00000000-0000-0000-0000-000000000000",
    "lignes": [
      {
        "designation": "Développement sur mesure",
        "quantite_milliemes": 2000,
        "unite": "jour",
        "prix_unitaire_cents": 45000
      }
    ]
  }'

Émettre puis récupérer la Factur-X archivée :

# Émettre (numérotation + archive Factur-X), puis télécharger le PDF/A-3
curl -X POST https://factur.shau.fr/api/v1/factures/ID/emettre \
  -H "Authorization: Bearer sfk_live_votre_cle"

curl -OJ https://factur.shau.fr/api/v1/factures/ID/facturx \
  -H "Authorization: Bearer sfk_live_votre_cle"

La spécification OpenAPI 3.1 est servie sur /api/v1/openapi.json. Explorez et testez chaque endpoint ci-dessous (« Authorize » pour renseigner votre clé) :