Comment lire et écrire un catalogue WooCommerce par l'API ?

Dès qu'une boutique est alimentée par autre chose que sa propre interface d'administration, la question de l'interface de programmation se pose. Un logiciel de gestion qui pousse les stocks, un tableur qui met à jour les prix, un outil maison qui crée les fiches, une place de marché qui récupère les commandes : tous passent par le même point d'entrée, avec les mêmes contraintes et les mêmes limites. L'API REST de WooCommerce couvre l'essentiel de ces besoins, à condition d'en connaître les particularités, notamment sur la pagination, la gestion des variantes et le débit supportable par la machine. Une intégration écrite sans ces précautions fonctionne parfaitement sur un catalogue de démonstration et s'effondre sur les quinze mille références du client, en général la nuit précédant une mise en ligne.

S'authentifier et se connecter proprement

L'accès repose sur un couple de clés généré depuis l'administration, avec un niveau de droits choisi au moment de la création et non modifiable ensuite. C'est la première décision et elle mérite un peu d'attention, comme nous l'expliquons dans notre article sur la manière de sécuriser une boutique WooCommerce.

Choisir le mode d'authentification

Sur une boutique servie en HTTPS, ce qui doit être le cas de toutes, les clés se transmettent dans l'en tête d'authentification standard, ce qui est simple et sûr. Un second mécanisme, plus complexe, existe pour les connexions non chiffrées et n'a plus aucune raison d'être employé. Certaines configurations de serveur suppriment l'en tête d'authentification avant qu'il n'atteigne PHP, ce qui produit un refus incompréhensible : le contournement passe par une transmission dans les paramètres de requête, à réserver aux cas où la configuration du serveur ne peut pas être corrigée, une clé passée dans l'adresse se retrouvant dans tous les journaux.

Vérifier les droits accordés

Une clé en lecture seule suffit à un flux marchand, à un tableau de bord ou à un export comptable, ce qui couvre la majorité des besoins. Une clé en écriture ne se justifie que pour une intégration qui modifie réellement le catalogue ou les commandes. Créer systématiquement des clés complètes par confort double la surface de risque sans rien apporter, et rend impossible de limiter les dégâts si la clé fuite. Le niveau de droits ne peut pas être modifié après création, il faut donc recréer la clé, ce qui est l'affaire d'une minute mais impose de mettre à jour l'outil qui l'utilise.

Rattacher la clé à un compte dédié

Une clé est associée à un utilisateur WordPress, dont elle emprunte les capacités. La rattacher à un compte dédié à l'intégration, plutôt qu'au compte personnel d'un administrateur, permet de suivre les actions dans les journaux d'activité et évite que le départ d'une personne ne coupe une synchronisation. Ce compte doit disposer du rôle minimal permettant les opérations concernées, le rôle de gestionnaire de boutique suffisant à la quasi totalité des intégrations.

Vérifier la version employée

L'interface est versionnée, et les anciennes versions restent disponibles pour ne pas casser l'existant. Une intégration écrite il y a cinq ans peut fonctionner sur une version dépréciée sans que rien ne le signale, jusqu'au jour où elle est retirée. Le contrôle consiste à vérifier quelle version le code appelle et à comparer avec la version courante, ce qui prend une minute et évite une panne à la prochaine mise à jour majeure, qui survient toujours au mauvais moment.

Tester la connexion avant tout développement

Le premier appel doit être une simple lecture, par exemple la liste des cinq premiers produits, exécutée depuis l'environnement qui hébergera l'intégration. Cela valide d'un seul geste les clés, la configuration du serveur, l'accès réseau, la résolution du nom de domaine et l'absence de pare feu bloquant. Découvrir un blocage réseau après avoir écrit trois cents lignes de code est une perte de temps évitable en cinq minutes, et pourtant fréquente.

Deux interfaces qui cohabitent

Une confusion revient systématiquement et fait perdre du temps : il existe en réalité deux interfaces distinctes sur une boutique WordPress. Celle de WordPress lui même, accessible sans clé pour les contenus publics et avec authentification par jeton pour le reste, expose les articles, les pages, les médias et les utilisateurs. Celle de WooCommerce, accessible avec le couple de clés décrit ici, expose les produits, les commandes, les clients, les remises, les taxes et les rapports. Les deux ont des chemins voisins, des conventions différentes et des modes d'authentification incompatibles, et la documentation de l'une ne s'applique pas à l'autre. Un point d'accès qui refuse obstinément une clé pourtant valable est presque toujours un point d'accès de la première interface interrogé avec les identifiants de la seconde. Vérifier le chemin exact avant de chercher plus loin fait gagner des heures.

Lire un catalogue entier

