Back to Details

a1-yandex-kit-orders

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

A1 Yandex KIT — Orders

A1 Yandex KIT — 订单管理

Communication

沟通规范

Before producing any user-facing message, read and apply 
../a1-yandex-kit/references/merchant-communication.md
 completely.
Covers the order-management domain of the Yandex KIT e-commerce API — tags: Заказы, Клиенты, Подарочные карты, Услуги. Orders are created by buyers on the storefront; through the API you list and inspect them, confirm or cancel them, close out their delivery (
POST /v1/orders/{id}/delivery/complete
— for pickup and the store's own delivery when delivery automation is off), write «Честный знак» marking codes onto order items (
POST /v1/orders/{id}/marking-codes
— one code per item, null removes a code), and read the attached additional services (addons), customer records and gift cards. A customer record also carries the marketing-consent pair 
agreement_for_promo
+ 
agreement_at
— read it before adding anyone to a mailing list and mirror it into your CRM. All datetimes are UTC, and list endpoints paginate with 
page
/
per_page
(max 100).
For authentication (
Authorization: Bearer <token>
), the base URL (
https://api.kit.yandex.net
, all paths under 
/v1/
), the 3 rps rate limit and the 
{code, message, trace_id}
error contract, see the 
a1-yandex-kit
skill.
在生成任何面向用户的消息之前，请完整阅读并遵循 
../a1-yandex-kit/references/merchant-communication.md
 中的内容。
本文档涵盖Yandex KIT电商API的订单管理领域——标签：Заказы（订单）、Клиенты（客户）、Подарочные карты（礼品卡）、Услуги（服务）。订单由买家在店铺前台创建；通过API你可以列出并查看订单、确认或取消订单、完成订单配送（
POST /v1/orders/{id}/delivery/complete
——适用于自提和店铺自主配送且配送自动化关闭的场景）、将«Честный знак»（诚信标识）编码写入订单项（
POST /v1/orders/{id}/marking-codes
——每个商品对应一个编码，null表示移除编码），还可以查看附加服务（addons）、客户记录和礼品卡信息。客户记录中还包含营销许可字段对
agreement_for_promo
+ 
agreement_at
——在将客户添加到邮件列表前请读取该字段，并同步到你的CRM系统中。所有日期时间均为UTC时区，列表接口通过
page
/
per_page
进行分页（最大100条）。
关于认证方式（
Authorization: Bearer <token>
）、基础URL（
https://api.kit.yandex.net
，所有路径均在
/v1/
下）、每秒3次的请求速率限制以及
{code, message, trace_id}
错误格式，请参考
a1-yandex-kit
技能文档。

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).
  1. 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 "подтвердить заказ"
    .
  2. Inspect the full contract of one operation — path/query parameters plus the fully dereferenced request/response schemas:
    bash
    node scripts/search_docs.mjs --operation ConfirmOrder
  3. Validate a drafted request body offline before sending anything:
    bash
    node scripts/validate.mjs --operation ConfirmOrder --body '<json>'
# or: node scripts/validate.mjs --operation ConfirmOrder --body-file body.json
    Prints 
    VALID
    (exit 0) or the list of schema violations (exit 1).
  4. Execute the operation:
    • prefer the matching 
      mcp-yandex-kit
      MCP tool from «Related MCP tools» below (e.g. 
      list_orders
      , 
      confirm_order
      );
    • 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
，无需网络连接）。
  1. 搜索所需操作：
    bash
    node scripts/search_docs.mjs "<query>" [--tag "<Тег>"] [--limit N]
    匹配操作ID、路径、标签以及俄文摘要/描述，例如：
    node scripts/search_docs.mjs "подтвердить заказ"
    。
  2. 查看单个操作的完整契约——包括路径/查询参数以及完全解引用的请求/响应 schema：
    bash
    node scripts/search_docs.mjs --operation ConfirmOrder
  3. 离线验证拟发送的请求体：
    bash
    node scripts/validate.mjs --operation ConfirmOrder --body '<json>'
