Créer, limiter, tester et révoquer une clé API

Ouvrir la gestion des clés

Connectez-vous avec un profil administrateur de la bonne boutique, puis ouvrez Configuration → Webservices → Clés API. Le panneau affiche l’identifiant shopID de cette boutique. Un manager ou un autre collaborateur doit demander la création à un administrateur.

Les appels API nécessitent l’activation des webservices dans les options générales. Le panneau peut proposer la création de clés alors que les webservices sont désactivés ; elles ne deviennent utilisables qu’après leur activation. Une clé d’une boutique ne permet pas d’accéder à un autre établissement en changeant simplement shopID.

La gestion des clés exige une session administrateur dans le logiciel. Posséder une clé API, même avec toutes les autorisations, ne permet pas de créer ou de révoquer les autres clés depuis ce panneau.

Créer une clé pour une application

1. Dans Nouvelle clé API, indiquez un nom reconnaissable : application, prestataire et usage, par exemple Synchronisation du catalogue — Boutique en ligne.
2. Choisissez les autorisations nécessaires. Chaque domaine commence sur Aucun accès ; sélectionnez au moins une autorisation pour enregistrer.
3. Choisissez éventuellement une date d’Expiration future. Une date vide signifie Sans expiration. La clé expire au début de la date choisie, à 00:00 UTC, et non à la fin de cette journée.
4. Cliquez sur Créer une clé, attendez la confirmation puis copiez la valeur key affichée. Relevez aussi shopID pour configurer l’application.
5. Enregistrez la clé dans les paramètres privés de l’intégration ou un gestionnaire de secrets. Communiquez-la uniquement aux personnes chargées de cette application ; ne transmettez pas votre mot de passe personnel à la place.

La clé complète est masquée automatiquement après une minute, ou avec Masquer. Ce masquage ne désactive pas l’accès. Pour une clé non révoquée, Afficher key permet de retrouver sa valeur et Copier de la recopier. Le préfixe visible dans la liste sert à reconnaître la clé ; il ne suffit pas pour appeler l’API.

Choisir les droits nécessaires

Consultation permet de lire les données du domaine. Consultation et modification inclut aussi la lecture et peut autoriser des créations, mises à jour ou suppressions. Aucun accès ne donne aucun droit sur ce domaine. Les autorisations portent sur les domaines de la boutique, sans sélection individuelle de clients, d’articles ou de caisses dans cet écran.

• Catalogue et stock : articles, rayons, groupes, variantes, TVA et remises. La modification permet aussi les changements de stock exposés dans les articles.
• Customers : fiches et coordonnées ; la modification permet de créer, modifier ou supprimer des clients.
• Ventes et commandes : commandes, encours et factures, avec leurs coordonnées clients. La modification permet aussi les encaissements prévus par l’API.
• Rapports et exports : consultation uniquement, avec accès aux données détaillées des exports, pouvant inclure clients et ventes.
• Configuration et utilisateurs : paramètres de boutique et d’intégration, modes de paiement, caisses, livraison et consultation des utilisateurs. La modification de configuration reste un droit étendu.
• Webhooks : abonnements aux événements et historique des livraisons ; la modification permet aussi leur gestion et les relances proposées par l’API.
• Messaging : messages, pièces jointes et dossiers ; la modification permet aussi l’envoi d’emails, les réponses et le classement.

Certaines actions combinent plusieurs domaines : enregistrer une vente en créant ou modifiant aussi une fiche client exige la modification des clients en plus de celle des ventes. Référencer simplement un client existant par son identifiant ne demande pas ce droit supplémentaire. Rechercher ou consulter les clients depuis la messagerie exige à la fois la consultation de Messagerie et de Clients.

La gestion des collaborateurs par API exige toutes les autorisations disponibles ; Configuration et utilisateurs en modification ne suffit pas. Ne donnez pas tous les droits pour résoudre un refus de lecture sans avoir identifié le besoin réel. Inviter et gérer les collaborateurs.

Tester avant de démarrer l’intégration

1. Configurez l’application avec le domaine de votre logiciel et les paramètres shopID et key de la même boutique. Vérifiez que la valeur complète de key a été copiée, sans espace ni coupure.
2. Commencez par une lecture du domaine autorisé. Pour une clé Catalogue et stock en Consultation, un outil de test API peut envoyer une requête POST vers /workers/getPlus.php, avec un corps de formulaire contenant shopID, key et format=json. Cette lecture ne crée ni vente, ni paiement, ni client.
3. Contrôlez le résultat retourné et la bonne boutique. Un catalogue vide peut être un résultat normal. Ne vous fiez pas seulement au statut HTTP ou au fait que l’application affiche une page : consultez aussi le message ou les données de la réponse.
4. Si vous vérifiez aussi un refus de droit, utilisez une autre route de consultation non autorisée par cette clé. Ne testez pas une interdiction en essayant de créer un paiement, d’envoyer un email ou de supprimer une donnée réelle.
5. Cliquez sur Actualiser dans le panneau des clés pour consulter Dernière utilisation, puis testez le fonctionnement attendu avec votre prestataire. Pour les écritures, utilisez une boutique de test adaptée et ses propres identifiants avant la boutique réelle.

