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é
| Adresse | Usage | Paramètres | État mesuré |
|---|---|---|---|
| /sitemap.xml | Index des pages publiques du site | Aucun | 200 |
| /robots.txt | Règles d'exploration | Aucun | 200 |
| /llms.txt | Description du site et répertoire des adresses publiques pour les robots d'IA | Aucun | 200 |
| /api/geo/v1/capabilities | Déclare les champs lisibles et la liste des adresses publiques du site | Aucun | 200 |
| /capi/geo/list | Liste le contenu public (produits / catégories / pages / articles) | type, page, pageSize, updated_since | 200 |
| /capi/geo/product/info | Vue de connaissance publique d'un produit | handle | 200 |
| /capi/geo/entity/info | Vue publique des connaissances d'une entité (pages, etc.) | entity_type, entity_id | 200 |
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
- Connectez-vous au back-office et ouvrez la page « Connexion IA » dans la navigation de gauche.
- 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_).
- 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égorie | Signification | Recommandation |
|---|---|---|
| Lecture seule | Consulter produits, contenu, trafic, état des plugins | Activé par défaut |
| Écriture | Ajouter ou modifier produits, contenu, mise en page | Activer si l'Agent gère l'exploitation |
| Dangereuse | Suppression, écrasement du site entier, opérations de publication | Activer 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) :
| Interface | Site B2B | Site B2C |
|---|---|---|
| GET /api/skill/capabilities | 200 / 46 063 B | 200 / 45 842 B |
| GET /api/skill/base/init | 200 / 644 B | 200 / 664 B |
| GET /api/skill/product/list?limit=2 | 200 / 25 534 B | 200 / 5 417 B |
| GET /api/skill/analytics/traffic-get | 200 / 3 424 B | 200 / 2 913 B |
| GET /api/skill/plugin/list | 200 / 15 673 B | 200 / 14 681 B |
| GET /api/skill/i18n/list | 200 / 5 275 B | 200 / 5 275 B |
| Idem, sans jeton | 401 / 68 B | 401 / 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
| État | Signification | Traitement |
|---|---|---|
| 401 | Jeton manquant ou incorrect | Vérifier que l'en-tête est bien X-Site-Token ; le jeton a-t-il été réinitialisé |
| 403 | Bloqué par la matrice de permissions | Consulter le reason renvoyé ; ouvrir le module correspondant dans « Permissions d'interface » du back-office |
| 404 | Chemin inexistant | Vérifier d'abord le nom d'interface via capabilities, ne pas le reconstituer de mémoire |
| 503 | Jeton de site non configuré côté serveur | Ouvrir 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
- 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.
- N'accorder que les permissions nécessaires : lecture + écriture suffisent pour l'exploitation courante, activer temporairement les opérations dangereuses au besoin.
- 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
- Back-office « Connexion IA » → copier l'adresse d'interface et le jeton d'accès (ou copier directement l'ensemble des instructions de connexion).
- Dans la configuration du connecteur / des compétences de WorkBuddy, saisir l'adresse du site, authentification via X-Site-Token.
- Laisser l'Agent appeler d'abord capabilities pour s'auto-décrire, puis appeler les interfaces concrètes selon la liste.