ztemerbekov/a1-yandex-kit-skills

A1 Yandex KIT Skills

Comunicación

Antes de producir cualquier mensaje dirigido al usuario, lee y aplica completamente references/merchant-communication.md.

Yandex KIT (kit.yandex.ru, beta) es el creador de tiendas de comercio electrónico de Yandex — esencialmente un Shopify ruso. Su API REST es una capa de servidor a servidor para sincronizar catálogo, existencias y precios, y para gestionar pedidos entre el backend de un comerciante y la plataforma. La documentación oficial está en ruso; la especificación OpenAPI completa (160 operaciones) viene incluida con este skill en data/kit_v1.json.gz y se puede buscar sin conexión con los scripts a continuación.

Conceptos básicos de la API

• URL base: https://api.kit.yandex.net, cada ruta tiene el prefijo /v1/.
• Autenticación: Authorization: Bearer <token> (Bearer HTTP simple, no OAuth). El token se genera en el panel del comerciante: Ajustes → API → Generar token — se muestra solo una vez, guárdalo de forma segura y genera uno nuevo si lo pierdes.
• Límite de tasa: 3 solicitudes por segundo por tienda, sin cabeceras de cuota. Superarlo devuelve el código LIMIT_EXCEEDED con HTTP 400 (no 429) — limita del lado del cliente y detecta el error por su code, no por el estado.
• Contrato de errores: cada error es JSON {"code", "message", "trace_id"}. Códigos: AUTHENTICATION_ERROR (401), FORBIDDEN_ERROR (403), VALIDATION_ERROR (400), LIMIT_EXCEEDED (400), UNSUPPORTED_MEDIA_TYPE (415), NOT_FOUND (404), CONFLICT (409), UNKNOWN_ERROR (500). Cita trace_id al contactar con soporte.
• Fechas y horas: todo está en UTC.
• Sin sandbox: solo producción — prefiere llamadas de solo lectura mientras exploras y revisa cada escritura dos veces.
• Paginación: los endpoints de lista aceptan parámetros de consulta page + per_page (máx. 100).
• Tipos de contenido: los cuerpos de solicitud son application/json, excepto las 5 operaciones que usan JSON Merge Patch (application/merge-patch+json): UpdateCategory, UpdateCharacteristic, UpdateVariant, UpdateVariantAttachment, UpdateWarehouse — envía solo los campos a cambiar. null limpia un campo solo donde el esquema lo marca como anulable — de estos, eso es solo parent_id y file_id de UpdateCategory; en otros casos, null falla la validación (validate.mjs más abajo lo detectará). POST /v1/files (UploadFile) y POST /v1/videos (UploadVideo) son multipart/form-data.
• Escrituras masivas: BulkUpdatePrices y BulkUpdateStocks aceptan hasta 5000 elementos por solicitud y son atómicos — un solo elemento inválido rechaza todo el lote (400) y no aplica nada. Prefiérelos sobre las actualizaciones por variante para sincronizaciones de catálogo.

Flujo de trabajo

Ejecuta los scripts incluidos desde el directorio de este skill — son autónomos (Node.js >= 20, módulos integrados + un validador propio, sin npm install, sin red).

1. Busca la operación que necesitas:

   node scripts/search_docs.mjs "<consulta>" [--tag "<Etiqueta>"] [--limit N]
   

   Coincide con IDs de operación, rutas, etiquetas y los resúmenes/descripciones en ruso, p. ej., node scripts/search_docs.mjs "создать товар".

2. Inspecciona el contrato completo de una operación — parámetros de ruta/consulta más los esquemas de solicitud/respuesta completamente desreferenciados:

   node scripts/search_docs.mjs --operation CreateProduct
   

3. Valida un cuerpo de solicitud redactado sin conexión antes de enviar algo:

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

   Imprime VALID (código de salida 0) o la lista de violaciones del esquema (código de salida 1).

4. Ejecuta la operación:

   • prefiere el servidor MCP incluido mcp-yandex-kit: una herramienta personalizada cuando exista (consulta los skills de dominio), en caso contrario, el trío meta a continuación;
   • cualquier operación sin una herramienta dedicada: la herramienta MCP kit_request — valida el cuerpo contra el mismo esquema antes de enviar;
   • o HTTP simple: curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/... (ten en cuenta el límite de 3 rps).

Skills de dominio

Prefiere el skill enfocado cuando la tarea pertenece claramente a un dominio — cada uno incluye los mismos scripts y datos, además de las tablas de endpoints de sus etiquetas:

• a1-yandex-kit-catalog — productos, variantes (SKU, precios, existencias, sincronización masiva de precios/existencias), categorías, características (grupos, colores), videos, colecciones, colecciones de contexto, insignias.
• a1-yandex-kit-orders — pedidos, clientes, tarjetas de regalo, servicios adicionales (complementos).
• a1-yandex-kit-promotions — descuentos, códigos promocionales, grupos de códigos promocionales, regalos.
• a1-yandex-kit-store — perfil de la tienda, almacenes, usuarios, geo, archivos, redirecciones, blog/noticias, alertas.
• a1-yandex-kit-webhooks — webhooks: eventos de pedidos, callbacks HTTPS, secreto de firma.

Herramientas MCP relacionadas

El servidor MCP incluido mcp-yandex-kit expone 70 herramientas. Las herramientas personalizadas cubren los flujos de trabajo cotidianos de catálogo/pedidos/promociones/tienda/webhooks (se enumeran en los skills de dominio); el trío meta a continuación alcanza las 160 operaciones:

• search_operations — Busca en el catálogo completo de las 160 operaciones de la API de Yandex KIT por palabra clave.
• get_operation_schema — Obtiene metadatos completos para una operación de la API de KIT por operationId: método HTTP, ruta, parámetros de ruta/consulta, tipo de contenido de solicitud, información de paginación, y los esquemas JSON completamente desreferenciados del cuerpo de la solicitud y la respuesta.
• kit_request — Válvula de escape que ejecuta CUALQUIERA de las 160 operaciones de la API de Yandex KIT por operationId, incluyendo operaciones sin una herramienta dedicada.