Changements de l’Admin API de PrestaShop 9.2 : contrats des transporteurs et des réponses

Un client API peut cesser de fonctionner même lorsque l’URL qu’il appelle n’a pas changé. Un champ obligatoire peut être décrit plus précisément, une entité absente peut désormais produire un échec explicite, ou un résultat de requête peut passer par un autre chemin interne de correspondance. Ce sont des questions de contrat qui méritent des tests ciblés.

PrestaShop 9.2 RC1 inclut des travaux sur le domaine des transporteurs et l’API, ainsi qu’un changement pour les requêtes CQRS renvoyant des listes. Cet article examine ces changements concrets et leurs implications pour l’intégration. Il suppose une connaissance de l’Admin API et ne reprend pas les bases de l’authentification ou d’API Platform.

Cet examen est à jour au 26 septembre 2026. RC1 reste une cible d’évaluation ; les exemples ci-dessous décrivent des méthodes de test de contrat, et non des réponses vérifiées d’une boutique en fonctionnement dans ce projet.

Si une réponse API inclut des champs personnalisés, incluez le processus d’intégration du module Extra Properties dans l’examen du contrat plutôt que de présumer que chaque champ enregistré doit être exposé.

La prise en charge des transporteurs concerne le cœur et le module de ressources

Les travaux sur les transporteurs dans le cœur sont liés aux travaux sur les ressources dans ps_apiresources. La PR intégrée au cœur identifie des corrections nécessaires au bon fonctionnement des ressources de transporteurs, notamment des arguments scalaires de requête, le contexte moderne de boutique et une vérification de produit manquant. Changement du domaine des transporteurs et de l’API n° 42022.

Pour les développeurs de clients, la conséquence immédiate est de consigner les deux versions. « Cœur 9.2 » ne décrit pas complètement l’inventaire des ressources installé sur une boutique donnée. Avant d’adopter une opération, examinez la documentation générée dans cette installation et vérifiez sa disponibilité par une requête autorisée en bac à sable.

Ne copiez pas une route proposée dans une discussion d’incident en présumant qu’elle a été livrée. Un changement du cœur peut prendre en charge une ressource empaquetée séparément, et un commentaire de revue peut décrire une itération antérieure. Utilisez ensemble le schéma installé et la révision source correspondante.

Construisez le plus petit jeu de test utile pour les transporteurs : un transporteur connu, un produit associé à la boutique pertinente et un identifiant de produit volontairement inexistant. Gardez les règles d’expédition simples au départ pour ne pas confondre un échec de validation du domaine avec une règle d’éligibilité.

Les schémas de requête générés font partie du contrat

La même PR sur les transporteurs traite la documentation du corps des requêtes dérivée des commandes : propriétés omises, caractère obligatoire et contexte de schéma fourni par les ressources. Elle ajoute également une gestion des valeurs par défaut des opérations avant la correspondance et la validation. Détails des schémas et des valeurs par défaut.

C’est important pour les clients générés. Un schéma obsolète peut inciter un client à omettre des informations nécessaires à l’opération ou à représenter incorrectement des valeurs imbriquées. Régénérer un client sans examiner les différences peut alors introduire des changements bien au-delà de l’opération adoptée.

Capturez le schéma de référence et celui de la candidate depuis leurs installations respectives. Examinez les champs obligatoires, la possibilité de valeurs nulles, les structures des éléments de tableau et les valeurs par défaut. Confirmez les différences qui affectent les opérations réellement appelées par votre client.

Une valeur par défaut documentée ne justifie pas l’envoi systématique de null. Les valeurs omises, nulles et explicites peuvent avoir des significations différentes. Testez chaque état que votre application peut produire et consignez le comportement obtenu.

Pour une opération d’écriture, comparez l’entité enregistrée à la requête, et pas seulement au résultat HTTP. Une requête peut être acceptée alors qu’une valeur par défaut produit un résultat différent de l’attente métier du client.

Les entités manquantes et le périmètre de boutique nécessitent des cas négatifs

