Vendling Commerce API — 标准接口文档（UCP 对齐）#

0. 目录#

1. 对齐原则
2. 角色与方向
3. 通用约定：信封、鉴权、头、金额、时间、SKU 命名空间、分页、错误
4. 发现档案 /.well-known/ucp
5. 目录 Catalog：供货方 SKU 清单、机器库存、SKU 注册表
6. 位置 Location：机器即门店
7. 结账 Checkout：向供货方下采购单
8. 订单 Order：采购单状态、机器交易流水
9. 扩展：定价 Pricing
10. 扩展：补货 Replenishment
11. 扩展：审批 Approval
12. 扩展：事件 Events 与订单 Webhook
13. 护栏与安全 - 附录 A 设备与供货方适配器契约 - 附录 B 能力 × 设备类型矩阵

1. 对齐原则#

UCP 明确允许的扩展点，本规范都只用这些：metadata 对象、自定义 fulfillment.methods[].type、开放的 fulfillment.events[].type / adjustments[].type、自由的 messages[].code、actions 映射、 以 extends 声明的扩展能力、能力条目上的 config。

2. 角色与方向#

UCP 只定义两个角色：Platform（消费能力的一方）和 Business（暴露能力的一方）。Vendling 同时扮演两个角色：

                ┌──────────── 上游：Vendling 是 Platform ──────────────┐
                │                                                       │
   供货方 <vendor>-supply   ◄── catalog / checkout / order status ──  Vendling
   （Business：卖货给我们）      §5.1          §7          §8.1            │
                                                                       │
   机器平台 <vendor>-machine ◄── inventory / ledger / prices / recommend ┤
   （Business：运营机器）        §5.2      §8.2     §9       §10.3        │
                                                                       │
                ┌──────────── 下游：Vendling 是 Business ─────────────┤
                │                                                       │
   运营者 / 其他 Agent / 顾客界面  ────────────────────────────────────►│
   （Platform）    §6 位置  §5 目录  §8 订单  §10 补货  §11 审批  §12 事件

上游不必讲 UCP：每个厂商一个适配器（附录 A），把它翻译成本规范的形状。下游调用方只看本规范， 永远不会碰到厂商自己的字段。

3. 通用约定#

3.1 响应信封#

{
  "ucp": {
    "version": "2026-08-25",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [{ "version": "2026-08-25" }],
      "com.xiaopingfeng.vendling.inventory": [{ "version": "2026-09-10" }]
    }
  },
  "products": [ ... ]
}

ucp.capabilities 列出本响应实际启用的能力（含扩展），调用方据此知道哪些扩展字段有效。

3.2 鉴权#

发送一个有意义的 User-Agent。Cloudflare 会对默认的 Python-urllib UA 返回 403（错误 1010），那不是鉴权失败。

3.3 请求头#

3.4 金额 Price / Total#

{ "amount": 550, "currency": "CNY" }
{ "type": "subtotal", "amount": 6600 }

• amount 恒为整数、分。Total.amount 是有符号的，退款等调整为负数。
• totals[] 类型用到 subtotal、fulfillment（配送费）、total。
• 成本只在可靠时给出：适配器若发现上游报的"成本"与售价相同，视为未知（null），下游一律标"估算"，不冒充。

3.5 时间#

对外一律 RFC 3339 带时区偏移，如 "2026-09-09T14:03:00+08:00"。上游厂商的时间格式与时区由适配器换算； 位置的营业时间按 UCP 用本地民用时间 + timezone: "Asia/Shanghai"。

3.6 SKU 标识与命名空间#

一件商品在所有接口里只有一个标识：sku_id。

sku_id = "<namespace>:<vendor_sku>"
namespace = "<vendor>-<role>"      role ∈ supply | machine

• vendor：适配器登记的厂商标识（[a-z][a-z0-9]*）。role：supply 供货方，machine 机器平台。
• vendor_sku：厂商自己的编号，原样保留、不解析（不能含冒号和空白）。
• 整串是唯一身份，按精确字符串比较。不同命名空间的两个 sku_id 永远不相等，哪怕物理上是同一件货；跨命名空间的"同一件货"靠 §5.4 的别名表达。
• 实际存在哪些命名空间由运行时给出：GET /ucp/v1/namespaces（§5.4）或 /.well-known/ucp 里 com.xiaopingfeng.vendling.sku 能力的 config.namespaces。每条带 vendor、role、status（live / planned）、capabilities。

