ztemerbekov/a1-yandex-kit-skills

A1 Yandex KIT Skills

Communication

Avant de produire tout message destiné à l'utilisateur, lisez et appliquez intégralement references/merchant-communication.md.

Yandex KIT (kit.yandex.ru, bêta) est le constructeur de boutiques en ligne de Yandex — effectivement un Shopify russe. Son API REST est une couche serveur-à-serveur pour synchroniser le catalogue, les stocks et les prix, et pour gérer les commandes entre le backend d'un commerçant et la plateforme. La documentation officielle est en russe ; la spécification OpenAPI complète (160 opérations) est fournie avec cette compétence dans data/kit_v1.json.gz et peut être recherchée hors ligne à l'aide des scripts ci-dessous.

Éléments essentiels de l'API

• URL de base : https://api.kit.yandex.net, chaque chemin est préfixé par /v1/.
• Authentification : Authorization: Bearer <token> (HTTP Bearer simple, pas OAuth). Le jeton est généré dans le panneau d'administration du commerçant : Paramètres → API → Générer un jeton — il est affiché une seule fois, stockez-le de manière sécurisée et générez-en un nouveau si perdu.
• Limite de débit : 3 requêtes par seconde par boutique, pas d'en-têtes de quota. Dépasser cette limite renvoie le code LIMIT_EXCEEDED avec une erreur HTTP 400 (pas 429) — limitez du côté client et détectez l'erreur par son code, pas par le statut.
• Contrat d'erreur : chaque erreur est un JSON {"code", "message", "trace_id"}. Codes : AUTHENTICATION_ERROR (401), FORBIDDEN_ERROR (403), VALIDATION_ERROR (400), LIMIT_EXCEEDED (400), UNSUPPORTED_MEDIA_TYPE (415), NOT_FOUND (404), CONFLICT (409), UNKNOWN_ERROR (500). Citez trace_id lorsque vous contactez le support.
• Dates et heures : tout est en UTC.
• Pas de bac à sable : production uniquement — privilégiez les appels en lecture seule pendant l'exploration et vérifiez chaque écriture.
• Pagination : les points de terminaison de liste acceptent les paramètres de requête page + per_page (max 100).
• Types de contenu : les corps de requête sont application/json, à l'exception des 5 opérations qui utilisent JSON Merge Patch (application/merge-patch+json) : UpdateCategory, UpdateCharacteristic, UpdateVariant, UpdateVariantAttachment, UpdateWarehouse — envoyez uniquement les champs à modifier. null efface un champ uniquement là où le schéma le marque comme nullable — parmi celles-ci, cela concerne uniquement parent_id et file_id de UpdateCategory ; ailleurs, null échoue à la validation (validate.mjs ci-dessous le détectera). POST /v1/files (UploadFile) et POST /v1/videos (UploadVideo) sont multipart/form-data.
• Écritures groupées : BulkUpdatePrices et BulkUpdateStocks acceptent jusqu'à 5 000 articles par requête et sont atomiques — un seul article invalide rejette tout le lot (400) et n'applique rien. Préférez-les aux mises à jour par variante pour les synchronisations de catalogue.

Flux de travail

Exécutez les scripts fournis depuis le répertoire de cette compétence — ils sont autonomes (Node.js >= 20, intégrés + un validateur fourni, pas de npm install, pas de réseau).

1. Recherchez l'opération dont vous avez besoin :

   node scripts/search_docs.mjs "<requête>" [--tag "<Étiquette>"] [--limit N]
   

   Correspond aux identifiants d'opération, chemins, étiquettes et résumés/descriptions en russe, par ex. node scripts/search_docs.mjs "создать товар".

2. Inspectez le contrat complet d'une opération — paramètres de chemin/requête ainsi que les schémas de requête/réponse entièrement déréférencés :

   node scripts/search_docs.mjs --operation CreateProduct
   

3. Validez un corps de requête rédigé hors ligne avant d'envoyer quoi que ce soit :

   node scripts/validate.mjs --operation CreateProduct --body '<json>'
   # ou : node scripts/validate.mjs --operation CreateProduct --body-file body.json
   

   Affiche VALID (code de sortie 0) ou la liste des violations de schéma (code de sortie 1).

4. Exécutez l'opération :

   • privilégiez le serveur MCP fourni mcp-yandex-kit : un outil spécialisé lorsqu'il en existe un (voir les compétences domaine), sinon le trio méta ci-dessous ;
   • toute opération sans outil dédié : l'outil MCP kit_request — il valide le corps par rapport au même schéma avant d'envoyer ;
   • ou HTTP simple : curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/... (attention à la limite de 3 req/s).

Compétences domaine

Privilégiez la compétence ciblée lorsque la tâche relève clairement d'un domaine — chacune regroupe les mêmes scripts et données, ainsi que les tableaux de points de terminaison de ses étiquettes :

• a1-yandex-kit-catalog — produits, variantes (SKU, prix, stocks, synchronisation groupée des prix/stocks), catégories, caractéristiques (groupes, couleurs), vidéos, collections, collections contextuelles, badges.
• a1-yandex-kit-orders — commandes, clients, cartes cadeaux, services supplémentaires (extensions).
• a1-yandex-kit-promotions — réductions, codes promo, groupes de codes promo, cadeaux.
• a1-yandex-kit-store — profil de la boutique, entrepôts, utilisateurs, géographie, fichiers, redirections, blog/actualités, alertes.
• a1-yandex-kit-webhooks — webhooks : événements de commande, rappels HTTPS, secret de signature.

Outils MCP associés

Le serveur MCP fourni mcp-yandex-kit expose 70 outils. Les outils spécialisés couvrent les flux de travail quotidiens du catalogue/commandes/promotions/boutique/webhooks (ils sont listés dans les compétences domaine) ; le trio méta ci-dessous atteint les 160 opérations :

• search_operations — Recherche dans le catalogue complet des 160 opérations de l'API Yandex KIT par mot-clé.
• get_operation_schema — Obtient les métadonnées complètes d'une opération de l'API KIT par operationId : méthode HTTP, chemin, paramètres de chemin/requête, type de contenu de la requête, informations de pagination, et les schémas JSON entièrement déréférencés du corps de la requête et de la réponse.
• kit_request — Échappatoire qui exécute N'IMPORTE QUELLE opération parmi les 160 opérations de l'API Yandex KIT par operationId, y compris les opérations sans outil dédié.