Workflows

Cette page décrit les workflows complets et les dépendances entre les différents endpoints.

Vue d’ensemble des dépendances

┌─────────────────────────────────────────────────────────┐
│                    RÉFÉRENTIELS                         │
│                                                         │
│   POST /articles ◄──── Prérequis pour tout              │
│   POST /customers ◄── Prérequis pour commandes *        │
│   POST /suppliers ◄── Prérequis pour appros *           │
│                                                         │
│   * selon configuration de votre activité               │
└────────────┬──────────────────────────┬─────────────────┘
             │                          │
             ▼                          ▼
┌────────────────────────┐  ┌────────────────────────────┐
│   FLUX COMMANDES       │  │   FLUX APPROVISIONNEMENTS  │
│                        │  │                            │
│   POST /orders         │  │   POST /procurements       │
│         │              │  │         │                  │
│         ▼              │  │         ▼                  │
│   GET /orders/reports  │  │   GET /procurements/reports│
│                        │  │                            │
└────────────────────────┘  └────────────────────────────┘
             │                          │
             ▼                          ▼
┌─────────────────────────────────────────────────────────┐
│                      STOCK                              │
│                                                         │
│   GET /articles/stock      ◄── Snapshot                 │
│   GET /articles/movements  ◄── Détail mouvements        │
│                                                         │
└─────────────────────────────────────────────────────────┘

Workflow 1 : Commande client (Order)

1. Créer les articles — POST /articles

   Tous les articles référencés dans la commande doivent exister. Sinon erreur 211.

2. Créer le client (si config.CheckCustomer est activé) — POST /customers

   Le numéro client (DOManagedCustomerNumber) doit exister. Sinon erreur 217.

3. Envoyer la commande — POST /orders

   La commande contient les lignes avec les références articles et quantités. Utilisez validationOnly=true pour tester sans persister.

4. Attendre le traitement WMS

   Le WMS prend en charge la préparation. Ce traitement est asynchrone.

5. Récupérer le compte-rendu — GET /orders/reports

   Pollez régulièrement avec afterId ou afterDate pour récupérer les résultats :

   • Quantités préparées par ligne
   • Détails des colis (poids, SSCC, numéros de tracking)
   • URL de suivi

6. Suivre le stock — GET /articles/stock / GET /articles/movements

   Les mouvements de sortie sont visibles après expédition.

Note

Le compte-rendu de commande (OrderReport) est généré par le WMS. Il peut y avoir un délai entre l’envoi de la commande et la disponibilité du rapport. Utilisez le mécanisme de polling avec afterId pour une récupération incrémentale.

Workflow 2 : Approvisionnement fournisseur (Procurement)

1. Créer les articles — POST /articles

   Les articles attendus en réception doivent exister dans le référentiel.

2. Créer le fournisseur (si config.CheckSupplier est activé) — POST /suppliers

   Le code fournisseur (SupplierCode) doit exister. Sinon erreur 216.

3. Déclarer l’approvisionnement — POST /procurements

   Contient les lignes avec les articles attendus et les quantités.

4. Attendre la réception WMS

   Le WMS enregistre les réceptions physiques.

5. Récupérer le compte-rendu — GET /procurements/reports

   Pollez pour obtenir :

   • Quantités reçues par ligne
   • Numéros de lot et dates de péremption
   • Détails de chaque réception

Workflow 3 : Mise à jour du référentiel articles

1. Envoi initial — POST /articles

   Créez l’article avec ses codes-barres et variantes logistiques.

2. Mises à jour — POST /articles (même endpoint)

   L’API fait un upsert : si l’article existe (même activityCode + articleReference), il est mis à jour.

3. Verrouillage après réception

   Après la première réception WMS, certains champs sont verrouillés :

   • Les dimensions et poids (si RTopVlNouvelle = false)
   • Les variantes logistiques (si NewLv = false sur la VL 30)
   • Les données alcool

   Ces verrous protègent la cohérence entre le référentiel et le WMS.

Attention

Le mécanisme de verrouillage est automatique et ne peut pas être contourné par l’API. Si vous devez modifier des champs verrouillés, contactez le support pour débloquer l’article dans le WMS.

Gestion des erreurs dans les workflows

Quand un POST retourne un status Mixed (HTTP 206) :

• Les ressources listées dans passed ont été traitées
• Les ressources dans errors n’ont pas été persistées
• Vous pouvez corriger et renvoyer uniquement les ressources en erreur
• L’operationId permet de tracer l’opération dans les logs

{
  "status": "Mixed",
  "operationId": "abc-123",
  "passed": ["CMD_001"],
  "errors": {
    "CMD_002": [
      { "code": "211", "description": "Article [UNKNOWN_ART] inconnu" }
    ]
  }
}