a1-yandex-kit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

A1 Yandex KIT Skills

A1 Yandex KIT技能

Communication

沟通规范

Before producing any user-facing message, read and apply

references/merchant-communication.md

completely.

Yandex KIT (kit.yandex.ru, beta) is Yandex's e-commerce store builder — effectively a Russian Shopify. Its REST API is a server-to-server layer for syncing catalog, stocks and prices and for managing orders between a merchant's backend and the platform. The official docs are in Russian; the full OpenAPI spec (162 operations) is bundled with this skill in

data/kit_v1.json.gz

and searchable offline with the scripts below.

在生成任何面向用户的消息之前，请完整阅读并遵循

references/merchant-communication.md

中的内容。

Yandex KIT（kit.yandex.ru，测试版）是Yandex推出的电商店铺构建工具——相当于俄罗斯版的Shopify。其REST API是一个服务器到服务器的层，用于在商家后端与平台之间同步商品目录、库存和价格，以及管理订单。官方文档为俄语；完整的OpenAPI规范（包含162个操作）已随本技能打包在

data/kit_v1.json.gz

中，可通过下方脚本进行离线搜索。

API essentials

API基础要点

Base URL:
```
https://api.kit.yandex.net
```
, every path is prefixed with
```
/v1/
```
.
Auth:
```
Authorization: Bearer <token>
```
(plain HTTP Bearer, not OAuth). The token is generated in the merchant cabinet: Settings → API → Generate token — it is shown only once, store it securely and generate a new one if lost.
Rate limit: 3 requests per second per store, no quota headers. Exceeding it returns code
```
LIMIT_EXCEEDED
```
with HTTP 400 (not 429) — throttle client-side and detect the error by its
```
code
```
, not by the status.

Error contract: every error is 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). Quote

trace_id

when contacting support.

Datetimes: everything is UTC.
No sandbox: production only — prefer read-only calls while exploring and double-check every write.
Pagination: list endpoints take
```
page
```
+
```
per_page
```
(max 100) query parameters.
Content types: request bodies are
```
application/json
```
, except the 5 operations that use JSON Merge Patch (
```
application/merge-patch+json
```
):
```
UpdateCategory
```
,
```
UpdateCharacteristic
```
,
```
UpdateVariant
```
,
```
UpdateVariantAttachment
```
,
```
UpdateWarehouse
```
— send only the fields to change.
```
null
```
clears a field only where the schema marks it nullable — of these, that is just
```
parent_id
```
and
```
file_id
```
of
```
UpdateCategory
```
; elsewhere
```
null
```
fails validation (
```
validate.mjs
```
below will catch it).
```
POST /v1/files
```
(
```
UploadFile
```
) and
```
POST /v1/videos
```
(
```
UploadVideo
```
) are
```
multipart/form-data
```
.
Bulk writes:
```
BulkUpdatePrices
```
and
```
BulkUpdateStocks
```
take up to 5000 items per request and are atomic — a single invalid item rejects the whole batch (400) and applies nothing. Prefer them over per-variant updates for catalog syncs.

基础URL：
```
https://api.kit.yandex.net
```
，所有路径均以
```
/v1/
```
为前缀。
认证方式：
```
Authorization: Bearer <token>
```
（纯HTTP Bearer认证，非OAuth）。令牌在商家后台生成：设置 → API → 生成令牌——令牌仅显示一次，请安全存储，若丢失需重新生成。
速率限制：每个店铺每秒最多3次请求，无配额响应头。超出限制会返回
```
LIMIT_EXCEEDED
```
错误码，对应HTTP 400状态码（而非429）——需在客户端进行限流，并通过错误
```
code
```
而非状态码检测该错误。
错误约定：所有错误均为JSON格式
```
{"code", "message", "trace_id"}
```
。错误码包括：
```
AUTHENTICATION_ERROR
```
（401）、
```
FORBIDDEN_ERROR
```
（403）、
```
VALIDATION_ERROR
```
（400）、
```
LIMIT_EXCEEDED
```
（400）、
```
UNSUPPORTED_MEDIA_TYPE
```
（415）、
```
NOT_FOUND
```
（404）、
```
CONFLICT
```
（409）、
```
UNKNOWN_ERROR
```
（500）。联系技术支持时请提供
```
trace_id
```
。
日期时间：所有时间均采用UTC时区。
无沙箱环境：仅支持生产环境——探索阶段优先使用只读接口，执行写入操作前务必仔细检查。
分页机制：列表接口接受
```
page
```
和
```
per_page
```
（最大值100）查询参数。
内容类型：请求体默认使用
```
application/json
```
，除了5个使用JSON Merge Patch的操作（
```
application/merge-patch+json
```
）：
```
UpdateCategory
```
、
```
UpdateCharacteristic
```
、
```
UpdateVariant
```
、
```
UpdateVariantAttachment
```
、
```
UpdateWarehouse
```
——仅发送需要修改的字段。仅当架构标记字段可为空时，
```
null
```
才会清除字段值，目前只有
```
UpdateCategory
```
的
```
parent_id
```
和
```
file_id
```
支持此操作；其他场景下
```
null
```
会触发验证失败（下方的
```
validate.mjs
```
脚本可检测此类问题）。
```
POST /v1/files
```
（
```
UploadFile
```
）和
```
POST /v1/videos
```
（
```
UploadVideo
```
）接口使用
```
multipart/form-data
```
类型。
批量写入：
```
BulkUpdatePrices
```
和
```
BulkUpdateStocks
```
接口每次请求最多支持5000条数据，且操作具有原子性——只要有一条数据无效，整个批次都会被拒绝（返回400），且不会应用任何修改。同步商品目录时，优先使用这些批量接口而非逐个变体更新。