Un test de contrat significatif inclut un identifiant qui ne peut pas exister dans le jeu de test. Les travaux sur les transporteurs font échouer explicitement l’affectation de références à un produit inconnu au lieu de ne rien faire silencieusement. Comportement en cas de produit manquant.

Votre client doit traiter cela comme un échec de l’opération métier. Journaliser une synchronisation réussie simplement parce qu’une requête de transport s’est achevée masquerait cette distinction.

Testez aussi une entité réelle dans un contexte de boutique inapproprié. Un identifiant global valide ne prouve pas qu’une opération est valide dans toutes les boutiques. Utilisez le mécanisme de périmètre documenté de l’opération installée et vérifiez l’association ou la valeur résultante dans la boutique prévue.

Évitez de substituer silencieusement la boutique par défaut lorsque le contexte manque. Si votre application exige une opération limitée à une boutique, validez cette exigence avant l’envoi. Une précondition côté client peut empêcher un échec serveur vague et clarifier le périmètre prévu dans les journaux.

Ne confondez pas un résultat d’éligibilité vide avec une erreur. Une requête valide peut correctement ne trouver aucun transporteur éligible. Distinguez ce résultat d’un accès refusé, d’un produit invalide ou d’une exception serveur.

La correspondance des requêtes de liste ne signifie pas que chaque réponse a une nouvelle enveloppe

Une autre modification de la version 9.2 enveloppe les résultats de listes simples provenant d’opérations CQRS hors collection sous une clé interne de correspondance _queryResult. Les résultats associatifs conservent leur comportement de correspondance existant. La PR explique que cette clé permet d’affecter un résultat de liste à une propriété de ressource. Correspondance des résultats de liste n° 42011.

La distinction essentielle est celle entre l’entrée de correspondance interne et la représentation publique de la réponse. Ne demandez pas à tous les clients API d’attendre une propriété de premier niveau _queryResult. La correspondance des ressources et la sérialisation déterminent la structure exposée.

Pour une extension implémentant une ressource adaptée, vérifiez une liste remplie et une liste vide. Le résultat vide est important car le code le traite souvent comme des données manquantes ou un type inattendu. Le client doit recevoir la représentation documentée dans les deux cas.

Si vous conservez des captures de contrat, comparez la structure analysée plutôt que la mise en forme sans importance ou l’ordre des propriétés. Une assertion utile vérifie le type et les valeurs attendus du champ. Une comparaison de texte brut peut échouer sur des changements de sérialisation anodins tout en négligeant un écart sémantique ailleurs.

Ce changement est une amélioration ciblée de la correspondance. Il ne prouve pas que toutes les opérations de collection ou tous les clients existants nécessitent une réécriture.

L’exposition d’Extra Properties ajoute une dimension de contrat de données

Lorsqu’une intégration adopte une propriété nouvellement enregistrée, traitez-la comme une partie du contrat métier. Définissez son propriétaire, son type, le sens d’une valeur vide et son périmètre de boutique ou de langue avant de laisser un autre système l’écrire.

Ne déduisez pas la charge utile externe du libellé administratif d’un champ. Examinez le schéma de ressource installé et un exemple de réponse vérifié. Préservez l’espace de noms du module et la représentation exacte prise en charge dans la correspondance de votre client.

Un champ peut être disponible dans un formulaire administratif sans qu’une intégration ait été configurée ou autorisée à le consommer. Inversement, une valeur exposée peut hériter des autorisations de l’entité parente plutôt qu’avoir une politique distincte au niveau du champ. Vérifiez ce comportement dans la documentation actuelle de la fonctionnalité et dans l’installation.

Pour une nouvelle propriété, ajoutez des cas de cycle complet : écrire une valeur valide, la relire, l’effacer si cela est pris en charge, rejeter une valeur invalide et vérifier qu’une seconde boutique reste inchangée. Séparez ces cas des champs produit ordinaires pour que les échecs identifient la nouvelle surface d’extension.

