A1 Yandex KIT Skills
커뮤니케이션
사용자에게 표시되는 모든 메시지를 생성하기 전에
references/merchant-communication.md를
완전히 읽고 적용하세요.
Yandex KIT (kit.yandex.ru, 베타)는 Yandex의 전자상거래 스토어 빌더입니다. 사실상
러시아의 Shopify와 같습니다. REST API는 판매자의 백엔드와 플랫폼 간에 카탈로그, 재고 및
가격을 동기화하고 주문을 관리하기 위한 서버 간 계층입니다. 공식 문서는 러시아어로 되어 있으며,
전체 OpenAPI 스펙(160개 연산)은 이 스킬에 data/kit_v1.json.gz로 포함되어 있으며
아래 스크립트로 오프라인에서 검색할 수 있습니다.
API 핵심 사항
- 기본 URL:
https://api.kit.yandex.net, 모든 경로는/v1/접두사가 붙습니다. - 인증:
Authorization: Bearer <토큰>(일반 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은 스키마가 nullable로 표시한 경우에만 필드를 지웁니다. 그 중에서는UpdateCategory의parent_id와file_id만 해당됩니다. 다른 곳에서null을 사용하면 검증에 실패합니다(아래validate.mjs가 이를 감지합니다).POST /v1/files(UploadFile) 및POST /v1/videos(UploadVideo)는multipart/form-data입니다. - 벌크 쓰기:
BulkUpdatePrices및BulkUpdateStocks는 요청당 최대 5000개 항목을 받으며 원자적입니다 — 유효하지 않은 항목 하나가 전체 배치를 거부(400)하고 아무것도 적용하지 않습니다. 카탈로그 동기화 시 변형별 업데이트보다 이것들을 선호하세요.
워크플로
이 스킬 디렉토리에서 번들된 스크립트를 실행하세요 — 자체 포함되어 있습니다
(Node.js >= 20, 내장 모듈 + 공급업체 검증기, npm install 필요 없음, 네트워크 필요 없음).
-
검색: 필요한 연산을 찾으세요:
node scripts/search_docs.mjs "<쿼리>" [--tag "<태그>"] [--limit N]연산 ID, 경로, 태그 및 러시아어 요약/설명과 일치합니다. 예:
node scripts/search_docs.mjs "создать товар". -
검사: 하나의 연산에 대한 전체 계약 — 경로/쿼리 파라미터 및 완전히 역참조된 요청/응답 스키마:
node scripts/search_docs.mjs --operation CreateProduct -
검증: 아무것도 보내기 전에 오프라인에서 요청 본문을 검증하세요:
node scripts/validate.mjs --operation CreateProduct --body '<json>' # 또는: node scripts/validate.mjs --operation CreateProduct --body-file body.jsonVALID(종료 코드 0) 또는 스키마 위반 목록 (종료 코드 1)을 출력합니다. -
실행: 연산을 실행하세요:
- 번들된
mcp-yandex-kitMCP 서버를 선호하세요: 전용 도메인 스킬이 있을 때는 큐레이션된 도구, 그렇지 않으면 아래 메타 트리오; - 전용 도구가 없는 연산:
kit_requestMCP 도구 — 전송 전에 본문을 동일한 스키마로 검증합니다; - 또는 일반 HTTP:
curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/...(초당 3회 제한을 유의하세요).
- 번들된
도메인 스킬
작업이 명확히 하나의 도메인에 속할 때는 집중화된 스킬을 선호하세요 — 각각 동일한 스크립트와 데이터, 그리고 해당 태그의 엔드포인트 테이블을 포함합니다:
a1-yandex-kit-catalog— 상품, 변형(SKU, 가격, 재고, 벌크 가격/재고 동기화), 카테고리, 특성(그룹, 색상), 비디오, 컬렉션, 컨텍스트 컬렉션, 배지.a1-yandex-kit-orders— 주문, 고객, 기프트 카드, 추가 서비스(애드온).a1-yandex-kit-promotions— 할인, 프로모션 코드, 프로모션 코드 그룹, 선물.a1-yandex-kit-store— 스토어 프로필, 창고, 사용자, 지역, 파일, 리디렉션, 블로그/뉴스, 알림.a1-yandex-kit-webhooks— 웹훅: 주문 이벤트, HTTPS 콜백, 서명 비밀.
관련 MCP 도구
번들된 mcp-yandex-kit MCP 서버는 70개의 도구를 제공합니다. 큐레이션된 도구는
일상적인 카탈로그/주문/프로모션/스토어/웹훅 워크플로를 다루며(도메인 스킬에 나열됨),
아래 메타 트리오는 모든 160개 연산에 접근할 수 있습니다:
search_operations— 키워드로 전체 160개 Yandex KIT API 연산 카탈로그를 검색합니다.get_operation_schema— operationId로 하나의 KIT API 연산에 대한 전체 메타데이터를 가져옵니다: HTTP 메소드, 경로, 경로/쿼리 파라미터, 요청 콘텐츠 유형, 페이지네이션 정보 및 요청 본문과 응답의 완전히 역참조된 JSON 스키마.kit_request— 전용 도구가 없는 연산을 포함하여 operationId로 160개 Yandex KIT API 연산 중 ANY를 실행하는 이스케이프 해치입니다.