La date de dernière utilisation indique qu’un appel a été autorisé. Elle est informative, actualisée au plus une fois par minute, et ne prouve pas à elle seule que tout le traitement métier a réussi. Jamais ne constitue pas un journal exhaustif ni une preuve d’absence de toute tentative.

Il n’y a pas de bouton de test métier dans ce panneau : le test se fait depuis l’application ou un outil API. N’élargissez pas les droits d’une clé uniquement pour utiliser un exemple de test qui concerne un autre domaine. Documentation technique des lectures · Créer une boutique de test.

Modifier les droits ou l’expiration

Dans Clés de cette boutique, choisissez Modifier sur la clé concernée, ajustez le nom, les autorisations ou l’expiration, puis Enregistrer. Le changement ne génère pas une nouvelle valeur key. Une clé expirée mais non révoquée peut recevoir une nouvelle date future ; vérifiez que vous souhaitez bien réactiver cette même clé.

Les droits et le statut sont relus lors des appels. Les nouvelles restrictions s’appliquent dès l’appel suivant ; un appel déjà autorisé peut finir. Vérifiez les fonctions utilisées par l’application après une réduction des droits et demandez au prestataire de traiter les refus sans répétition aveugle.

Remplacer, révoquer ou supprimer une clé

1. Pour un remplacement planifié, créez une nouvelle clé dédiée avec les droits voulus, configurez-la dans l’application puis vérifiez son fonctionnement.
2. Sur l’ancienne clé, choisissez Révoquer et confirmez. Les appels suivants utilisant cette clé sont refusés. Un appel déjà autorisé peut se terminer.
3. Vérifiez l’état Révoquée et l’arrêt de l’ancien accès. La révocation est définitive : la clé ne peut plus être affichée ni réactivée. Une nouvelle clé est nécessaire pour rétablir l’accès.

Supprimer retire définitivement la clé de la liste et invalide aussi son accès. Révoquer permet de garder une ligne identifiable dans le panneau, avec son état. Ces actions ne défont pas les ventes, messages, paiements ou autres changements déjà réalisés par l’intégration.

En cas d’exposition de la clé, révoquez l’accès concerné sans attendre la fin d’un remplacement planifié, puis configurez et testez le nouvel accès. Prévenez les personnes qui gèrent l’application de l’interruption attendue.

Déconnecter un appareil, changer un mot de passe, activer la double authentification ou retirer un accès collaborateur ne révoque pas automatiquement une clé API indépendante. Contrôlez les clés remises à un prestataire ou à un collaborateur lors de son départ. Appareils et sessions.

Anciennes clés : organiser le remplacement

Les anciennes clés de boutique restent acceptées avec leurs accès historiques. Elles ne sont pas forcément présentes dans la liste des clés dédiées. Créer une clé limitée, modifier ses droits ou la révoquer ne retire pas l’accès d’une ancienne clé encore utilisée ailleurs.

Pour migrer une intégration, identifiez les applications qui partagent l’ancienne clé, attribuez-leur des clés dédiées et testez-les. Si l’ancienne clé doit être retirée, contactez l’assistance pour organiser son remplacement et le contrôle des intégrations. Ne supposez pas qu’un changement de mot de passe a coupé cet accès.

Si la création ou le test échoue

• Session expirée ou profil changé : rechargez la page et vérifiez le profil administrateur et la boutique avant de poursuivre.
• Après une erreur réseau lors de la création, de la modification ou de la révocation : utilisez Actualiser pour vérifier la liste et l’état avant de recommencer. La demande peut avoir été appliquée sans confirmation reçue.
• Clé refusée par l’application : vérifiez shopID, la valeur complète de key, l’activation des webservices et l’état Active, Expirée ou Révoquée. Un refus de permission demande de vérifier la route utilisée et ses autorisations ; il ne nécessite pas forcément de recréer la clé.
• Gestion indisponible ou impossible d’afficher le secret : contactez l’assistance avec le message, la boutique et le nom de la clé, sans envoyer sa valeur. Une indisponibilité de l’affichage ne prouve pas que l’accès API a été révoqué.

Authentification API et compatibilité · Préparer une demande à l’assistance.