API d’administration PrestaShop 9 : guide pratique pour développeurs
La nouvelle API d’administration PrestaShop 9 est l’un des ajouts architecturaux les plus importants de la génération PrestaShop 9.
Elle est conçue pour améliorer l’ancienne API Webservice grâce à un modèle de sécurité plus moderne, à des opérations orientées métier et à une architecture extensible par les modules.
La nouvelle API repose sur :
- API Platform 3;
- OAuth2 authentification et autorisation ;
- commandes et requêtes CQRS;
- scopes ;
- documentation OpenAPI/Swagger ;
- ressources API définies par les modules.
Elle est donc particulièrement intéressante pour les développeurs qui créent :
- intégrations ERP ;
- intégrations PIM ;
- synchronisation des stocks ;
- plateformes fournisseurs ;
- connexions SaaS ;
- systèmes de gestion des commandes ;
- services de reporting ;
- outils d’automatisation.
Ce guide explique l’architecture, le fonctionnement de l’authentification, la création de clients et la manière dont les développeurs de modules peuvent exploiter l’API.
Note sur les versions : Cet article a été vérifié le 22 septembre 2026 à partir de la documentation actuelle de PrestaShop 9 destinée aux développeurs. L’API d’administration évolue activement : consultez toujours la spécification OpenAPI générée pour la version exacte de la boutique intégrée.
Pourquoi PrestaShop a créé une nouvelle API d’administration
L’ancienne API Webservice de PrestaShop est étroitement liée aux opérations CRUD historiques de type ObjectModel.
Le projet PrestaShop souligne plusieurs limites de cette ancienne approche :
- gestion limitée des permissions et de la sécurité ;
- fonctionnement CRUD élémentaire ;
- architecture historique ;
- maintenance plus difficile ;
- lien étroit avec ObjectModel.
La nouvelle API d’administration poursuit d’autres objectifs.
Elle est conçue pour être :
- plus sûre ;
- plus facile à auditer ;
- plus proche des opérations métier ;
- plus conforme aux normes modernes ;
- extensible par les modules.
C’est important.
Une API e-commerce moderne ne doit pas simplement exposer des enregistrements de base de données.
Elle doit exposer des opérations compréhensibles par le métier.
API Platform 3 : fondement HTTP/API
PrestaShop 9 utilise API Platform 3 pour la nouvelle API d’administration.
API Platform fournit l’infrastructure pour :
- les routes ;
- les ressources API ;
- la sérialisation ;
- la validation ;
- la génération OpenAPI ;
- Swagger UI ;
- les fournisseurs de données ;
- les processeurs.
PrestaShop intègre ensuite sa propre architecture applicative à ce framework.
Le résultat n’est pas un simple CRUD API Platform standard.
Les points de terminaison natifs peuvent appeler des commandes et requêtes CQRS de PrestaShop.
CQRS : lectures et écritures comme opérations métier
PrestaShop utilise CQRS depuis sa migration vers Symfony.
CQRS sépare les opérations qui :
lire les données
des opérations qui :
modifier l'état
L’API d’administration réutilise ce travail.
Selon l’architecture officielle :
- une opération de lecture peut exécuter une requête CQRS ;
- une opération de liste peut utiliser une fabrique de données de grille ;
- une opération d’écriture peut exécuter une commande CQRS.
Cela aide à maintenir un comportement cohérent entre le Back Office et l’API.
Pourquoi CQRS est important
Imaginez deux façons de modifier un produit.
Approche par accès direct à la base de données
requête API
→ UPDATE ps_product ...
Cela peut contourner :
- la validation ;
- les hooks ;
- les règles métier ;
- les entités liées.
Approche par commande applicative
requête API
→ ressource API
→ commande CQRS
→ gestionnaire applicatif
→ règles métier
Le deuxième modèle est généralement plus facile à maintenir cohérent avec le reste de l’application.
Il facilite également les tests du comportement de l’API.
L’API d’administration est activée par défaut
La documentation officielle actuelle de PrestaShop indique que l’API d’administration est disponible dès l’installation de PrestaShop 9.
Il faut néanmoins configurer les clients API et leurs permissions avant qu’une application externe puisse l’utiliser.
Le chemin du Back Office pour gérer les clients est :
Paramètres avancés
→ API d'administration
Les administrateurs peuvent y créer des clients API et leur attribuer des scopes.
La production exige HTTPS
L’API d’administration de PrestaShop impose un accès sécurisé en production.
Le mode développement peut assouplir la vérification HTTPS localement, mais la production exige un HTTPS sécurisé.
Ne créez pas d’intégration qui dépend de la désactivation de la sécurité du transport.
Les identifiants et jetons API sont sensibles.
Ils ne doivent jamais circuler sur HTTP non chiffré dans un réseau de production.
OAuth2 est le modèle d’authentification
L’API d’administration utilise OAuth2.
OAuth2 distingue plusieurs concepts :
- client ;
- serveur de ressources ;
- serveur d’autorisation ;
- jeton d’accès ;
- scopes.
Dans la configuration PrestaShop par défaut :
Application externe = client
PrestaShop = serveur de ressources
PrestaShop = serveur d'autorisation
PrestaShop peut aussi utiliser un serveur d’autorisation externe.
Client Credentials pour les intégrations serveur à serveur
Pour les intégrations normales de machine à machine, la documentation PrestaShop recommande le flux OAuth2 Client Credentials .
Exemples typiques :
- ERP → PrestaShop ;
- PIM → PrestaShop ;
- WMS → PrestaShop ;
- Service SaaS → PrestaShop.
Aucune connexion humaine n’est nécessaire pour chaque requête API.
L’intégration reçoit :
client_id
client_secret
puis les échange contre un jeton d’accès.
Créer un client API dans le Back Office
Allez dans :
Paramètres avancés
→ API d'administration
→ Ajouter un nouveau client API
La configuration du client comprend notamment :
- nom du client ;
- identifiant client ;
- description ;
- durée de validité ;
- état d’activation ;
- scopes.
Utilisez un nom de client descriptif.
Bon :
Synchronisation du stock de l'entrepôt
Mauvais :
api2
Des mois plus tard, l’administrateur doit immédiatement savoir à quoi sert cet identifiant.
Enregistrez immédiatement le secret client
La documentation de l’API d’administration PrestaShop prévient que le secret client généré n’est affiché qu’une fois.
Enregistrez-le de façon sécurisée lors de la création du client.
Ne le mettez pas dans :
- le contrôle de version ;
- la configuration publique ;
- les systèmes de suivi des tickets ;
- les captures d’écran ;
- les journaux.
Si possible, utilisez un secret d’environnement ou un gestionnaire de secrets dédié.
Créer des clients API depuis la CLI
PrestaShop fournit également une commande console :
bin/console prestashop:api-client create CLIENT_ID
Par exemple :
bin/console prestashop:api-client create warehouse-sync
Des options supplémentaires permettent de configurer :
- le nom ;
- la description ;
- les scopes ;
- la durée du jeton.
La documentation présente aussi une option --all-scopes , mais déconseille tous les scopes pour les véritables intégrations en production.
Appliquer le principe du moindre privilège
Chaque client API ne doit disposer que des scopes nécessaires.
Un service de synchronisation des stocks peut nécessiter un accès aux produits ou aux stocks.
Il ne doit pas automatiquement pouvoir :
- gérer des modules sans rapport ;
- modifier tous les clients API ;
- accéder à des opérations client sans rapport.
Si un jeton est volé, des scopes limités réduisent les dommages potentiels.
Une intégration, un client
Évitez d’utiliser le même client API pour :
- ERP ;
- CRM ;
- automatisation marketing ;
- entrepôt ;
- reporting.
Attribuez un client distinct à chaque service.
Avantages :
- identifiants séparés ;
- scopes distincts ;
- révoquer individuellement ;
- meilleure auditabilité.
Si la plateforme marketing est compromise, vous pouvez révoquer ce client uniquement.
Obtenir un jeton d’accès
Avec le serveur d’autorisation interne de PrestaShop, le point de terminaison des jetons est :
/admin-api/access_token
La documentation officielle utilise une requête semblable à :
curl --location 'https://shop.example.com/admin-api/access_token' \
--form 'grant_type="client_credentials"' \
--form 'client_id="warehouse-sync"' \
--form 'client_secret="YOUR_CLIENT_SECRET"' \
--form 'scope[]="product_read"' \
--form 'scope[]="product_write"'
Le serveur d’autorisation renvoie un jeton d’accès.
L’application utilise ensuite ce jeton dans les requêtes API.
Envoyer le jeton Bearer
Les requêtes authentifiées utilisent :
Authorization: Bearer YOUR_ACCESS_TOKEN
Par exemple :
curl --location \
'https://shop.example.com/admin-api/api-client/infos' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Les points de terminaison disponibles dépendent de la version PrestaShop installée et des modules activés.
Ne figez pas dans le code les hypothèses d’un article de blog.
Utilisez la documentation API générée par la boutique cible.
Les scopes font partie de la demande de jeton
Un détail important d’OAuth est qu’un client peut disposer de nombreux scopes, mais le jeton d’accès est émis seulement pour ceux demandés.
Par exemple :
le client autorise :
product_read
product_write
customer_group_read
Un jeton spécifique pourrait ne demander que :
product_read
Ce jeton possède alors des capacités plus limitées.
C’est utile pour réduire encore les privilèges.
Un scope manquant entraîne une erreur d’autorisation
Si un point de terminaison exige un scope absent de votre jeton, PrestaShop renvoie une erreur d’autorisation.
C’est exactement le comportement souhaité.
Une intégration doit échouer clairement au lieu d’effectuer discrètement une opération hors de ses permissions.
Traitez explicitement les codes d’état HTTP dans votre client API.
Les jetons d’accès expirent
La configuration d’un client API comprend la durée de validité des jetons.
Les applications doivent s’attendre à l’expiration des jetons d’accès.
Ne considérez pas un jeton d’accès comme un identifiant permanent.
Un client robuste :
- obtient un jeton ;
- le met en cache de façon sécurisée ;
- suit son expiration ;
- en demande un nouveau si nécessaire.
Ne demandez pas un nouveau jeton avant chaque appel API, sauf si votre architecture le nécessite réellement.
PrestaShop reste toujours le serveur de ressources
La documentation PrestaShop établit une distinction utile.
La boutique est toujours le serveur de ressources qui sert les ressources protégées.
Le serveur d’autorisation peut être :
- PrestaShop lui-même ;
- un serveur d’autorisation externe.
Cela permet aux organisations avancées d’intégrer une infrastructure d’identité centrale si nécessaire.
Serveurs d’autorisation externes
L’architecture de PrestaShop prend en charge des fournisseurs d’autorisation externes.
C’est utile dans les grandes infrastructures disposant déjà d’un système OAuth centralisé.
La documentation officielle fournit les concepts d’intégration et un exemple de serveur d’autorisation externe.
C’est plus complexe que le flux interne par défaut.
Choisissez-le seulement si votre infrastructure a vraiment besoin d’une autorisation centralisée.
Documentation Swagger
L’un des grands avantages d’API Platform est la documentation automatique.
PrestaShop expose des informations Swagger/OpenAPI permettant aux développeurs d’explorer l’API.
En développement, le Back Office propose un lien vers Swagger.
C’est extrêmement utile, car la page Swagger représente l’API réellement exposée par l’installation.
JSON OpenAPI
La documentation de l’API d’administration peut être exposée au format OpenAPI.
La documentation officielle cite :
/admin-api/docs.json
Cette spécification peut être importée dans des outils comme :
- Postman ;
- clients compatibles Insomnia ;
- générateurs de code OpenAPI.
C’est plus sûr que de maintenir manuellement la liste des structures de points de terminaison dans un autre projet.
Générer la documentation API depuis la CLI
PrestaShop fournit aussi :
php bin/console prestashop:generate:apidoc
La sortie peut être redirigée :
php bin/console prestashop:generate:apidoc > api-spec.json
Cas d’usage :
- documentation API ;
- génération de clients ;
- comparaison des versions ;
- tests de contrat ;
- CI.
Versionner la spécification API
Pour une grande intégration, stockez les spécifications OpenAPI générées des versions de PrestaShop prises en charge.
Comparez ensuite les versions.
Par exemple :
prestashop-9.0-api.json
prestashop-9.1-api.json
Une différence peut révéler :
- nouveaux points de terminaison ;
- champs modifiés ;
- nouvelles valeurs obligatoires.
Cela permet d’anticiper les problèmes de compatibilité.
Les modules peuvent ajouter des ressources API
La nouvelle API est conçue pour être extensible par les modules.
PrestaShop recherche les classes de ressources API dans les modules lorsque la convention prévue est respectée.
L’emplacement des modules documenté est :
src/ApiPlatform/Resources
Un module peut ainsi ajouter ses propres ressources API.
Le point de terminaison est utilisable lorsque le module est installé et activé.
Les modules peuvent définir leurs propres scopes
Les fonctionnalités API ajoutées par les modules doivent disposer de leurs propres permissions.
Exemples :
security_audit_read
security_audit_write
supplier_import_read
supplier_import_run
C’est préférable à un accès générique trop large.
Un connecteur SaaS peut recevoir exactement les capacités nécessaires.
Les ressources API utilisent les attributs PHP
L’intégration d’API Platform dans PrestaShop utilise des attributs PHP pour configurer les ressources.
Cela garde la configuration du point de terminaison près de la classe DTO/ressource.
Conceptuellement :
#[ApiResource(
operations: [
// API operation definitions
]
)]
class ExampleResource
{
// fields
}
PrestaShop propose aussi des opérations personnalisées orientées CQRS pour relier les ressources aux commandes et requêtes.
Les providers gèrent les lectures
Pour les ressources API intégrées à CQRS, les abstractions Provider gèrent les opérations de lecture.
PrestaShop comprend des providers pour :
- requêtes sur une seule ressource ;
- listes et données de grille.
Le provider reçoit la configuration de ressource API, transforme les données en requête adaptée et l’envoie au bus.
Les processors gèrent les écritures
Les opérations d’écriture utilisent des abstractions Processor.
Requêtes telles que :
- POST ;
- PUT ;
- PATCH ;
- DELETE ;
peuvent être reliées aux commandes CQRS.
Cela crée un chemin clair :
requête HTTP
→ ressource API
→ processeur
→ commande CQRS
→ bus de commandes
→ gestionnaire
Pourquoi c’est utile aux modules commerciaux
Imaginez un module d’import fournisseur.
Le Back Office a besoin de :
- état de la file ;
- démarrer l’import ;
- relancer les échecs ;
- lire l’état du fournisseur.
Un tableau de bord SaaS peut avoir besoin des mêmes opérations.
Plutôt que de créer des points de terminaison ad hoc tels que :
/modules/mymodule/run.php?secret=...
le module peut s’aligner sur l’architecture de l’API d’administration.
Vous obtenez ainsi :
- OAuth2 ;
- scopes ;
- documentation API cohérente ;
- routage par le framework ;
- réponses standard.
Ne transformez pas chaque longue tâche en requête API unique
L’API d’administration ne remplace pas les files d’attente.
Une requête telle que :
POST /admin-api/import-all-products
ne devrait pas rester ouverte deux heures pendant le traitement de 100 000 produits.
Un meilleur modèle :
POST /imports
→ 202 Accepted
→ identifiant de tâche
Puis :
GET /imports/{id}
peut renvoyer l’état.
Le worker s’exécute séparément.
Concevoir des opérations asynchrones
Pour les traitements volumineux :
API
→ créer une tâche
→ file d'attente
→ processus de traitement
→ progression
Cela assure une latence prévisible de l’API.
L’intégration peut consulter l’état périodiquement ou recevoir un webhook si le module en fournit un.
Rendre les écritures idempotentes
Les réseaux tombent en panne.
Les clients réessaient.
Supposons qu’une intégration envoie :
créer une correspondance produit fournisseur
et subisse un timeout après que le serveur a déjà achevé l’opération.
Si une nouvelle tentative crée une autre correspondance, vous obtenez un doublon.
Utilisez :
- identifiants externes stables ;
- contraintes d’unicité ;
- clés d’idempotence lorsque nécessaire.
Une nouvelle tentative sûre ne doit pas provoquer un deuxième effet métier.
Limiter le débit des opérations coûteuses
Même des clients authentifiés peuvent surcharger une boutique involontairement.
Une erreur de programmation peut envoyer des milliers de requêtes par seconde.
Protégez les points de terminaison personnalisés coûteux avec :
- pagination raisonnable ;
- limites de lot ;
- limitation de débit si nécessaire.
N’exposez pas de point de terminaison renvoyant 500 000 produits entièrement chargés en une seule réponse.
Paginer les listes
Les opérations API de liste doivent être bornées.
Préférez :
page
limit
filters
plutôt que :
donnez-moi tout le catalogue
Pour la synchronisation, les lectures incrémentielles sont généralement plus efficaces.
Utiliser la synchronisation incrémentielle
Si un système de rapports externe connaît déjà le catalogue d’hier, il ne doit pas télécharger tout le catalogue chaque heure.
Utilisez :
- horodatages de modification ;
- curseurs ;
- identifiants d’événements externes ;
- points de reprise métier.
Cela réduit :
- trafic API ;
- charge CPU ;
- charge de base de données.
Gérer explicitement les erreurs HTTP
Votre intégration doit distinguer :
- 400 : erreur de validation ;
- 401 : problème d’authentification ;
- 403 : scope manquant ;
- 404 : ressource introuvable ;
- 409 : conflit, le cas échéant ;
- 429 : limite de débit si votre infrastructure la met en place ;
- 5xx : erreur du serveur.
Ne réessayez pas toutes les erreurs.
Un champ obligatoire manquant ne deviendra pas valide après dix nouvelles tentatives.
Journaliser les identifiants de corrélation
Pour les intégrations complexes, attribuez un identifiant de corrélation à chaque requête ou tâche.
Les journaux peuvent alors relier :
requête externe
→ requête API
→ commande CQRS
→ tâche en arrière-plan
→ appel fournisseur
Cela simplifie considérablement l’assistance.
Ne jamais journaliser les secrets
Ne journalisez pas :
- secret client ;
- jeton Bearer complet ;
- en-têtes d’autorisation.
Nettoyez les journaux de requêtes des données sensibles.
Si les outils de débogage capturent toutes les requêtes HTTP, restreignez l’accès et limitez la durée de conservation.
Renouveler les identifiants
Prévoyez un processus de rotation des secrets clients.
N’attendez pas de soupçonner une compromission.
Une intégration mature peut :
- créer un client de remplacement ;
- déployer un nouveau secret ;
- vérifier le trafic ;
- désactiver l’ancien client.
Des clients distincts rendent cela facile.
API d’administration et ancien Webservice
L’ancien Webservice est toujours présent dans l’écosystème PrestaShop, mais la nouvelle API d’administration représente l’architecture moderne introduite avec PrestaShop 9.
Pour les nouvelles intégrations, évaluez d’abord l’API d’administration.
Les raisons comprennent :
- OAuth2 ;
- scopes ;
- API Platform ;
- CQRS ;
- extensibilité par les modules ;
- documentation OpenAPI générée.
Ne réécrivez pas une intégration historique stable uniquement pour suivre la mode.
Évitez toutefois d’accumuler de la dette technique ancienne lorsque l’API moderne répond déjà au besoin.
Architecture d’intégration suggérée
Une intégration de production peut ressembler à :
ERP / PIM
↓
jeton OAuth2
↓
API d'administration PrestaShop
↓
CQRS
↓
Logique métier
↓
Base de données
Tâches volumineuses :
API → file d'attente → processus de traitement
L’API constitue la frontière.
La file d’attente traite les travaux longs.
Liste de contrôle de sécurité
- HTTPS en production
- Un client API par intégration
- Scopes à privilèges minimaux
- Secrets stockés de façon sécurisée
- Jetons non journalisés
- Expiration des jetons gérée
- Anciens clients désactivés
- Entrées validées
- Grandes opérations asynchrones
- Erreurs API surveillées
Liste de contrôle de développement
- Consulter Swagger actuel
- Exporter la spécification OpenAPI
- Tester les scopes requis
- Tester un jeton expiré
- Tester un jeton invalide
- Tester un scope manquant
- Tester les erreurs de validation
- Tester les nouvelles tentatives
- Tester la pagination
- Tester un module désactivé
Questions fréquentes
L’API d’administration de PrestaShop 9 est-elle activée par défaut ?
Oui. La documentation officielle indique actuellement qu’elle est disponible dès l’installation de PrestaShop 9, mais il faut encore configurer les clients et les scopes.
Quelle authentification utilise l’API d’administration ?
OAuth2.
Quel type d’autorisation utiliser pour une intégration serveur à serveur ?
PrestaShop recommande le flux Client Credentials pour les intégrations serveur à serveur.
Quel framework fait fonctionner l’API d’administration ?
API Platform 3.
L’API d’administration utilise-t-elle CQRS ?
Oui. PrestaShop relie les ressources API aux commandes et requêtes CQRS existantes.
Où créer un client API ?
Dans le Back Office, sous Paramètres avancés → Admin API, ou avec la commande console prestashop:api-client commande console.
Quelle est l’URL du jeton d’accès ?
Avec le serveur d’autorisation interne, le point de terminaison documenté est /admin-api/access_token.
Les modules peuvent-ils ajouter des points de terminaison ?
Oui. L’extensibilité par les modules est un objectif fondamental de la nouvelle API. Les ressources des modules peuvent être chargées depuis src/ApiPlatform/Resources.
Swagger est-il disponible ?
Oui. API Platform génère la documentation API et PrestaShop fournit un accès Swagger/OpenAPI pour l’API d’administration.
Faut-il donner tous les scopes à une intégration ?
Non. La documentation PrestaShop recommande explicitement de limiter chaque client aux scopes strictement nécessaires.