G-Stock — Facture électronique (Factur-X) & API REST

Document destiné aux développeurs, intégrateurs et comptables. Il explique l'utilité de la facture électronique dans G-Stock et surtout comment utiliser l'API REST, pas à pas, avec des exemples prêts à copier-coller.

Partie A — Facture électronique (Factur-X)

A.1 En quoi c'est utile

Une facture G-Stock finalisée n'est pas un simple PDF : c'est un PDF/A-3 contenant un XML structuré (norme CII, profil MINIMUM — urn:factur-x.eu:1p0:minimum). Un seul fichier, lisible par un humain ET par une machine.

Concrètement, ça apporte :

1. Interopérabilité / zéro ressaisie — le comptable, le client ou une plateforme (PDP/PPF) importe la facture et récupère automatiquement montant, TVA, numéro, dates… sans re-taper.
2. Inaltérabilité (valeur légale) — chaque facture finalisée est verrouillée et chaînée par une empreinte SHA-256. Toute modification ultérieure casse la chaîne et devient détectable → exigence anti-fraude à la TVA.
3. Export FEC — le Fichier des Écritures Comptables (format réglementaire) s'exporte pour un contrôle fiscal (ventes et achats).
4. Conformité future — pour les clients en France / UE, la facturation électronique devient obligatoire (2026-2027). G-Stock les rend prêts sans logiciel comptable supplémentaire.

Nuance : l'obligation Factur-X est surtout française/européenne. Sur les marchés sans mandat e-invoicing (ex. Madagascar), l'intérêt immédiat est qualitatif (factures pro, inaltérables, exportables).

A.2 Comment ça marche dans G-Stock

À retenir : une fois finalisée, une facture ne se modifie plus (inaltérabilité). Pour corriger, on émet un avoir ou une nouvelle facture.

Partie B — API REST

L'API ouverte de G-Stock permet de connecter votre boutique en ligne, votre outil de BI ou tout autre système à vos données G-Stock. Elle est en JSON, authentifiée par token, et chaque appel est strictement limité aux données de votre entreprise (isolation multi-tenant).

B.1 Prérequis

Avant de commencer, il vous faut :

1. Un compte G-Stock actif (essai gratuit ou abonnement). Vos identifiants de connexion servent aussi à l'API.
2. Le ou les modules concernés activés pour votre entreprise (menu Modules) : - /api/produits/ nécessite le module Produits (catalogue) ; - /api/clients/ nécessite le module Clients ; - /api/commandes/ nécessite le module Commandes (ventes).
3. HTTPS : tous les appels se font en https://.

💡 Pour tester tout de suite sans créer de compte, utilisez l'espace de démonstration public : identifiants demo / demo. (Ses données sont réinitialisées chaque jour.)

B.2 Démarrage rapide — en 3 étapes

Étape 1 — Définir l'adresse de base. C'est l'adresse de votre G-Stock :

BASE="https://stock.rankup-ai.com"

Étape 2 — Obtenir votre token (une seule fois ; réutilisable ensuite) :

curl -s -X POST "$BASE/api/token/" \
  -d "username=demo&password=demo"

Réponse :

{ "token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" }

Étape 3 — Appeler l'API avec ce token dans l'en-tête Authorization :

TOKEN="9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"

curl -s "$BASE/api/produits/" \
  -H "Authorization: Token $TOKEN"

✅ Vous recevez la liste de vos produits en JSON. C'est tout : vous êtes connecté à l'API.

B.3 Adresse de base & format

https://stock.rankup-ai.com          # votre domaine G-Stock

• Toutes les réponses sont en JSON (Content-Type: application/json).
• Pour explorer l'API dans un navigateur : ouvrez /api/ (interface navigable) ; vous pouvez vous y connecter en session via /api-auth/.

B.4 Authentification (token)

POST /api/token/ avec vos identifiants renvoie un token. Les deux formats sont acceptés :

# formulaire
curl -s -X POST "$BASE/api/token/" -d "username=VOTRE_LOGIN&password=VOTRE_MDP"

# ou JSON
curl -s -X POST "$BASE/api/token/" \
  -H "Content-Type: application/json" \
  -d '{"username":"VOTRE_LOGIN","password":"VOTRE_MDP"}'

Ensuite, chaque requête porte l'en-tête :

Authorization: Token VOTRE_TOKEN

Le token ne change pas tant que vous ne le régénérez pas. Traitez-le comme un mot de passe.

B.5 Ressources & permissions

Pagination — les listes renvoient 25 éléments par page :