La lecture paraît triviale et c'est là que les intégrations naïves échouent le plus, parce que la pagination classique se comporte mal sur les gros volumes. Le raisonnement rejoint celui exposé dans notre article sur la manière de modéliser un catalogue produit.

La pagination par numéro de page et sa limite

Le mécanisme standard demande une page et un nombre d'éléments par page, avec un plafond de cent. Il fonctionne bien sur les premières pages et devient très coûteux au delà, la base devant parcourir toutes les lignes précédentes pour atteindre la bonne. Sur un catalogue de vingt mille produits, les dernières pages deviennent lentes au point de dépasser le délai d'exécution, ce qui produit des synchronisations qui échouent toujours au même endroit, symptôme reconnaissable entre tous.

Parcourir par identifiant croissant

La méthode qui tient à l'échelle consiste à trier par identifiant croissant et à demander à chaque appel les éléments dont l'identifiant est supérieur au dernier reçu. Le coût par page reste alors constant quel que soit l'avancement dans le catalogue, et l'interruption en cours de route se reprend exactement là où elle s'est arrêtée. C'est un peu plus de code que la pagination par numéro, et cela transforme une synchronisation fragile en traitement fiable, y compris sur un catalogue qui doublera de taille.

Ne demander que ce dont on a besoin

Chaque produit renvoyé transporte l'intégralité de ses champs, images comprises, ce qui représente plusieurs kilooctets. Quand la synchronisation ne porte que sur les stocks, demander explicitement les seuls champs utiles réduit le volume transféré d'un facteur important et accélère d'autant la lecture. Cette optimisation est disponible sur la plupart des points d'accès et reste largement sous employée, sans doute parce qu'elle n'apparaît pas dans les exemples les plus consultés.

Filtrer par date de modification

Une synchronisation complète quotidienne est rarement nécessaire. Demander uniquement les éléments modifiés depuis le dernier passage réduit le volume de plusieurs ordres de grandeur, et rend possible une synchronisation horaire là où une passe complète prenait une nuit. Le point de vigilance est la gestion du fuseau horaire, qui provoque des oublis discrets quand les deux systèmes ne travaillent pas dans le même référentiel. La précaution consiste à travailler en temps universel de bout en bout et à reculer la borne de quelques minutes, ce qui produit quelques doublons inoffensifs plutôt que des oublis.

Traiter les variantes séparément

Les déclinaisons d'un produit ne figurent pas dans la réponse du produit parent, qui n'en donne que la liste des identifiants : elles se lisent sur un point d'accès distinct, produit par produit. Une synchronisation de catalogue à variantes demande donc un appel par produit parent, ce qui multiplie le nombre de requêtes. C'est la principale source de lenteur des intégrations sur ce type de catalogue, et la seule parade consiste à ne récupérer les variantes que des produits réellement modifiés, ce qui suppose de conserver localement la date de dernière synchronisation de chaque produit.

Écrire sans saturer la boutique

L'écriture est plus délicate que la lecture, parce qu'elle consomme davantage de ressources et qu'elle peut entrer en concurrence avec l'activité réelle des clients. Elle repose entièrement sur la stabilité des références, sujet traité dans notre article sur les identifiants produit stables.

Utiliser les points d'accès par lots

Un point d'accès dédié permet de créer, modifier et supprimer jusqu'à cent éléments en une seule requête. La différence avec cent appels séparés est considérable, non seulement en temps de traitement mais surtout en charge serveur : chaque appel individuel démarre WordPress entièrement, charge toutes les extensions actives et refait le travail d'authentification. Toute intégration qui met à jour plus de quelques dizaines d'éléments doit passer par ce mécanisme, et les rares qui ne le font pas se reconnaissent au temps de synchronisation, qui se compte en heures là où il devrait se compter en minutes. Le point d'accès par lots renvoie par ailleurs un résultat par élément, ce qui permet de savoir précisément lesquels ont échoué au lieu de constater un échec global.

Envoyer uniquement ce qui change

Une mise à jour n'a pas besoin de transmettre l'intégralité de la fiche : envoyer seulement les champs modifiés réduit le volume transmis et surtout le risque d'écraser par mégarde une valeur modifiée entre temps depuis l'administration. C'est un point important sur les catalogues où deux sources écrivent, un logiciel de gestion pour les stocks et une équipe pour les descriptions. Sans cette précaution, chaque synchronisation écrase le travail éditorial de la veille, ce qui finit par décourager l'équipe.

Respecter un rythme raisonnable

La boutique n'impose pas nécessairement de limite de débit, mais l'hébergement en impose souvent une, parfois sans la documenter, et la saturer revient à dégrader le site pour les clients. Un espacement entre les lots, calibré pour rester sous une charge raisonnable, coûte quelques minutes de synchronisation supplémentaires et évite un incident dont le coût se compte en commandes perdues. Les traitements lourds gagnent par ailleurs à être programmés en dehors des heures de commande, et à s'interrompre d'eux mêmes si le temps de réponse de la boutique se dégrade au delà d'un seuil.