# 或：node scripts/validate.mjs --operation ConfirmOrder --body-file body.json
    验证通过时输出
    VALID
    （退出码0），否则输出schema违规列表（退出码1）。
  4. 执行操作：
    • 优先使用下方“相关MCP工具”中对应的
      mcp-yandex-kit
      工具（例如
      list_orders
      、
      confirm_order
      ）；
    • 对于没有专用工具的操作：使用
      kit_request
      MCP工具——它会在发送前根据相同的schema验证请求体；
    • 或使用普通HTTP请求： 
      curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/...
      （注意每秒3次的请求速率限制）。

Endpoints (23 operations)

接口（共23个操作）

Заказы

Заказы（订单）

MethodPathOperationIdSummary (RU)
GET
/v1/customers/{customer_id}/orders
GetOrdersByCustomerId
Получение списка заказов по ID клиента
GET
/v1/orders
GetOrders
Получение списка заказов
GET
/v1/orders/{id}
GetOrderById
Получение заказа по ID
GET
/v1/orders/{id}/addons
GetOrderAddons
Получение списка услуг заказа
POST
/v1/orders/{id}/confirm
ConfirmOrder
Подтверждение заказа
POST
/v1/orders/{id}/cancel
CancelOrder
Отмена заказа
POST
/v1/orders/{id}/delivery/complete
CompleteOrderDelivery
Завершение доставки заказа
POST
/v1/orders/{id}/marking-codes
SetOrderMarkingCodes
Запись кодов маркировки «Честный знак»
方法路径操作ID摘要（俄文/中文）
GET
/v1/customers/{customer_id}/orders
GetOrdersByCustomerId
Получение списка заказов по ID клиента（根据客户ID获取订单列表）
GET
/v1/orders
GetOrders
Получение списка заказов（获取订单列表）
GET
/v1/orders/{id}
GetOrderById
Получение заказа по ID（根据ID获取订单）
GET
/v1/orders/{id}/addons
GetOrderAddons
Получение списка услуг заказа（获取订单附加服务列表）
POST
/v1/orders/{id}/confirm
ConfirmOrder
Подтверждение заказа（确认订单）
POST
/v1/orders/{id}/cancel
CancelOrder
Отмена заказа（取消订单）
POST
/v1/orders/{id}/delivery/complete
CompleteOrderDelivery
Завершение доставки заказа（完成订单配送）
POST
/v1/orders/{id}/marking-codes
SetOrderMarkingCodes
Запись кодов маркировки «Честный знак»（写入诚信标识编码）

Клиенты

Клиенты（客户）

MethodPathOperationIdSummary (RU)
GET
/v1/customers
GetCustomers
Получение списка клиентов
GET
/v1/customers/{customer_id}
GetCustomerById
Получение клиента по ID
PATCH
/v1/customers/{customer_id}
UpdateCustomer
Обновление клиента
方法路径操作ID摘要（俄文/中文）
GET
/v1/customers
GetCustomers
Получение списка клиентов（获取客户列表）
GET
/v1/customers/{customer_id}
GetCustomerById
Получение клиента по ID（根据ID获取客户）
PATCH
/v1/customers/{customer_id}
UpdateCustomer
Обновление клиента（更新客户信息）

Подарочные карты

Подарочные карты（礼品卡）

MethodPathOperationIdSummary (RU)
GET
/v1/gift_cards
GetGiftCards
Получение списка подарочных карт
GET
/v1/gift_cards/{gift_card_id}
GetGiftCardById
Получение подарочной карты по ID
方法路径操作ID摘要（俄文/中文）
GET
/v1/gift_cards
GetGiftCards
Получение списка подарочных карт（获取礼品卡列表）
GET
/v1/gift_cards/{gift_card_id}
GetGiftCardById
Получение подарочной карты по ID（根据ID获取礼品卡）

Услуги

Услуги（服务）

