SHAUFactur

API et Swagger

Créer une clé d'API, appeler l'API REST v1 (clients, devis, factures, Factur-X) et explorer la référence OpenAPI.

Ce que permet l'API

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).

Créer une clé d'API

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

    Depuis l'application, connecté à votre compte.

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

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

  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.

Authentification et conventions

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-*.

Exemples

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"

Référence interactive (Swagger)

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é) :

API et Swagger · SHAU Factur