{ "count": 128, "next": "https://.../api/produits/?page=2", "previous": null, "results": [ ... ] }

Passez à la page suivante avec ?page=2, ou suivez simplement le champ next.

B.6 Exemples d'appels (curl)

Dans tous les exemples : AUTH="Authorization: Token $TOKEN".

Lister les produits :

curl -s "$BASE/api/produits/" -H "$AUTH"

Exemple de produit renvoyé :

{
  "id": 12,
  "nom": "Ordinateur portable 14\"",
  "reference": "REF-20261018-12",
  "categorie": "Informatique",
  "category": 3,
  "quantite": 25,
  "quantite_disponible": 25,
  "prix_achat": "420.00",
  "prix_vente": "560.00",
  "seuil_minimum": 5,
  "seuil_alerte": 10,
  "unity": "piece",
  "etat_stock": "disponible"
}

Champs en lecture seule : reference, categorie, quantite_disponible, etat_stock.

Récupérer un produit précis :

curl -s "$BASE/api/produits/12/" -H "$AUTH"

Créer un produit (la category doit appartenir à votre entreprise ; la reference est auto-générée) :

curl -s -X POST "$BASE/api/produits/" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{
        "nom": "Souris sans fil",
        "category": 3,
        "quantite": 40,
        "prix_achat": "6.50",
        "prix_vente": "12.90",
        "seuil_minimum": 5,
        "seuil_alerte": 10,
        "unity": "piece"
      }'

Règles de validation (reprises du modèle) : prix_vente ≥ prix_achat et seuil_alerte > seuil_minimum.

Mettre à jour partiellement (ex. ajuster le prix) :

curl -s -X PATCH "$BASE/api/produits/12/" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"prix_vente": "575.00"}'

Lister les clients :

curl -s "$BASE/api/clients/" -H "$AUTH"

Lister les commandes (avec lignes et total TTC) :

curl -s "$BASE/api/commandes/" -H "$AUTH"

{
  "id": 7,
  "reference": "CMD-0007",
  "client": "SARL Exemple",
  "status": "Completed",
  "order_date": "2026-05-14",
  "total_amount": "1084.00",
  "total_ttc": "1300.80",
  "items": [
    { "produit": "Ordinateur portable 14\"", "quantity": 2, "price": "560.00" }
  ]
}

B.7 Exemple complet en Python (requests)

import requests

BASE = "https://stock.rankup-ai.com"

# 1) obtenir le token
r = requests.post(f"{BASE}/api/token/",
                  data={"username": "demo", "password": "demo"})
r.raise_for_status()
token = r.json()["token"]
headers = {"Authorization": f"Token {token}"}

# 2) parcourir TOUS les produits (en suivant la pagination)
url, produits = f"{BASE}/api/produits/", []
while url:
    data = requests.get(url, headers=headers).json()
    produits += data["results"]
    url = data["next"]

print(len(produits), "produits")

# 3) créer un produit
nouveau = requests.post(f"{BASE}/api/produits/", headers=headers, json={
    "nom": "Souris sans fil", "category": 3, "quantite": 40,
    "prix_achat": "6.50", "prix_vente": "12.90",
    "seuil_minimum": 5, "seuil_alerte": 10, "unity": "piece",
})
print(nouveau.status_code, nouveau.json())

B.8 Codes de réponse

B.9 Cas d'usage typiques

• Synchro e-commerce — après une vente sur votre site, PATCH /api/produits/{id}/ pour ajuster le stock ; ou lecture régulière pour éviter la survente.
• Tableau de bord / BI — récupérer commandes et totaux pour alimenter un reporting.
• Réversibilité — extraire vos produits, clients et commandes à tout moment (aucun enfermement).

B.10 Sécurité & bonnes pratiques

• Le token vaut un mot de passe : ne l'exposez jamais côté client public ; gardez-le en secret côté serveur.
• Toujours en HTTPS.
• Isolation : un token ne lit/écrit que les données de son entreprise — un id d'une autre entreprise renvoie 404.
• En cas de fuite, régénérez le token (l'ancien est alors invalidé).

Récapitulatif

• Factur-X = factures conformes, inaltérables (chaîne SHA-256), export FEC → conforme & crédible.
• API REST ouverte (token, JSON, multi-tenant) = G-Stock s'intègre à votre écosystème, sans double saisie ni enfermement.

Ensemble : une solution conforme ET ouverte, adaptée aussi bien à l'usage quotidien qu'à l'intégration dans un système d'information existant.