Achats fournisseurs

Le module Achats centralise tout ce qui concerne les commandes fournisseurs : bons de commande (PO), autofacture IA depuis les PDF reçus, réception partielle, mapping automatique vers le stock, et calcul du COGS (Cost Of Goods Sold) pour le bénéfice net.

1. Workflow standard

1. Réception facture fournisseur (PDF par email ou upload manuel)
   ↓
2. Extraction IA (cascade Anthropic → OpenAI → Gemini)
   → JSON structuré : fournisseur, lignes, totaux HT/TVA/TTC
   ↓
3. Validation manuelle + mapping produits
   → ligne extraction ↔ InventoryItem (création ou existant)
   ↓
4. Génération automatique d'un PurchaseOrder (PO-####)
   → statut `received` ou `partial`
   ↓
5. Décrément stock-attendu / incrément stock physique
   ↓
6. COGS HT injecté dans /api/goals/progress (bénéfice net)

2. Autofacture IA — extraction PDF

Upload manuel : /supplier-invoices → bouton "Importer une facture" → sélection PDF → cascade IA. Résultat brut affiché dans une fenêtre dédiée pour validation.

Auto-import par email : configure dans /settings → Achats une adresse de forwarding générée (ex. factures.abc123@invoices.fixvault.fr). Tu transmets toutes tes factures fournisseur à cette adresse → SendGrid Inbound Parse → extraction automatique.

Champs extraits

Fournisseur (nom, SIRET, adresse, email)
Date de facture, n° facture, n° de commande
Lignes : description, quantité, prix unitaire HT, total HT, TVA
Totaux : sous-total HT, frais de port HT, remise, TVA, TTC

Cascade IA

Claude Haiku 4.5 (prioritaire — meilleur rapport qualité/prix sur l'extraction tabulaire)
GPT-4o-mini (fallback si Anthropic indispo)
Gemini 2.0 Flash (dernier recours)

Le résultat est mis en cache 24 h pour ne pas re-payer la même extraction si on rouvre la fenêtre.

3. Mapping produits (Learning DB)

À la première extraction d'un fournisseur, FixVault demande de mapper manuellement chaque ligne extraction vers un InventoryItem. Ces mappings sont enregistrés dans la table SupplierProductMapping :

MSI EAN8056789 → InventoryItem "Écran iPhone 13 OEM"
WAVLINK 32MB     → InventoryItem "Cable USB-C → Lightning"

Aux extractions suivantes du même fournisseur, le mapping est appliqué automatiquement. Le tech voit "12 lignes mappées sur 14" — il complète les 2 nouvelles à la main, et la prochaine fois ce sera 14/14.

Endpoint : GET / POST / DELETE /api/supplier-invoices/mappings.

4. Bon de commande (PO)

Un PO est une commande engagée auprès d'un fournisseur (statut au-delà de draft). Statuts :

Statut	Description
`draft`	Brouillon — pas encore commandé, ne compte pas dans le COGS
`ordered`	Commande passée auprès du fournisseur
`partial`	Réception partielle (au moins 1 item reçu, d'autres en attente)
`received`	Tout reçu — stock incrémenté en totalité
`cancelled`	Annulé — pas dans le COGS

Flux de réception partielle : bouton "Recevoir" sur chaque ligne → quantité reçue ≤ quantité commandée → stock incrémenté de la quantité reçue uniquement → statut PO passe automatiquement à partial (ou received si tout est reçu).

5. COGS et bénéfice net

GET /api/goals/progress calcule le bénéfice net micro-entrepreneur en agrégeant les PO de la période sélectionnée :

COGS HT = Σ totalTTC - Σ totalTVA   (régime normal, TVA récupérable)
COGS    = Σ totalTTC                 (franchise — TVA non récupérable)

Filtre des PO inclus : status IN ('ordered', 'partial', 'received') — les draft et cancelled sont exclus pour ne pas fausser le calcul.

6. Routes API utiles

# Lister les PO en cours
curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://app.fixvault.fr/api/supplier-invoices/purchase-orders?status=ordered,partial"

# Marquer une ligne comme reçue
curl -sS -X PATCH \
  "https://app.fixvault.fr/api/supplier-invoices/purchase-orders/<poId>/items/<itemId>/receive" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"receivedQty": 5}'

Pour la liste complète : voir API & Intégrations § 22.

7. Bonnes pratiques

Forwardez tout : transférez systématiquement vos factures fournisseur à l'adresse d'auto-import — vous gagnez du temps et le COGS est toujours à jour.
Validez avant de mapper : si l'IA s'est trompée (ligne ratée, total faux), corrigez l'extraction avant de mapper, sinon le mapping pollue le learning.
Réception au plus juste : ne marquez "received" qu'après contrôle physique. Une ligne received avec quantité fantôme casse le rapprochement comptable.
Vérifiez la TVA récupérable : si vous êtes en franchise (TVA non appliquée), passez tvaFranchise: true dans tenant.settings.businessContext → le COGS sera calculé en TTC.

1. Workflow standard​

2. Autofacture IA — extraction PDF​

Champs extraits​

Cascade IA​

3. Mapping produits (Learning DB)​

4. Bon de commande (PO)​

5. COGS et bénéfice net​

6. Routes API utiles​

7. Bonnes pratiques​