Périmètre

🛠️ API

📘

NEW

Matrice de prix shipping — CRUD complet

Contexte

Le module de livraison s'enrichit d'une matrice de prix permettant aux opérateurs de définir les tarifs de livraison en fonction de plusieurs dimensions : famille logistique, zone de livraison, type de livraison et fournisseur. Cette matrice constitue le référentiel tarifaire utilisé lors du calcul des frais de port au checkout.

Fonctionnement

L'opérateur (OPERATOR) dispose désormais de cinq endpoints pour gérer intégralement la matrice de prix shipping :

• Création en bulk : chaque ligne associe une combinaison unique de dimensions (famille logistique, zone, type de livraison, et fournisseur en contexte marketplace). Le prix (price) doit être ≥ 0, le franco de port (francoAmount) strictement > 0 s'il est renseigné (null = pas de franco). Les éléments valides sont créés et les invalides rejetés avec un message d'erreur détaillé.
• Lecture unitaire et liste paginée : la liste supporte des filtres multi-valués combinés en AND (logisticFamilyIds, shippingZoneIds, shippingTypeIds, supplierIds, plages de dates), avec tri et pagination. Chaque ligne retourne les noms associés aux dimensions (famille, zone, type, fournisseur) pour faciliter l'affichage.
• Modification en bulk : remplacement intégral des champs modifiables (full update), avec les mêmes règles de validation que la création.
• Suppression en bulk : chaque ligne est traitée indépendamment. La suppression est possible même si des commandes passées référencent ces lignes.

La combinaison (logisticFamilyId + shippingZoneId + shippingTypeId + supplierId) doit rester unique — tout doublon est rejeté avec le code F-E-003.

Impact API

Toutes les routes requièrent dj-client: OPERATOR et dj-api-key. Codes d'erreur : F-E-001 (champ manquant), F-E-002 (référence inexistante), F-E-003 (doublon), F-E-010 (valeur invalide), F-E-012 (format d'ID invalide).

📄 Documentation : Shipping Price Matrix

👉 Côté métier : les opérateurs peuvent désormais configurer et maintenir leur grille tarifaire de livraison directement via l'API, avec une gestion fine par famille logistique, zone, type de livraison et fournisseur.

👉 Côté technique : cinq nouveaux endpoints CRUD sur la ressource shipping-prices, avec traitement bulk et validation indépendante par élément.

Exposition de la famille logistique d'une classification

Contexte

Lors de la gestion des familles logistiques dans le Back-Office, il est nécessaire de connaître la famille logistique actuellement rattachée à une classification — que ce soit pour l'afficher dans une liste ou pour avertir l'opérateur avant un changement d'affectation.

Fonctionnement

Un nouvel endpoint permet d'interroger en masse la famille logistique associée à un ensemble de classifications. Pour chaque classification connue, la réponse inclut l'identifiant, le nom de la famille logistique, et un indicateur system qui distingue la famille système par défaut des familles personnalisées.

Règles de comportement :

• Chaque classification possède toujours une famille (au minimum la famille système par défaut) — la réponse n'est jamais null.
• Les identifiants inconnus sont silencieusement omis (Tolerant Reader).
• Ce endpoint sert aussi de pré-check avant affectation : le Back-Office peut afficher un avertissement si la classification est déjà rattachée à une famille non-système différente de la cible.

Impact API

GET /v1/logistic-families/assignments?classificationCategoryIds=cat-001,cat-002 — operationId : ADM-LOGISTIC-FAMILY-560

Requiert dj-client: OPERATOR et la permission LOGISTIC_FAMILY_READ. Le flag system dans la réponse permet de distinguer les familles personnalisées de la famille par défaut.

📄 Documentation : Logistic Families

👉 Côté métier : les opérateurs visualisent directement la famille logistique de chaque classification et sont avertis en cas de réaffectation, avant même de confirmer l'action.

👉 Côté technique : nouveau endpoint de lecture en masse, sans pagination, optimisé en une seule requête (pas de N+1).

Ajout de localisations à une shipping zone

Contexte

La configuration des zones de livraison nécessite de pouvoir y rattacher des pays et, pour la France, des départements spécifiques. Ce nouvel endpoint permet de composer finement le périmètre géographique d'une zone.

Fonctionnement

L'opérateur peut ajouter à une zone de livraison :

• Des pays entiers (type country), avec possibilité d'exclure certains départements français (excludedDepartments).
• Des départements français individuels (type department) — ce type n'est autorisé que pour countryCode: "FR".

Une zone peut combiner pays étrangers et départements français. Si un pays ou département est déjà rattaché à une autre zone, il en est automatiquement retiré avant d'être affecté à la nouvelle zone (pas de doublon inter-zones).

Impact API

PATCH /v1/shipping-zones/{shippingZoneId}/locations — operationId : ADM-SHIPPING-ZONE-210

Requiert dj-client: OPERATOR. Retourne 204 No Content en cas de succès. Code F-E-012 si le type department est utilisé pour un pays non-FR.

📄 Documentation : Shipping Zones And Types

👉 Côté métier : les opérateurs configurent précisément le périmètre géographique de chaque zone de livraison, avec une granularité au département pour la France.

👉 Côté technique : nouveau endpoint PATCH avec gestion automatique du transfert de localisations entre zones.

Shipping types — Modification et suppression

Contexte

Après la création et la consultation des shipping types, les opérateurs disposent désormais des endpoints de modification et de suppression pour gérer le cycle de vie complet de ces ressources.

Fonctionnement

• Modification : remplacement intégral du nom et de la description du shipping type (full update). Le nom est obligatoire (1 à 255 caractères), la description est optionnelle (jusqu'à 10 000 caractères). Passer null ou "" pour la description vide le champ. L'identifiant reste immutable.
• Suppression : la suppression est bloquée tant que des lignes de la matrice de prix sont associées au shipping type (code F-E-042). L'opérateur doit d'abord retirer les lignes de matrice concernées.

Impact API

Requièrent dj-client: OPERATOR. La suppression retourne 409 (F-E-042) si le shipping type est encore référencé dans la matrice de prix.

👉 Côté métier : cycle de vie complet des types de livraison — les opérateurs peuvent renommer, mettre à jour la description, ou supprimer un type devenu obsolète (après nettoyage de la matrice de prix).

👉 Côté technique : deux nouveaux endpoints avec contrôle d'intégrité référentielle à la suppression.