三条硬规则：

1. 适配器只认自己的命名空间。 把 acme-supply:… 传给机器侧接口返回 400 namespace_mismatch。
2. 一张采购单只能有一个供货方命名空间。 一张 PO 只发给一个供货方。
3. 包装不进 ID。 整箱还是单个是下单时的计量单位（§7.1 quantity_unit）。缺省按个。

其余标识符：

3.7 分页#

游标分页：请求 pagination: {cursor, limit}，响应 pagination: {cursor, has_next_page, total_count}。limit 缺省 20。

3.8 错误模型#

协议层错误用 HTTP 状态码 + 信封；业务结果按 UCP 约定用 HTTP 200 + messages[]，实体照常返回， 调用方必须先看 messages 再用数据。

{
  "ucp": { "version": "2026-08-25", "status": "error" },
  "messages": [
    { "type": "error", "code": "kill_switch_engaged", "severity": "requires_buyer_review", "path": "$",
      "content": "kill switch is engaged — real writes are frozen" }
  ],
  "continue_url": "https://vendling.xiaopingfeng.com/"
}

警告（type: "warning"，不阻塞）：price_estimated（单价由箱价换算）、location_unverified（机器号在流水里从未出现）、 history_truncated、hours_unknown、same_namespace、sync_problem。程序只认 code。

4. 发现档案 /.well-known/ucp#

[有] 公开、无需 token。endpoint 指向标准基址 https://vendling.xiaopingfeng.com/ucp/v1。 节选（完整档案以线上为准）：

{
  "ucp": {
    "version": "2026-08-25",
    "services": {
      "dev.ucp.shopping": [{ "version": "2026-08-25", "transport": "rest", "endpoint": "https://vendling.xiaopingfeng.com/ucp/v1", "spec": "…", "schema": "…" }]
    },
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [{ "version": "2026-08-25", "spec": "…", "schema": "…" }],
      "dev.ucp.shopping.checkout":       [{ "version": "2026-08-25", "spec": "…", "schema": "…" }],
      "dev.ucp.shopping.fulfillment":    [{ "version": "2026-08-25", "extends": "dev.ucp.shopping.checkout" }],
      "dev.ucp.shopping.order":          [{ "version": "2026-08-25" }],
      "dev.ucp.common.location.search":  [{ "version": "2026-08-25" }],
      "com.xiaopingfeng.vendling.sku": [{
        "version": "2026-09-10",
        "extends": ["dev.ucp.shopping.catalog.search", "dev.ucp.shopping.catalog.lookup", "dev.ucp.shopping.checkout", "dev.ucp.shopping.order"],
        "config": {
          "namespaces": [
            { "namespace": "acme-supply",  "vendor": "acme", "role": "supply",  "status": "live", "capabilities": ["dev.ucp.shopping.catalog.search", "dev.ucp.shopping.checkout", "dev.ucp.shopping.order"] },
            { "namespace": "acme-machine", "vendor": "acme", "role": "machine", "status": "live", "capabilities": ["com.xiaopingfeng.vendling.inventory", "com.xiaopingfeng.vendling.pricing", "com.xiaopingfeng.vendling.replenishment"] }
          ],
          "defaults": { "machine": "acme-machine", "supply": "acme-supply" }
        }
      }],
      "com.xiaopingfeng.vendling.inventory":     [{ "version": "2026-09-10", "extends": ["dev.ucp.shopping.catalog.search", "dev.ucp.shopping.catalog.lookup"] }],
      "com.xiaopingfeng.vendling.location":      [{ "version": "2026-09-10", "extends": ["dev.ucp.common.location.search", "dev.ucp.common.location.lookup"] }],
      "com.xiaopingfeng.vendling.approval":      [{ "version": "2026-09-10", "extends": "dev.ucp.shopping.checkout" }],
      "com.xiaopingfeng.vendling.order":         [{ "version": "2026-09-10", "extends": "dev.ucp.shopping.order" }],
      "com.xiaopingfeng.vendling.pricing":       [{ "version": "2026-09-10" }],
      "com.xiaopingfeng.vendling.replenishment": [{ "version": "2026-09-10" }],
      "com.xiaopingfeng.vendling.events":        [{ "version": "2026-09-10" }]
    },
    "payment_handlers": {
      "com.xiaopingfeng.vendling.on_account": [{ "id": "supplier_account", "version": "2026-09-10" }]
    }
  },
  "keys": []
}

