Partner Sp V1

StackPanel Partner API v1

Partner API v1 的固定网络命名空间是 /sp/v1/*。它面向渠道/合作方系统，不是用户 API，也不是 MCP 的替代品。它以 Ed25519 规范化请求签名认证，并提供 catalog、order 和 service 的合作方操作。

Scope	用途
catalog:read	读取可供渠道销售的目录
order:read / order:write	查询和创建订单
service:read / service:write	查询和管理服务生命周期

写操作要求 Idempotency-Key，所有调用受重放保护、单次 nonce、限流和审计约束。协议细节见请求签名和Webhook。

接口

方法	路径	Scope	输入	成功响应
GET	/sp/v1/catalog	catalog:read	page、pageSize、categoryId 可选	{ items, total, page, pageSize }
GET	/sp/v1/catalog/:id	catalog:read	商品 ID	{ item }
GET	/sp/v1/orders	order:read	page、pageSize 可选	{ items, total, page, pageSize }
GET	/sp/v1/orders/:id	order:read	订单 ID	{ order }
POST	/sp/v1/orders	order:write	下单对象	{ order }
GET	/sp/v1/services	service:read	无	{ items }
GET	/sp/v1/services/:id	service:read	服务 ID	{ service }
POST	/sp/v1/services/:id/:action	service:write	action 为 suspend、resume 或 terminate	{ service }

创建订单的 body：

{
  "productId": "product_123",
  "quantity": 1,
  "channelCode": "partner-reference-42"
}

quantity 范围为 1 到 100。价格、库存和履约均由 commerce 操作权威计算，Partner API 不能传入价格或把订单归属到任意平台用户。订单、服务与目录响应只包含当前 partner 所属资源。

所有失败返回 application/problem+json，使用稳定 code。常见值包括 sp_v1.signature_missing、sp_v1.signature_expired、sp_v1.nonce_replayed、 sp_v1.scope_forbidden、sp_v1.product_unavailable、sp_v1.order_not_found 和 sp_v1.service_not_found。