Si vous n’utilisez pas Extra Properties, n’élargissez pas la charge utile d’écriture de votre client simplement parce que la candidate peut les exposer. Adoptez uniquement les champs dont votre contrat métier a besoin.

Construire un petit processus de comparaison des contrats

L’utilitaire Python suivant compare l’inventaire des chemins et méthodes de deux fichiers JSON OpenAPI enregistrés localement. Il ne récupère pas une boutique, ne s’authentifie pas et ne valide pas le comportement des opérations :

import json
from pathlib import Path

METHODS = {"get", "post", "put", "patch", "delete", "head", "options"}

def operations(filename):
    document = json.loads(Path(filename).read_text(encoding="utf-8"))
    return {
        (method.upper(), path)
        for path, item in document.get("paths", {}).items()
        for method in item
        if method.lower() in METHODS
    }

before = operations("baseline-openapi.json")
after = operations("candidate-openapi.json")
print("Added:", sorted(after - before))
print("Removed:", sorted(before - after))

Utilisez les noms de fichiers des exports de schémas que vous avez réellement enregistrés. Un inventaire inchangé nécessite toujours une comparaison de schémas pour les opérations utilisées. Les paramètres de requête, schémas de corps, schémas de réponse et autorisations peuvent changer sans ajout ni suppression d’un chemin.

Après la comparaison statique, exécutez une petite suite sur des enregistrements synthétiques : lecture autorisée, écriture valide, entrée invalide, entité manquante, résultat vide et périmètre de boutique pertinent. Examinez le résultat persistant de chaque écriture.

Ne capturez pas de jetons dans les jeux de test et ne validez pas de réponses brutes de production dans le dépôt. Masquez les identifiants si nécessaire et utilisez des données clients synthétiques pour que les preuves du contrat puissent être partagées sans risque avec les mainteneurs.

Distinguer prise en charge absente et prise en charge incompatible

Si une opération est absente du schéma de la candidate, notez-la comme indisponible dans ce couple de versions. N’envoyez pas une requête devinée et n’interprétez pas un échec de routage comme une preuve que la nouvelle implémentation du domaine est défectueuse.

Si l’opération existe mais rejette une charge utile documentée, conservez l’extrait de schéma, la requête expurgée et la réponse. Il s’agit d’une autre catégorie de problème de compatibilité qui peut être signalée avec un écart précis de contrat.

Pour les clients générés, conservez la révision du code généré à côté de l’export de schéma. Sinon, un développeur peut tester un serveur actuel avec un ancien client et attribuer au serveur le choix de sérialisation du client. Reproduisez avec une requête minimale prise en charge avant de modifier l’un ou l’autre côté.

Ces distinctions rendent un rapport de migration d’API exploitable : opération indisponible, écart de schéma, défaut de sérialisation et échec de validation métier désignent chacun un responsable différent.

Publier le client pour un couple de versions nommé

Une déclaration de compatibilité doit identifier les versions du cœur et du module de ressources, les opérations adoptées et les éventuelles limitations. Si une nouvelle opération est absente, désactivez explicitement la fonctionnalité qui en dépend plutôt que d’échouer plus tard dans un processus sans rapport.

Lorsqu’une opération renvoie un résultat incertain après un dépassement de délai, effectuez un rapprochement avant de répéter une écriture importante. Les améliorations de schéma de la version 9.2 ne suppriment pas les modes d’échec des systèmes distribués.

La tâche principale du développeur est donc ciblée : examiner le contrat réel des ressources, tester les changements de transporteurs et de correspondance dont vous dépendez, et préserver les preuves que les hypothèses du client restent valides. C’est plus fiable que de considérer la nouvelle version comme une invitation à tout régénérer aveuglément.

Pour le contexte de la plateforme sous-jacente, consultez notre guide de l’Admin API de PrestaShop 9 et appliquez les vérifications propres à chaque version ci-dessus à l’installation que vous évaluez.

Lorsque vous choisissez une extension, parcourez les modules PrestaShop 9 de PrestaSuite et comparez la prise en charge des versions et les exigences d’intégration documentées à vos propres résultats de test.