payment_handlers 只有一个：账户挂账。采购按供货方账户记账，下单不经过支付凭证，所以结账的 payment.instruments[] 只有 type: "on_account"，没有 credential。keys 为空：现在不做 RFC 9421 签名。

5. 目录 Catalog#

能力：dev.ucp.shopping.catalog.search、dev.ucp.shopping.catalog.lookup · 扩展：com.xiaopingfeng.vendling.inventory（机器库存视图）、com.xiaopingfeng.vendling.sku（销售单位、别名、SKU 注册表）

同一套端点，filters.namespace 的角色决定查哪种源：

5.1 供货方 SKU 清单（<vendor>-supply）#

POST /catalog/search
{ "query": "乌龙", "filters": { "namespace": "acme-supply", "categories": ["饮料"] }, "pagination": { "limit": 20 } }

一个供货方商品 = 一个 Product + 一个 Variant。整箱 / 单个不是两个变体，是同一个变体的两种销售单位 （sale_units[]），下单时用 quantity_unit 选。缺省单位是 EA（个）：按个下单是基础情况，按箱是可选项。

{
  "ucp": { "version": "2026-08-25", "status": "success" },
  "products": [
    {
      "id": "acme-supply:10023",
      "title": "乌龙茶 500ml",
      "description": { "plain": "500ml*15瓶/箱" },
      "categories": [{ "value": "饮料", "taxonomy": "merchant" }],
      "price_range": { "min": { "amount": 380, "currency": "CNY" }, "max": { "amount": 380, "currency": "CNY" } },
      "variants": [
        {
          "id": "acme-supply:10023",
          "title": "乌龙茶 500ml",
          "price": { "amount": 380, "currency": "CNY" },
          "quantity_unit": { "unit": "EA", "display_text": "个", "increment": 1 },
          "sale_units": [
            { "unit": "EA", "display_text": "个", "increment": 1, "price": { "amount": 380, "currency": "CNY" }, "price_derived": true },
            { "unit": "BX", "display_text": "箱", "contains": 15, "increment": 1, "price": { "amount": 5700, "currency": "CNY" } }
          ],
          "unit_price": { "amount": 380, "currency": "CNY", "measure": { "value": 15, "unit": "EA" }, "reference": { "value": 1, "unit": "EA" } },
          "availability": { "available": true, "status": "in_stock" },
          "aliases": [],
          "metadata": { "vendor_sku": "10023", "spec": "500ml*15瓶/箱", "supplier_stock": 120 }
        }
      ],
      "metadata": { "sites": [{ "id": "site:2021", "address": "…" }] }
    }
  ],
  "pagination": { "has_next_page": false, "total_count": 1 }
}

sale_units[]（扩展）：

variants[].price 恒为 EA 单位的价格，quantity_unit 恒为 EA：不认识 sale_units 的 UCP 标准客户端也能正确按个下单。 metadata.sites[] 是供货方的提货点（附录 A SupplySite），自提时用作目的地 ID。

5.2 机器库存（<vendor>-machine）— 扩展 com.xiaopingfeng.vendling.inventory#

POST /catalog/search
{ "filters": { "namespace": "acme-machine", "location": "12345678" } }

{
  "products": [
    {
      "id": "acme-machine:8837",
      "title": "红牛 250ml",
      "price_range": { "min": { "amount": 600, "currency": "CNY" }, "max": { "amount": 600, "currency": "CNY" } },
      "variants": [
        {
          "id": "acme-machine:8837",
          "sku": "6920202888883",
          "barcodes": [{ "type": "EAN", "value": "6920202888883" }],
          "title": "红牛 250ml",
          "price": { "amount": 600, "currency": "CNY" },
          "availability": { "available": true, "status": "in_stock" },
          "inventory": { "location": "12345678", "slot_id": "12345678-8837", "stock": 7, "capacity": null, "locked": false },
          "aliases": [{ "sku_id": "acme-supply:10088", "source": "manual", "confirmed_at": "2026-09-01T10:00:00+08:00" }]
        }
      ]
    }
  ]
}

已知陷阱：有的机器平台对不存在的机器号也返回成功。适配层用账户级交易流水做交叉检查：一个在同步窗口内 没有任何流水的机器号会在 messages[] 里得到 type: "warning"、code: "location_unverified"。

5.3 Lookup#

POST /catalog/lookup
{ "ids": ["acme-supply:10023", "acme-machine:8837"], "filters": { "location": "12345678" } }