MethodPathOperationIdSummary (RU)
GET
/v1/addons
GetAddons
Получение списка услуг
POST
/v1/addons
CreateAddon
Создание услуги
GET
/v1/addons/{id}
GetAddonById
Получение услуги по ID
PATCH
/v1/addons/{id}
UpdateAddon
Обновление услуги
DELETE
/v1/addons/{id}
DeleteAddon
Удаление услуги
GET
/v1/addons/{id}/variants
GetAddonVariantIDs
Получение уникальных идентификаторов товаров услуги
GET
/v1/addons/{id}/categories
GetAddonCategoryIDs
Получение идентификаторов категорий услуги
GET
/v1/addons/{id}/collections
GetAddonCollectionIDs
Получение идентификаторов коллекций услуги.
POST
/v1/addons/{id}/objects/add
AddAddonObjects
Добавление объектов в услугу
POST
/v1/addons/{id}/objects/remove
RemoveAddonObjects
Удаление объектов из услуги
方法路径操作ID摘要（俄文/中文）
GET
/v1/addons
GetAddons
Получение списка услуг（获取服务列表）
POST
/v1/addons
CreateAddon
Создание услуги（创建服务）
GET
/v1/addons/{id}
GetAddonById
Получение услуги по ID（根据ID获取服务）
PATCH
/v1/addons/{id}
UpdateAddon
Обновление услуги（更新服务）
DELETE
/v1/addons/{id}
DeleteAddon
Удаление услуги（删除服务）
GET
/v1/addons/{id}/variants
GetAddonVariantIDs
Получение уникальных идентификаторов товаров услуги（获取服务商品唯一ID）
GET
/v1/addons/{id}/categories
GetAddonCategoryIDs
Получение идентификаторов категорий услуги（获取服务分类ID）
GET
/v1/addons/{id}/collections
GetAddonCollectionIDs
Получение идентификаторов коллекций услуги.（获取服务集合ID）
POST
/v1/addons/{id}/objects/add
AddAddonObjects
Добавление объектов в услугу（向服务中添加对象）
POST
/v1/addons/{id}/objects/remove
RemoveAddonObjects
Удаление объектов из услуги（从服务中移除对象）

Related MCP tools

相关MCP工具

Curated 
mcp-yandex-kit
tools for these tags (the server also exposes the meta trio — 
search_operations
, 
get_operation_schema
, 
kit_request
— reaching all 162 operations):
  • list_orders
    — List orders of the store (paginated), newest first.
  • get_order
    — Get a single order by its ID, including line items, delivery chunks, payment and status.
  • confirm_order
    — Confirm an order.
  • cancel_order
    — Cancel an order.
  • complete_order_delivery
    — Mark the delivery of an order as fully completed.
  • set_order_marking_codes
    — Write «Честный знак» (Chestny ZNAK) marking codes onto order items, or remove them.
  • get_order_addons
    — List additional services (addons) attached to an order by the order ID.
  • list_customers
    — List customers of the store (paginated).
  • get_customer
    — Get a single customer by their ID.
  • update_customer
    — Update a customer (plain JSON PATCH).
  • get_customer_orders
    — List order IDs of a customer by their customer ID (paginated).
  • list_gift_cards
    — List gift cards of the store (paginated), with optional status and purchase-date filters.
  • get_gift_card
    — Get a single gift card by its ID, including status, balance and purchase info.
Услуги (addons) beyond 
get_order_addons
have no dedicated tools — manage them through 
search_operations
+ 
kit_request
.
以下是为上述标签精选的
mcp-yandex-kit
工具（服务器还提供三个元工具——
search_operations
、
get_operation_schema
、
kit_request
——可覆盖全部162个操作）：
  • list_orders
    — 列出店铺订单（分页），按最新排序。
  • get_order
    — 根据ID获取单个订单详情，包括订单项、配送段、支付信息和状态。
  • confirm_order
    — 确认订单。
  • cancel_order
    — 取消订单。
  • complete_order_delivery
    — 将订单配送标记为已完成。
  • set_order_marking_codes
    — 将«Честный знак»（诚信标识）编码写入订单项，或移除编码。
  • get_order_addons
    — 根据订单ID获取附加服务（addons）列表。
  • list_customers
    — 列出店铺客户（分页）。
  • get_customer
    — 根据ID获取单个客户详情。
  • update_customer
    — 更新客户信息（纯JSON PATCH方式）。
  • get_customer_orders
    — 根据客户ID列出客户的订单ID（分页）。
  • list_gift_cards
    — 列出店铺礼品卡（分页），支持按状态和购买日期筛选。
  • get_gift_card
    — 根据ID获取单个礼品卡详情，包括状态、余额和购买信息。
除
get_order_addons
外，Услуги（服务）相关操作没有专用工具——需通过
search_operations
+ 
kit_request
进行管理。