Workflow

工作流程

Run the bundled scripts from this skill's directory — they are self-contained (Node.js >= 20, builtins + a vendored validator, no

npm install

, no network).

Search for the operation you need:

bash

node scripts/search_docs.mjs "<query>" [--tag "<Тег>"] [--limit N]

Matches operation ids, paths, tags and the Russian summaries/descriptions, e.g.

node scripts/search_docs.mjs "создать товар"

Inspect the full contract of one operation — path/query parameters plus the fully dereferenced request/response schemas:
bash
```
node scripts/search_docs.mjs --operation CreateProduct
```

Validate a drafted request body offline before sending anything:

bash

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

Prints

VALID

(exit 0) or the list of schema violations (exit 1).

Execute the operation:
- prefer the bundled
```
mcp-yandex-kit
```
  MCP server: a curated tool when one exists (see the domain skills), otherwise the meta trio below;
- any operation without a dedicated tool: the
```
kit_request
```
  MCP tool — it validates the body against the same schema before sending;
- or plain HTTP:
```
curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/...
```
  (mind the 3 rps limit).

从本技能的目录中运行附带的脚本——这些脚本是独立的（要求Node.js >=20，仅使用内置模块和内置验证器，无需

npm install

，无需网络）。

搜索所需操作：

bash

node scripts/search_docs.mjs "<query>" [--tag "<Тег>"] [--limit N]

匹配操作ID、路径、标签以及俄语摘要/描述，例如

node scripts/search_docs.mjs "создать товар"

。

查看单个操作的完整约定——包括路径/查询参数以及完全解引用的请求/响应架构：
bash
```
node scripts/search_docs.mjs --operation CreateProduct
```

离线验证拟发送的请求体：

bash

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

验证通过会输出

VALID

（退出码0），否则输出架构违规列表（退出码1）。

执行操作：
- 优先使用附带的
```
mcp-yandex-kit
```
  MCP服务器：若有专用工具则使用该工具（详见各领域技能），否则使用下方的三个通用工具；
- 对于无专用工具的操作：使用
```
kit_request
```
  MCP工具——它会在发送前根据相同架构验证请求体；
- 或使用普通HTTP请求：
```
curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/...
```
  （注意每秒3次请求的限制）。

Domain skills

领域技能

Prefer the focused skill when the task clearly belongs to one domain — each bundles the same scripts and data, plus the endpoint tables of its tags:

```
a1-yandex-kit-catalog
```
— products, variants (SKUs, prices, stocks, bulk price/stock sync), categories, characteristics (groups, colors), videos, collections, context collections, badges.
```
a1-yandex-kit-orders
```
— orders, customers, gift cards, additional services (addons).
```
a1-yandex-kit-promotions
```
— discounts, promo codes, promocode groups, gifts.
```
a1-yandex-kit-store
```
— store profile, warehouses, users, geo, files, redirects, blog/news, alerts.
```
a1-yandex-kit-webhooks
```
— webhooks: order events, HTTPS callbacks, signing secret.

当任务明确属于某一领域时，优先使用针对性的技能——每个领域技能都包含相同的脚本和数据，以及对应标签的端点表格：

```
a1-yandex-kit-catalog
```
—— 商品、变体（SKU、价格、库存、批量价格/库存同步）、分类、属性（组、颜色）、视频、集合、上下文集合、徽章。
```
a1-yandex-kit-orders
```
—— 订单、客户、礼品卡、附加服务（插件）。
```
a1-yandex-kit-promotions
```
—— 折扣、促销码、促销码组、赠品。
```
a1-yandex-kit-store
```
—— 店铺资料、仓库、用户、地理位置、文件、重定向、博客/新闻、通知。
```
a1-yandex-kit-webhooks
```
—— Webhooks：订单事件、HTTPS回调、签名密钥。

a1-yandex-kit

Original

Translation

A1 Yandex KIT Skills

A1 Yandex KIT技能

Communication

沟通规范

API essentials

API基础要点

Workflow

工作流程

Domain skills

领域技能

Related MCP tools

相关MCP工具