命名空间就在 ID 里，一次请求可以跨命名空间，按前缀分发（machine 角色的 ID 需要 filters.location）。 ID 去重；每个变体带 inputs[]（exact / featured）；超过 50 个 ID 返回 400 request_too_large。

5.4 命名空间与 SKU 注册表 — 扩展 com.xiaopingfeng.vendling.sku#

GET /namespaces

{
  "namespaces": [
    { "namespace": "acme-supply",  "vendor": "acme", "role": "supply",  "status": "live",    "capabilities": ["…"] },
    { "namespace": "acme-machine", "vendor": "acme", "role": "machine", "status": "live",    "capabilities": ["…"] },
    { "namespace": "beta-supply",  "vendor": "beta", "role": "supply",  "status": "planned", "capabilities": [] }
  ],
  "defaults": { "machine": "acme-machine", "supply": "acme-supply" }
}

补货闭环要从"机器里 acme-machine:8837 快空了"走到"向 acme-supply:10088 采购"，这一步跨命名空间，靠别名：

{ "resolved": [{ "from": "acme-machine:8837", "to": "acme-supply:10088" }], "unresolved": ["acme-machine:9120"] }

别名规则：source ∈ barcode（两边都有 EAN 时自动建立）、manual（运营者确认）、suggested（按名称相似度提出）。 只有 barcode 和 manual 参与下单。别名是对称的。unresolved 不是错误，但带着未解析的行去 §10.2 下单会得到 unresolved_sku。

6. 位置 Location#

能力：dev.ucp.common.location.search、dev.ucp.common.location.lookup · 扩展：com.xiaopingfeng.vendling.location

UCP 的 Location 是"地图上找得到的实体"。一台售货机正是：有地址、有营业时段、可以按"这里现在有没有某件商品"筛选。

{
  "id": "12345678",
  "name": "某写字楼 11F",
  "address": { "street_address": "…", "extended_address": "11F 电梯厅", "address_locality": "北京市", "address_country": "CN" },
  "timezone": "Asia/Shanghai",
  "amenities": { "com.xiaopingfeng.vendling.qr_chat": { "description": "扫码可与机器对话、点单、报修" } },
  "online": true,
  "venue_name": "某写字楼11层",
  "venue_type": "office",
  "placement": "indoor",
  "profile_complete": true,
  "missing": []
}

• hours[] 未记录时省略：UCP 规定"缺 = 未知"而非"关门"；带 filters.hours 的搜索会附 hours_unknown 警告。
• filters.items[] 用 machine 角色的 sku_id，只返回该商品 stock > 0 的机器。按 UCP 语义这是临时性信号，不是保留。
• PUT /locations/{id} 注册后每小时自动同步；同步是整体替换机器 / 商品 / 货道 / 销售，但保留运营者的货道锁。sales_window_days 不得小于补货策略的观察期（21 天）。
• DELETE 清掉档案、周边信息、遥测；保留事件与对话历史。

7. 结账 Checkout#

能力：dev.ucp.shopping.checkout + dev.ucp.shopping.fulfillment · 扩展：com.xiaopingfeng.vendling.approval、com.xiaopingfeng.vendling.sku

这是"下单进货"：向一个供货方下一张真实的、花真钱的采购单。UCP 的结账会话模型把它拆成 "建单 → 补齐信息 → 审批 → 提交"几步，每一步都有明确状态，钱只在最后一步动。

7.1 建单#

POST /checkout-sessions
Idempotency-Key: po_20260909_001
{
  "id": "po_20260909_001",
  "line_items": [
    { "item": { "id": "acme-supply:10023" }, "quantity": 2, "quantity_unit": { "unit": "BX" } },
    { "item": { "id": "acme-supply:10088" }, "quantity": 6 }
  ],
  "fulfillment": {
    "methods": [{ "type": "shipping", "line_item_ids": ["*"],
      "destinations": [{ "type": "shipping_address", "street_address": "…", "address_locality": "北京市", "address_country": "CN", "first_name": "张三", "phone_number": "13800000000" }] }]
  }
}

