A1 Yandex KIT Skills

Was macht A1 Yandex KIT Skills?

Kommunikation

Bevor Sie eine an den Benutzer gerichtete Nachricht verfassen, lesen und befolgen Sie bitte vollständig die Anleitung in references/merchant-communication.md.

Yandex KIT (kit.yandex.ru, Beta) ist der E-Commerce-Shop-Baukasten von Yandex – vereinfacht ausgedrückt das russische Shopify. Die REST-API ist eine Server-zu-Server-Schnittstelle zum Synchronisieren von Katalog, Beständen und Preisen sowie zur Verwaltung von Bestellungen zwischen dem Backend eines Händlers und der Plattform. Die offizielle Dokumentation ist auf Russisch; die vollständige OpenAPI-Spezifikation (160 Operationen) ist in diesem Skill in data/kit_v1.json.gz gebündelt und mit den folgenden Skripten offline durchsuchbar.

API-Grundlagen

• Basis-URL: https://api.kit.yandex.net, jeder Pfad wird mit /v1/ ergänzt.
• Authentifizierung: Authorization: Bearer <token> (einfacher HTTP-Bearer, kein OAuth). Das Token wird im Händler-Backend generiert: Einstellungen → API → Token generieren – es wird nur einmal angezeigt; speichern Sie es sicher und generieren Sie ein neues, falls es verloren geht.
• Rate-Limit: 3 Anfragen pro Sekunde pro Shop, keine Kontingent-Header. Bei Überschreitung wird der Code LIMIT_EXCEEDED mit HTTP 400 (nicht 429) zurückgegeben – begrenzen Sie die Anfragen clientseitig und erkennen Sie den Fehler am code, nicht am Statuscode.
• Fehlervertrag: Jeder Fehler ist ein JSON-Objekt mit {"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). Geben Sie bei Kontakt mit dem Support die trace_id an.
• Datums-/Zeitangaben: Alles in UTC.
• Keine Sandbox: Nur Produktivumgebung – bevorzugen Sie lesende Aufrufe beim Erkunden und prüfen Sie jeden schreibenden Aufruf doppelt.
• Seitenweise Abfrage: Listen-Endpunkte akzeptieren die Parameter page + per_page (max. 100).
• Inhaltstypen: Request-Bodies sind application/json, mit Ausnahme der 5 Operationen, die JSON Merge Patch (application/merge-patch+json) verwenden: UpdateCategory, UpdateCharacteristic, UpdateVariant, UpdateVariantAttachment, UpdateWarehouse – senden Sie nur die zu ändernden Felder. null löscht ein Feld nur, wenn das Schema es als nullable markiert – davon betroffen sind nur parent_id und file_id von UpdateCategory; ansonsten führt null zu einem Validierungsfehler (validate.mjs weiter unten erkennt das). POST /v1/files (UploadFile) und POST /v1/videos (UploadVideo) verwenden multipart/form-data.
• Massen-Schreiboperationen: BulkUpdatePrices und BulkUpdateStocks akzeptieren bis zu 5000 Elemente pro Anfrage und sind atomar – ein einzelnes ungültiges Element führt zur Ablehnung des gesamten Batches (400) und es wird nichts angewendet. Bevorzugen Sie sie gegenüber Einzelvarianten-Updates für Katalogsynchronisationen.

Arbeitsablauf

Führen Sie die gebündelten Skripte aus dem Verzeichnis dieses Skills aus – sie sind eigenständig (Node.js >= 20, interne Module + ein mitgelieferter Validator, kein npm install, keine Netzwerkverbindung).

1. Suchen Sie nach der benötigten Operation:

   node scripts/search_docs.mjs "<Suchbegriff>" [--tag "<Tag>"] [--limit N]
   

   Durchsucht Operations-IDs, Pfade, Tags und die russischen Zusammenfassungen/Beschreibungen, z. B. node scripts/search_docs.mjs "создать товар".

2. Prüfen Sie den vollständigen Vertrag einer Operation – Pfad-/Query-Parameter sowie die vollständig dereferenzierten Request-/Response-Schemata:

   node scripts/search_docs.mjs --operation CreateProduct
   

3. Validieren Sie einen entworfenen Request-Body offline, bevor Sie etwas senden:

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

   Gibt VALID (Exit-Code 0) oder die Liste der Schema-Verstöße (Exit-Code 1) aus.

4. Ausführen der Operation:

   • bevorzugen Sie den gebündelten MCP-Server mcp-yandex-kit: ein kuratiertes Werkzeug, falls vorhanden (siehe die Domänen-Fähigkeiten), ansonsten das Meta-Trio unten;
   • jede Operation ohne dediziertes Werkzeug: das MCP-Tool kit_request – es validiert den Body vor dem Senden gegen dasselbe Schema;
   • oder einfaches HTTP: curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/... (beachten Sie das Limit von 3 Anfragen pro Sekunde).

Domänen-Fähigkeiten

Bevorzugen Sie die spezialisierte Fähigkeit, wenn die Aufgabe eindeutig zu einer Domäne gehört – jede bündelt dieselben Skripte und Daten sowie die Endpunkt-Tabellen ihrer Tags:

• a1-yandex-kit-catalog – Produkte, Varianten (SKUs, Preise, Bestände, Bulk-Preis-/Bestandssynchronisation), Kategorien, Merkmale (Gruppen, Farben), Videos, Kollektionen, Kontext-Kollektionen, Badges.
• a1-yandex-kit-orders – Bestellungen, Kunden, Geschenkkarten, Zusatzleistungen (Add-ons).
• a1-yandex-kit-promotions – Rabatte, Aktionscodes, Aktionscode-Gruppen, Geschenke.
• a1-yandex-kit-store – Shop-Profil, Lager, Benutzer, Geo, Dateien, Weiterleitungen, Blog/News, Benachrichtigungen.
• a1-yandex-kit-webhooks – Webhooks: Bestellereignisse, HTTPS-Callbacks, Signierungs-Geheimnis.

Verwandte MCP-Werkzeuge

Der gebündelte MCP-Server mcp-yandex-kit stellt 70 Werkzeuge bereit. Kuratierte Werkzeuge decken die alltäglichen Arbeitsabläufe in Katalog/Bestellungen/Aktionen/Shop/Webhooks ab (sie sind in den Domänen-Fähigkeiten aufgeführt); das Meta-Trio unten erreicht alle 160 Operationen:

• search_operations – Durchsuchen Sie den vollständigen Katalog aller 160 Yandex-KIT-API-Operationen nach Schlüsselwörtern.
• get_operation_schema – Rufen Sie die vollständigen Metadaten für eine KIT-API-Operation anhand der operationId ab: HTTP-Methode, Pfad, Pfad-/Query-Parameter, Request-Content-Typ, Paginierungsinformationen und die vollständig dereferenzierten JSON-Schemata des Request-Bodys und der Response.
• kit_request – Sicherheitslücke zur Ausführung JEDER der 160 Yandex-KIT-API-Operationen anhand der operationId, einschließlich Operationen ohne dediziertes Werkzeug.