Gérer les erreurs et les reprises

Une synchronisation qui s'interrompt doit pouvoir reprendre sans tout refaire ni créer de doublons. Cela suppose de journaliser l'avancement à intervalles réguliers, de rendre les opérations rejouables sans effet cumulatif, et de traiter séparément les erreurs temporaires, qui justifient une nouvelle tentative après un délai croissant, et les erreurs définitives, comme un produit refusé pour donnée invalide, qui doivent être remontées à un humain avec le détail du refus. Un lot en échec ne doit jamais faire échouer silencieusement l'ensemble, ni être considéré comme réussi parce que la requête a répondu.

Écrire un stock sans écraser une vente

La mise à jour des stocks mérite un traitement à part, car c'est la seule donnée que la boutique modifie de son côté pendant que l'outil externe la modifie du sien. Envoyer une valeur absolue calculée il y a dix minutes annule les ventes intervenues entre temps, ce qui produit des survendes le jour d'une forte activité. Trois approches limitent le problème. La première consiste à synchroniser très fréquemment et à accepter un écart résiduel, ce qui convient parfaitement aux catalogues à faible rotation. La deuxième consiste à faire de la boutique la source de vérité du stock et à ne lui envoyer que des mouvements d'entrée, les sorties étant décomptées par elle. La troisième, la plus sûre sur les produits à faible disponibilité, consiste à réserver une marge de sécurité qui absorbe le décalage et qui se règle produit par produit selon le rythme de vente constaté. Le choix se fait produit par produit plutôt qu'en une règle unique, et il doit être écrit quelque part, faute de quoi personne ne saura expliquer une survente six mois plus tard ni décider quoi corriger.

Quand l'interface ne suffit plus

Quelques situations dépassent ce que ce mécanisme permet raisonnablement, et savoir les reconnaître à temps évite de s'obstiner sur une solution inadaptée pendant plusieurs semaines.

Les imports initiaux massifs

Charger cinquante mille produits pour la première fois par cette voie prend des heures et sollicite lourdement le serveur. Un import direct en base, avec un script maîtrisé et testé sur une copie, ou l'outil d'import natif de la plateforme, sont bien plus adaptés à cette opération unique et non répétée. L'interface reprend tout son intérêt ensuite, pour les mises à jour incrémentales qui portent sur quelques centaines d'éléments et s'exécutent en quelques secondes.

Les besoins en temps réel

Interroger la boutique toutes les minutes pour savoir si une commande est arrivée est un gaspillage de ressources considérable, chaque appel démarrant l'application complète pour, la plupart du temps, ne rien trouver. Le mécanisme de notification sortante, où la boutique appelle elle même un point d'accès distant lorsqu'un événement se produit, répond bien mieux à ce besoin et supprime entièrement l'interrogation périodique. Il demande en contrepartie un point d'accès disponible en permanence et une gestion des livraisons manquées, car une notification perdue n'est pas systématiquement réémise. Le filet consiste à doubler ce mécanisme d'une lecture périodique de rattrapage, portant sur une courte fenêtre, qui récupère ce qui aurait été manqué.

Les données que l'interface n'expose pas

Certaines extensions stockent leurs données dans des champs personnalisés que l'interface ne renvoie pas par défaut, ce qui donne l'impression que l'information n'existe pas alors qu'elle est bien présente en base. Il est possible de les exposer par du code, en déclarant ces champs sur les points d'accès concernés, ce qui est infiniment préférable à un accès direct en base depuis un outil externe, lequel contourne toute la logique applicative et casse au premier changement de structure. Cette extension du contrat doit être documentée, car elle constitue désormais une dépendance du système tiers, et parce qu'une mise à jour du code du site peut la faire disparaître sans que personne n'y pense.

Documenter l'intégration

Le dernier travail est documentaire : une note décrivant, pour chaque intégration, ce qu'elle lit, ce qu'elle écrit, à quelle fréquence, avec quelle clé et vers quel système, ainsi que la personne à prévenir en cas de panne. Sans ce document, personne ne sait plus, deux ans plus tard, si une clé peut être révoquée ni pourquoi un stock se remet tout seul à une valeur ancienne. Cette note de suivi tient sur une page et se relit lors de chaque intervention sur le catalogue, où elle évite systématiquement une mauvaise surprise. Elle doit mentionner la date de création de chaque clé et son périmètre exact, deux informations qui manquent presque toujours au moment où l'on cherche à savoir laquelle révoquer sans rien casser.