• id 可选。给了就用作 PO 号（兼作供货方的订单参考号），没给由服务端生成。
• line_items[].item.id 必须来自 supply 角色的命名空间。machine 角色的 ID 不能直接下单，先经 §5.4 resolve。
• 一张单一个命名空间：所有行的前缀必须相同，否则 400 namespace_mismatch。会话的 vendor 由第一行决定，建单后不可变。
• 按个下单是缺省：quantity_unit 省略即 { "unit": "EA" }。要按箱写 { "unit": "BX" }，quantity 是箱数。unit 必须在该变体的 sale_units[] 里，否则 400 invalid。
• 履约二选一：
• shipping：目的地必须有 street_address + first_name（联系人）+ phone_number，缺一建单时返回 missing。
• pickup：目的地由服务端从供货方的提货点枚举（site:<id>），平台用 selected_destination_id 选点、groups[].selected_option_id 选自提时段（服务端生成未来 7 天的时段选项）。

7.2 会话实体#

{
  "ucp": { "version": "2026-08-25", "status": "success",
           "payment_handlers": { "com.xiaopingfeng.vendling.on_account": [{ "id": "supplier_account", "version": "2026-09-10" }] } },
  "id": "po_20260909_001",
  "status": "requires_escalation",
  "currency": "CNY",
  "vendor": "acme-supply",
  "line_items": [
    { "id": "li_1", "item": { "id": "acme-supply:10023", "title": "乌龙茶 500ml", "price": 5700, "quantity_unit": { "unit": "BX", "display_text": "箱", "contains": 15 } },
      "quantity": 2, "totals": [{ "type": "subtotal", "amount": 11400 }, { "type": "total", "amount": 11400 }] },
    { "id": "li_2", "item": { "id": "acme-supply:10088", "title": "红牛 250ml", "price": 480, "quantity_unit": { "unit": "EA", "display_text": "个" } },
      "quantity": 6, "totals": [{ "type": "subtotal", "amount": 2880 }, { "type": "total", "amount": 2880 }] }
  ],
  "fulfillment": { "methods": [{ "id": "fm_shipping", "type": "shipping", "line_item_ids": ["li_1", "li_2"],
    "destinations": [{ "type": "shipping_address", "id": "dest_1", "street_address": "…", "first_name": "张三", "phone_number": "138…" }],
    "selected_destination_id": "dest_1",
    "groups": [{ "id": "grp_1", "line_item_ids": ["li_1", "li_2"], "options": [{ "id": "opt_std", "title": "供货方配送", "totals": [{ "type": "total", "amount": 0 }] }], "selected_option_id": "opt_std" }] }] },
  "totals": [{ "type": "subtotal", "amount": 14280 }, { "type": "fulfillment", "amount": 0 }, { "type": "total", "amount": 14280 }],
  "payment": { "instruments": [{ "id": "instr_account", "handler_id": "supplier_account", "type": "on_account", "selected": true, "display": { "account": "on file" } }] },
  "messages": [
    { "type": "warning", "code": "price_estimated", "path": "$.line_items[1]", "content": "单价由箱价换算，实际以供货方对账为准" },
    { "type": "error", "code": "approval_required", "severity": "requires_buyer_review", "path": "$", "content": "estimated cost 142.80 exceeds run budget 100.00 — needs owner approval" }
  ],
  "actions": { "com.xiaopingfeng.vendling.approval": [{ "id": "dec-1757400000000-3" }] },
  "links": [{ "type": "documentation", "url": "https://vendling.dev/api/" }],
  "continue_url": "https://vendling.xiaopingfeng.com/tasks",
  "expires_at": "2026-09-10T14:03:00+08:00"
}

• item.price 是所选单位一件的价格（箱行是箱价，个行是单价），行 totals = price × quantity。
• 服务端回显 item.quantity_unit（UCP 要求非 each 的行必须带），并补上 display_text / contains。
• 按个下单的行会附 price_estimated 警告（供货方只公布箱价时，单价是换算的）。

7.3 状态机#

紧急停机（rules.killSwitchEngaged）不是一个状态：任何时候 complete 都会被拒（409 kill_switch_engaged），会话本身不动。 读不到规则时 503 guard_unverifiable，拒绝而非放行。

7.4 提交#

POST /checkout-sessions/po_20260909_001/complete
{ "payment": { "instruments": [{ "id": "instr_account", "handler_id": "supplier_account", "type": "on_account" }] }, "confirm": true }

• confirm 是扩展字段，必须是 JSON 布尔 true。字符串 "true"、数字 1 一律 400 confirmation_required。
• 成功：status: "completed"，并带 order: { "id": "po_…", "label": "<供货方订单号>", "permalink_url": "…/orders/po_…" }。
• 供货方拒单：502 + supplier_rejected，status 回到 ready_for_complete，content 带上游原文。重复提交已完成的会话返回同一个 order，不会再下一单。
• 每次提交无论成败都写一条事件到 §12 的事件流。花真钱的调用不能是黑箱。

