ztemerbekov/a1-yandex-kit-skills

A1 Yandex KIT Skills

Comunicação

Antes de produzir qualquer mensagem voltada ao usuário, leia e aplique references/merchant-communication.md completamente.

Yandex KIT (kit.yandex.ru, beta) é um construtor de lojas de e-commerce da Yandex — efetivamente um "Shopify russo". Sua API REST é uma camada servidor-a-servidor para sincronizar catálogo, estoques e preços e para gerenciar pedidos entre o back-end de um comerciante e a plataforma. A documentação oficial está em russo; a especificação OpenAPI completa (160 operações) está incluída nesta skill em data/kit_v1.json.gz e pode ser pesquisada offline com os scripts abaixo.

Fundamentos da API

• URL Base: https://api.kit.yandex.net, todo caminho é prefixado com /v1/.
• Autenticação: Authorization: Bearer <token> (HTTP Bearer simples, não OAuth). O token é gerado no painel do comerciante: Configurações → API → Gerar token — ele é exibido apenas uma vez, armazene-o com segurança e gere um novo se perdido.
• Limite de taxa: 3 requisições por segundo por loja, sem cabeçalhos de cota. Excedê-lo retorna código LIMIT_EXCEEDED com HTTP 400 (não 429) — limite o lado do cliente e detecte o erro pelo seu code, não pelo status.
• Contrato de erro: todo erro é 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). Informe o trace_id ao contatar o suporte.
• Datas e horas: tudo está em UTC.
• Sem ambiente de teste: apenas produção — prefira chamadas somente leitura enquanto explora e verifique cada operação de escrita duas vezes.
• Paginação: endpoints de lista aceitam parâmetros de consulta page + per_page (máx. 100).
• Tipos de conteúdo: corpos de requisição são application/json, exceto as 5 operações que usam JSON Merge Patch (application/merge-patch+json): UpdateCategory, UpdateCharacteristic, UpdateVariant, UpdateVariantAttachment, UpdateWarehouse — envie apenas os campos a serem alterados. null limpa um campo apenas onde o esquema o marca como anulável — destes, isso é apenas parent_id e file_id de UpdateCategory; em outros casos, null falha na validação (validate.mjs abaixo detectará isso). POST /v1/files (UploadFile) e POST /v1/videos (UploadVideo) são multipart/form-data.
• Escritas em lote: BulkUpdatePrices e BulkUpdateStocks aceitam até 5000 itens por requisição e são atômicas — um único item inválido rejeita todo o lote (400) e não aplica nada. Prefira-as em vez de atualizações por variante para sincronizações de catálogo.

Fluxo de trabalho

Execute os scripts incluídos a partir do diretório desta skill — eles são autocontidos (Node.js >= 20, módulos internos + um validador próprio, sem npm install, sem rede).

1. Pesquise a operação de que precisa:

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

   Corresponde a IDs de operação, caminhos, tags e resumos/descrições em russo, por exemplo: node scripts/search_docs.mjs "создать товар".

2. Inspecione o contrato completo de uma operação — caminho/parâmetros de consulta, mais os esquemas de requisição/resposta totalmente dereferenciados:

   node scripts/search_docs.mjs --operation CreateProduct
   

3. Valide um corpo de requisição rascunhado offline antes de enviar qualquer coisa:

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

   Imprime VALID (código de saída 0) ou a lista de violações de esquema (código de saída 1).

4. Execute a operação:

   • prefira o servidor MCP incluído mcp-yandex-kit: uma ferramenta curada quando existir (veja as skills de domínio), caso contrário, o trio meta abaixo;
   • qualquer operação sem ferramenta dedicada: a ferramenta MCP kit_request — ela valida o corpo contra o mesmo esquema antes de enviar;
   • ou HTTP puro: curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/... (lembre-se do limite de 3 rps).

Skills de domínio

Prefira a skill focada quando a tarefa claramente pertencer a um domínio — cada uma inclui os mesmos scripts e dados, além das tabelas de endpoints de suas tags:

• a1-yandex-kit-catalog — produtos, variantes (SKUs, preços, estoques, sincronização em lote de preço/estoque), categorias, características (grupos, cores), vídeos, coleções, coleções de contexto, selos.
• a1-yandex-kit-orders — pedidos, clientes, cartões-presente, serviços adicionais (complementos).
• a1-yandex-kit-promotions — descontos, códigos promocionais, grupos de códigos promocionais, brindes.
• a1-yandex-kit-store — perfil da loja, almoxarifados, usuários, geolocalização, arquivos, redirecionamentos, blog/notícias, alertas.
• a1-yandex-kit-webhooks — webhooks: eventos de pedido, callbacks HTTPS, segredo de assinatura.

Ferramentas MCP relacionadas

O servidor MCP incluído mcp-yandex-kit expõe 70 ferramentas. Ferramentas curadas cobrem os fluxos de trabalho cotidianos de catálogo/pedidos/promoções/loja/webhooks (elas são listadas nas skills de domínio); o trio meta abaixo alcança todas as 160 operações:

• search_operations — Pesquise todo o catálogo das 160 operações da API do Yandex KIT por palavra-chave.
• get_operation_schema — Obtenha metadados completos para uma operação da API KIT pelo operationId: método HTTP, caminho, parâmetros de caminho/consulta, tipo de conteúdo da requisição, informações de paginação e os esquemas JSON completamente dereferenciados do corpo da requisição e da resposta.
• kit_request — Escape hatch que executa QUALQUER uma das 160 operações da API Yandex KIT pelo operationId, incluindo operações sem uma ferramenta dedicada.