PAGE

Docs API

Cette page comporte deux parties : les adresses publiques lisibles (sans clé, lues directement par les moteurs de recherche et les robots d'IA) et le canal skill de connexion à un Agent IA (nécessite un jeton de site, pour que des Agents comme WorkBuddy lisent et écrivent sur ce site).

I. Adresses publiques : sans clé

AdresseUsageParamètresÉtat mesuré
/sitemap.xmlIndex des pages publiques du siteAucun200
/robots.txtRègles d'explorationAucun200
/llms.txtDescription du site et répertoire des adresses publiques pour les robots d'IAAucun200
/api/geo/v1/capabilitiesDéclare les champs lisibles et la liste des adresses publiques du siteAucun200
/capi/geo/listListe le contenu public (produits / catégories / pages / articles)type, page, pageSize, updated_since200
/capi/geo/product/infoVue de connaissance publique d'un produithandle200
/capi/geo/entity/infoVue publique des connaissances d'une entité (pages, etc.)entity_type, entity_id200

Retour uniforme { code, message, data }, code 200 indique un succès. Seul le contenu déjà public est renvoyé : produits en ligne, pages et articles publiés.

II. Connexion à un Agent IA (canal skill)

En bref : adresse d'interface + jeton de site, deux valeurs à saisir dans l'Agent pour l'utiliser. Le jeton équivaut aux droits d'administration du site ; placez-le uniquement dans l'en-tête de requête, ne l'insérez pas dans l'URL et ne le commitez pas dans un dépôt de code.

1. Obtenir les deux valeurs

  1. Connectez-vous au back-office et ouvrez la page « Connexion IA » dans la navigation de gauche.
  2. La page affiche deux lignes : adresse d'interface (fixe sur ce site : /api/skill, adresse complète https://votre-domaine/api/skill) et jeton d'accès (commençant par sk_).
  3. Cliquez sur le bouton de copie à droite ; vous pouvez aussi cliquer sur « Copier les instructions de connexion » pour transmettre en une fois l'adresse, l'authentification et la méthode de découverte des interfaces à l'Agent.

La réinitialisation du jeton invalide immédiatement l'ancien jeton ; les Agents déjà en service doivent être mis à jour en conséquence, sinon tous les appels renverront 401.

2. Authentification

Toutes les interfaces skill n'acceptent qu'un seul en-tête : X-Site-Token: votre jeton. Le jeton dans les paramètres d'URL n'est pas pris en charge — l'URL figure dans les journaux d'accès, le Referer et l'historique du navigateur, ce qui revient à exposer les droits d'administration.

Appel minimal (remplacez le domaine et le jeton par les vôtres) :

curl -s https://votre-domaine/api/skill/capabilities \
-H "X-Site-Token: sk_votre_jeton"

3. Demandez d'abord « que savez-vous faire », puis appelez les interfaces

Ne devinez pas les noms d'interface dès le départ. Deux interfaces en libre-service sont toujours disponibles, permettant à l'Agent de découvrir ses capacités :

  • GET /api/skill/capabilities —— liste complète des capacités : chemins d'interface, méthodes, types lecture/écriture, description des paramètres, ainsi que le mode d'authentification et le numéro de version du site.
  • GET /api/skill/base/init —— informations de base du site : type de site (B2B / B2C), thème actuel, thèmes disponibles, langues et devises.

Les autres interfaces sont organisées par module ; les plus courantes : /api/skill/product/list (produits), /api/skill/plugin/list (plugins), /api/skill/i18n/list (entrées multilingues), /api/skill/analytics/traffic-get (trafic), /api/skill/b2c-order/list (commandes, site B2C).

4. Matrice de permissions : tout ouvert par défaut, resserrable par module

La page « Permissions d'interface » du back-office propose deux niveaux : tout autoriser (par défaut, comportement identique à l'activation) et restreindre par module (activation individuelle des opérations lecture / écriture / dangereuses par module).

CatégorieSignificationRecommandation
Lecture seuleConsulter produits, contenu, trafic, état des pluginsActivé par défaut
ÉcritureAjouter ou modifier produits, contenu, mise en pageActiver si l'Agent gère l'exploitation
DangereuseSuppression, écrasement du site entier, opérations de publicationActiver uniquement en cas de besoin explicite

Les deux interfaces en lecture seule « liste des interfaces (capabilities) » et « initialisation du site (base/init) » restent toujours autorisées, indépendamment de la table de permissions — sinon l'Agent ne pourrait même pas vérifier « pourquoi la connexion échoue ». La prise en effet est immédiate après enregistrement, sans modification de configuration côté Agent ; les interfaces interdites renvoient 403 avec le motif.

5. Relevé de tests (2026-10-19, un test sur chacun des deux sites clients)

Appels successifs avec le jeton réel de chaque site, résultats ci-dessous (sans retouche, tels quels) :

InterfaceSite B2BSite B2C
GET /api/skill/capabilities200 / 46 063 B200 / 45 842 B
GET /api/skill/base/init200 / 644 B200 / 664 B
GET /api/skill/product/list?limit=2200 / 25 534 B200 / 5 417 B
GET /api/skill/analytics/traffic-get200 / 3 424 B200 / 2 913 B
GET /api/skill/plugin/list200 / 15 673 B200 / 14 681 B
GET /api/skill/i18n/list200 / 5 275 B200 / 5 275 B
Idem, sans jeton401 / 68 B401 / 68 B

Conclusion : la voie est ouverte sur les deux sites, l'authentification fonctionne, l'absence de jeton est refusée (retour « non autorisé : X-Site-Token manquant ou incorrect »). Les différences de taille relèvent du volume de données, non d'une anomalie.

6. Codes d'erreur et traitement

ÉtatSignificationTraitement
401Jeton manquant ou incorrectVérifier que l'en-tête est bien X-Site-Token ; le jeton a-t-il été réinitialisé
403Bloqué par la matrice de permissionsConsulter le reason renvoyé ; ouvrir le module correspondant dans « Permissions d'interface » du back-office
404Chemin inexistantVérifier d'abord le nom d'interface via capabilities, ne pas le reconstituer de mémoire
503Jeton de site non configuré côté serveurOuvrir une fois la page « Connexion IA » du back-office, le système le génère automatiquement

7. Trois règles de sécurité fondamentales

  1. Ne pas mettre le jeton dans l'URL, ni le coller dans une fenêtre de chat ou le committer dans un dépôt de code — il équivaut à une session d'administration.
  2. N'accorder que les permissions nécessaires : lecture + écriture suffisent pour l'exploitation courante, activer temporairement les opérations dangereuses au besoin.
  3. Réinitialiser le jeton lors d'un changement de personne ou d'une passation ; l'ancien jeton est immédiatement invalidé, plus fiable qu'une révocation individuelle.

III. Étapes minimales de connexion à WorkBuddy

  1. Back-office « Connexion IA » → copier l'adresse d'interface et le jeton d'accès (ou copier directement l'ensemble des instructions de connexion).
  2. Dans la configuration du connecteur / des compétences de WorkBuddy, saisir l'adresse du site, authentification via X-Site-Token.
  3. Laisser l'Agent appeler d'abord capabilities pour s'auto-décrire, puis appeler les interfaces concrètes selon la liste.