7.5 会话 → 适配器#

服务端把会话翻译成附录 A 的 createOrder(ref, lines, fulfillment)：ref = 会话 id；每行 {vendor_sku, quantity, unit: "each" | "pack"} （BX → pack）；fulfillment 是 {method:"shipping", contactName, contactPhone, address} 或 {method:"pickup", pickupAt, siteId?}。 厂商自己的字段名不出现在本规范里。

8. 订单 Order#

能力：dev.ucp.shopping.order · 扩展：com.xiaopingfeng.vendling.order（列表查询、位置 / 交易状态字段）

两类订单，同一个实体形状，用 kind 区分：

8.1 采购单（kind: purchase）#

{
  "id": "po_20260909_001",
  "label": "SUP-2026090912345",
  "kind": "purchase",
  "checkout_id": "po_20260909_001",
  "permalink_url": "https://vendling.xiaopingfeng.com/ucp/v1/orders/po_20260909_001",
  "currency": "CNY",
  "line_items": [
    { "id": "li_1", "item": { "id": "acme-supply:10023", "title": "…", "price": 5700, "quantity_unit": { "unit": "BX", "contains": 15 } },
      "quantity": { "original": 2, "total": 2, "fulfilled": 0 },
      "totals": [{ "type": "subtotal", "amount": 11400 }, { "type": "total", "amount": 11400 }], "status": "processing" }
  ],
  "fulfillment": {
    "expectations": [{ "id": "exp_1", "line_items": [{ "id": "li_1", "quantity": 2 }], "method_type": "shipping", "destination": { "street_address": "…", "address_country": "CN" }, "description": "待发货" }],
    "events": [{ "id": "fe_placed", "occurred_at": "2026-09-09T14:05:00+08:00", "type": "processing", "line_items": [{ "id": "li_1", "quantity": 2 }], "description": "已接单" }]
  },
  "adjustments": [],
  "totals": [{ "type": "subtotal", "amount": 14280 }, { "type": "fulfillment", "amount": 0 }, { "type": "total", "amount": 14280 }],
  "supplier_status": { "code": 2, "description": "待发货", "mapped": "ordered" },
  "logistics": []
}

适配器把供货方的状态归一为三态，UCP 视图由此推导：

supplier_status（原始码 + 描述）和 logistics[]（原样透传）是扩展字段，供排障用。

8.2 机器交易（kind: sale）#

GET /orders?kind=sale&location=12345678&from=2026-09-09T00:00:00%2B08:00&to=2026-09-09T23:59:59%2B08:00&limit=100

{
  "orders": [
    {
      "id": "2026090913001234",
      "kind": "sale",
      "checkout_id": "2026090913001234",
      "permalink_url": "…/orders/2026090913001234",
      "currency": "CNY",
      "line_items": [
        { "id": "2026090913001234-8837", "item": { "id": "acme-machine:8837", "title": "红牛 250ml", "price": 600 },
          "quantity": { "original": 1, "total": 1, "fulfilled": 1 },
          "totals": [{ "type": "subtotal", "amount": 600 }, { "type": "total", "amount": 600 }], "status": "fulfilled" }
      ],
      "fulfillment": {
        "expectations": [{ "id": "exp_1", "line_items": [{ "id": "2026090913001234-8837", "quantity": 1 }], "method_type": "vending_dispense",
          "destination": { "extended_address": "某写字楼11层", "address_country": "CN" }, "description": "机器即时出货" }],
        "events": [{ "id": "fe_1", "occurred_at": "2026-09-09T13:00:12+08:00", "type": "dispensed", "line_items": [{ "id": "2026090913001234-8837", "quantity": 1 }] }]
      },
      "adjustments": [],
      "totals": [{ "type": "subtotal", "amount": 600 }, { "type": "total", "amount": 600 }],
      "location": "12345678",
      "location_name": "某写字楼11层",
      "trade_status": "SETTLED"
    }
  ],
  "pagination": { "cursor": "eyJwYWdlIjoyfQ", "has_next_page": true }
}

适配器把每条流水行归一为五种状态，UCP 视图由此推导：

• 只有 paid 行进入销售统计。列表缺省只取已结算交易（trade_status=settled），传 trade_status=all 取全部。
• 流水是账户级的：location 参数是服务端在全量结果上做的筛选，多机器线路上要跨机器完整翻页（上限 20 页，超过带 history_truncated 警告）。
• trade_status / trade_status_label 是机器平台的原始状态，扩展字段，供排障用。

9. 扩展：定价 Pricing#

能力：com.xiaopingfeng.vendling.pricing

改的是真实机器上顾客看到的价格。UCP 没有"商家改自己售价"的能力，所以这是纯扩展，但复用 UCP 的 Price 类型、messages[] 错误模型和 requires_buyer_review 审批语义。

PUT /locations/12345678/prices
{ "prices": [{ "item": { "id": "acme-machine:8837" }, "price": { "amount": 650, "currency": "CNY" } }], "confirm": true }

{ "location": "12345678", "updated": [{ "item": { "id": "acme-machine:8837" }, "price": { "amount": 650, "currency": "CNY" } }] }

1. item.id 必须来自一个 machine 角色的命名空间，且一次请求只能一个命名空间（400 namespace_mismatch）。
2. price.amount 正整数（分），currency 必须是 CNY。
3. confirm 必须是布尔 true（同 §7.4）。
4. 紧急停机时 409 kill_switch_engaged。
5. 价格上限护栏：以机器上此刻的现价为基准，|new − current| > rules.priceCapPerItem 时不执行，返回 200 approval_required 并生成待审批决策（kind: price_change）。批准即执行（§11）；或批准后重发同一请求也会执行。
6. 无论成败写事件。

10. 扩展：补货 Replenishment#

能力：com.xiaopingfeng.vendling.replenishment

10.1 计划#

{
  "strategy_version": "v2-weekshape",
  "params": { "window_days": 21, "cover_days": 7, "safety_days": 2, "min_order_qty": 3, "max_order_qty": 40 },
  "lead_time": { "days": 1.6, "source": "measured", "samples": 7 },
  "plans": [
    { "slot_id": "12345678-8837", "location": "12345678", "item": { "id": "acme-machine:8837", "title": "红牛 250ml" }, "stock": 7,
      "demand": { "daily_rate": 0.52, "naive_daily_rate": 0.48, "available_days": 19, "empty_days": 2, "closed_days": 0, "measured": true },
      "days_of_cover": 13.4, "stockout_at": "2026-09-22T00:00:00+08:00", "recommendation": { "action": "hold" } }
  ]
}

lead_time.source 是 measured（从历史行程实测）或 stated（样本不够，用参数），必须原样透出。demand.measured = false 表示需求率是从缺货期推断的。

10.2 行程（Run）#

行程的形状刻意贴近 UCP Order：行项目、按机器分组的履约期望、追加式的履约事件、金额汇总。

• 行项目是机内 SKU（machine 角色）；每行带 source（经 §5.4 解析到的可采购 sku_id + 计量单位，缺省按个）。
• 下单 place：紧急停机 409；已下单 409 already_placed；待审批 409 approval_required。当前实现把行项目交给模拟供货方（响应带 supplier: "simulated"），未解析的行只是 unresolved_sku 警告；接真实供货方后，place 按 source 创建 §7 的结账会话（跨供货方时拆成多张），未解析的行升级为错误。
• 收货 receive：quantity 非负整数；有容量时封顶；已收货 409 already_delivered。
• 已下单未收货的行程覆盖的货道，在下一次计划里跳过，避免为同一批货付两次钱。
• cost_is_estimated = true 表示有行项目没有真实成本（用零售价 × 0.55 估的）；这个数字决定要不要审批，所以必须说明它是估的。

10.3 向机器平台的补货推荐#

• item.id 必须是 machine 角色；reference 是机器平台要求的批次号；reason 超过 100 字截断。
• 不花钱、没有 confirm，但受紧急停机约束：它会推动别人去往机器里装货。

11. 扩展：审批 Approval#

能力：com.xiaopingfeng.vendling.approval（extends dev.ucp.shopping.checkout）

{ "id": "dec-1757404800000-1", "kind": "restock_plan", "at": "2026-09-09T04:00:00+08:00",
  "summary": "purchase order po_big: 1 line(s), ¥285.00 at acme-supply", "reasoning": "…",
  "subject": { "type": "checkout", "id": "po_big" }, "status": "pending", "approved": null }

• kind ∈ swap | price_change | fault_flag | restock_plan | note。subject.type ∈ replenishment_run | checkout | price_change | slot。
• 批准一个 checkout 让会话变成 ready_for_complete（提交仍是独立的显式调用）；批准一个 price_change 立即执行改价。
• 带 resolver 的请求必须来自已注册的管理员，否则 403；已处理过的 409。每次处理写事件。

12. 扩展：事件 Events 与订单 Webhook#

能力：com.xiaopingfeng.vendling.events

{ "id": "evt-1757404812000-3", "occurred_at": "2026-09-09T13:00:12+08:00", "kind": "order",
  "summary": "order event: 2026090913001234 (交易成功) at 某写字楼11层 — 1 item(s), ¥6", "reasoning": "machine platform ledger poll", "location": "12345678" }

kind 是开放字符串。occurred_at 是事情发生的时间，不是入库时间。机器平台没有 webhook 时，订单事件由本系统 每 5 分钟轮询流水、去重后追加；要对接 UCP 平台的 Webhook，只需在同一处把 §8.2 的 Order 实体 POST 到对方 URL（头带 Webhook-Id、Webhook-Timestamp）。

13. 护栏与安全#

• 护栏失败关闭：读不到规则就拒绝（503 guard_unverifiable）。
• 模拟数据与真实数据不混：模拟购买默认关闭；平板模拟器的遥测标 simulated = 1。
• 顾客侧（扫码聊天界面）不在本规范内：它跑在另一个没有任何上游凭证的进程里，只能通过固定白名单的桥接读库存、写意图事件。
• 敏感字段：成本、利润只对运营者可见；目录响应不含成本，采购单的 price 是采购价。

附录 A. 设备与供货方适配器契约#

Vendling 不直接依赖任何厂商接口。每个上游通过一个适配器接入，实现下面两个角色之一或两者； 系统其余部分只见到这里的形状。Vendling 自带一个参考实现（一个机器平台 + 一个供货方），其厂商细节不在公开文档中。

A.1 通用约定#

• 金额一律整数分；时间给 epoch ms（解析不了给 null，由调用方决定丢弃还是近似）。
• 上游出错返回而不是抛出：{ ok: false, reason, unauthorized?, raw? }。鉴权失败必须可辨认（unauthorized: true），不能看起来像空结果。
• 幂等：createOrder(ref, …) 的 ref 是调用方给的采购单号，重复调用不得产生第二张单。
• 适配器只认自己的命名空间；上游的分页、时区、签名全部在适配器内部消化。

A.2 角色 supply（命名空间 <vendor>-supply）#

SupplyProduct { vendorSku, title, spec?, category?, imageUrl?, packSize, packPriceFen, eachPriceFen, eachPriceDerived, stock }
SupplySite    { id, name?, address? }

packSize = 1 表示只按个卖（目录里不会出现 BX）。只拿得到箱价时 eachPriceFen = round(packPriceFen / packSize) 且 eachPriceDerived = true。

A.3 角色 machine（命名空间 <vendor>-machine）#

MachineItem  { vendorSku, title, barcode?, priceFen, stock, imageUrl? }
LedgerRecord { orderNo, status, statusLabel?, locationId, locationName?, totalFen, createdAt: ms|null, createdAtRaw, lines: LedgerLine[] }
LedgerLine   { vendorSku, priceFen, costFen: number|null, status: "paid"|"unpaid"|"refunded"|"refund_failed"|"cancelled" }

costFen 只在上游给出一个不等于售价的成本时才有值；等于售价的"成本"没有信息量，必须置 null。 流水是账户级的：适配器不做位置过滤，调用方按 locationId 分拣。

A.4 注册与发现#

适配器登记为 { namespace, vendor, role, status: "live" | "planned", capabilities[] }。登记后 GET /ucp/v1/namespaces、 /.well-known/ucp 的 com.xiaopingfeng.vendling.sku.config.namespaces 自动带上；planned 的命名空间可以出现在 ID 里、 参与别名，但任何调用返回 namespace_unsupported。

A.5 我的设备还没有适配器？#

按 A.2 / A.3 实现对应角色即可，其余接口（目录、结账、订单、位置、改价、补货、审批、事件）不需要改动。 一台没有云平台的本地控制售货机，通常只需实现 machine 角色的 inventory 与 ledger（由本地网关维护）， updatePrices 与 restockRecommend 可以返回 { ok: false, reason: "unsupported" }，对应能力就不会出现在它的 capabilities[] 里。

附录 B. 能力 × 设备类型矩阵#

页面顶部的"我有什么"选择器按这张表折叠不相关的章节。