SellToAI
开发者入驻 / 登录
角色定位后的契约层

面向实现者的 API 参考

确认自己的路径后再用本页。买方 Agent 从 REST/OpenAPI 开始，A2A 宿主发现 Agent Card，Skill 宿主安装 SKILL.md，商家 Agent 使用 registry 与 proposal 契约。

OpenAPI 开发者 打开接入指南

本页内容怎么用

每一块对应一种接入方式，常见顺序如下：

  1. OpenAPI：可以从 `GET /v1/recommend` 快速接入，也可以继续接 `/v1/intents`、`/v1/proposals`、`/v1/match`、`/v1/match-tokens`。生产 API 调用使用 Bearer API key，现成片段在「接入指南 /connect」。
  2. Agent Card：把 A2A 发现地址指向 /.well-known/agent-card.json，能力与网关保持一致。
  3. SKILL.md：Claude / OpenClaw 等技能宿主用「接入指南」里的一行命令安装；技能把自然语言映射到 recommend / card / showcase 调用。
  4. 意图撮合（v0.2）：商家 Agent 先注册，再提交 Proposal；需求侧 Agent 再创建 Match Session，并在接受后铸造 Match Token。事件与对象字段见下方协议文档。

打开接入指南 打开 Try 试玩

OpenAPI 3.0

本网关的 REST 契约以 OpenAPI 发布；与本页文档使用同一 JSON：/openapi.json?locale=zh。路径、方法与字段标识为英文；标题与说明在此视图为中文。

打开 JSON

SellToAI 网关

根据自然语言意图推荐高转化的 TikTok Shop 商品，并附带 KOC 视频与带归因的购买链接；购买链接必须原样交给用户。

在线试玩与接入说明：https://selltoai.ai/ — 可直接调试接口，并复制适用于各主流 Agent 客户端的现成片段。

OpenAPI 3.0.3 · v0.1.0

recommend

推荐与发现接口；生产客户端调用需使用 Developer API key，portal 公开试玩通道除外。

GET /v1/recommend 按自然语言意图推荐商品卡 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
intent query 是 string 用户自然语言意图，例如「给 3 岁侄子买的礼物」。
limit query 否 integer —
region query 否 string 国家或地区 ISO 代码（如 US、UK）。
channel query 否 string 渠道提示（openclaw、cursor、gemini、chatgpt、hermes 等）。

返回

状态码说明
200

成功

响应体结构 — application/json · RecommendResponse

{
  "type": "object",
  "properties": {
    "intent": {
      "type": "string"
    },
    "intent_id": {
      "type": "string"
    },
    "count": {
      "type": "integer"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rec_id": {
            "type": "string",
            "description": "全局唯一推荐 ID；归因主键。"
          },
          "product": {
            "$ref": "#/components/schemas/Product"
          },
          "hero_pitch": {
            "$ref": "#/components/schemas/HeroPitch"
          },
          "selection_story": {
            "$ref": "#/components/schemas/SelectionStory"
          },
          "videos": {
            "type": "array",
            "items": {
              "$ref": "(max depth)"
            }
          },
          "cta": {
            "$ref": "#/components/schemas/Cta"
          },
          "compliance": {
            "type": "object",
            "properties": {
              "region_allow": {
                "$ref": "(max depth)"
              },
              "risk_level": {
                "$ref": "(max depth)"
              }
            }
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "channel": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "rec_id",
          "product",
          "hero_pitch",
          "selection_story",
          "videos",
          "cta",
          "generated_at"
        ]
      }
    },
    "proposals": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "proposal_count": {
      "type": "integer"
    },
    "match_session_id": {
      "type": "string"
    },
    "shopper_guide": {
      "type": "string",
      "description": "Warm, human-facing copy from the shopper agent (Gemini); explains how picks relate to the user's intent."
    },
    "note": {
      "type": "string",
      "description": "Optional machine hint e.g. intent_plus_trending, trending_suggested.",
      "nullable": true
    },
    "match_tier": {
      "type": "string",
      "description": "raw_substring | strict | narrow | fuzzy | broadened | none — how intent rows were retrieved before trending fill."
    },
    "intent_source": {
      "type": "string"
    },
    "resolved_keywords": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "resolved_categories": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "retrieval": {
      "type": "object",
      "properties": {
        "intent_hits": {
          "type": "integer"
        },
        "trending_fill": {
          "type": "integer"
        }
      }
    },
    "generated_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
503

推荐服务暂时不可用。请稍后重试；如果持续出现，请联系 SellToAI 支持。

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}

card

获取或查询已生成的 PCD（商品种草卡）。

GET /v1/cards/{recId} 按 recId 查询已生成的 PCD 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
recId path 是 string —

返回

状态码说明
200

成功

响应体结构 — application/json · PCD

{
  "type": "object",
  "properties": {
    "rec_id": {
      "type": "string",
      "description": "全局唯一推荐 ID；归因主键。"
    },
    "product": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "brand": {
          "type": "string",
          "nullable": true
        },
        "price_usd": {
          "type": "number",
          "nullable": true
        },
        "original_price_usd": {
          "type": "number",
          "nullable": true
        },
        "discount_label": {
          "type": "string",
          "nullable": true
        },
        "main_image": {
          "type": "string",
          "nullable": true
        },
        "gallery": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "category_l1": {
          "type": "string",
          "nullable": true
        },
        "category_l2": {
          "type": "string",
          "nullable": true
        }
      }
    },
    "hero_pitch": {
      "type": "object",
      "properties": {
        "one_liner": {
          "type": "string"
        },
        "why_it_wins_on_tiktok": {
          "type": "string"
        },
        "key_benefits": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "icon": {
                "$ref": "(max depth)"
              },
              "title": {
                "$ref": "(max depth)"
              },
              "desc": {
                "$ref": "(max depth)"
              }
            }
          }
        },
        "target_audience": {
          "type": "object",
          "properties": {
            "persona": {
              "type": "string"
            },
            "age": {
              "type": "string"
            },
            "region": {
              "type": "array",
              "items": {
                "$ref": "(max depth)"
              }
            }
          }
        }
      }
    },
    "selection_story": {
      "type": "object",
      "properties": {
        "headline": {
          "type": "string"
        },
        "bullets": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "moras_score": {
          "type": "number"
        }
      }
    },
    "videos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string"
          },
          "creator": {
            "type": "object",
            "properties": {
              "username": {
                "$ref": "(max depth)"
              },
              "display_name": {
                "$ref": "(max depth)"
              },
              "avatar": {
                "$ref": "(max depth)"
              },
              "followers": {
                "$ref": "(max depth)"
              }
            }
          },
          "thumbnail": {
            "type": "string",
            "nullable": true
          },
          "video_url": {
            "type": "string",
            "nullable": true
          },
          "duration_s": {
            "type": "integer"
          },
          "gmv_usd": {
            "type": "number"
          },
          "orders": {
            "type": "integer"
          },
          "views": {
            "type": "integer"
          },
          "conversion_score": {
            "type": "number"
          },
          "tiktok_video_url": {
            "type": "string",
            "nullable": true
          }
        }
      }
    },
    "cta": {
      "type": "object",
      "properties": {
        "primary": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string"
            },
            "url": {
              "type": "string",
              "description": "必须原样交给用户 — 内含归因 rec_id。"
            }
          }
        },
        "secondary": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string"
            },
            "url": {
              "type": "string"
            }
          }
        }
      }
    },
    "compliance": {
      "type": "object",
      "properties": {
        "region_allow": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "risk_level": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high"
          ]
        }
      }
    },
    "generated_at": {
      "type": "string",
      "format": "date-time"
    },
    "channel": {
      "type": "string",
      "nullable": true
    }
  },
  "required": [
    "rec_id",
    "product",
    "hero_pitch",
    "selection_story",
    "videos",
    "cta",
    "generated_at"
  ],
  "description": "商品种草卡（PCD）— 推荐与归因的最小单元。"
}
404

未找到
GET /v1/products/{productId}/card 按已知商品 ID 生成新的 PCD 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
productId path 是 string —

返回

状态码说明
200

成功

响应体结构 — application/json · PCD

{
  "type": "object",
  "properties": {
    "rec_id": {
      "type": "string",
      "description": "全局唯一推荐 ID；归因主键。"
    },
    "product": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "brand": {
          "type": "string",
          "nullable": true
        },
        "price_usd": {
          "type": "number",
          "nullable": true
        },
        "original_price_usd": {
          "type": "number",
          "nullable": true
        },
        "discount_label": {
          "type": "string",
          "nullable": true
        },
        "main_image": {
          "type": "string",
          "nullable": true
        },
        "gallery": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "category_l1": {
          "type": "string",
          "nullable": true
        },
        "category_l2": {
          "type": "string",
          "nullable": true
        }
      }
    },
    "hero_pitch": {
      "type": "object",
      "properties": {
        "one_liner": {
          "type": "string"
        },
        "why_it_wins_on_tiktok": {
          "type": "string"
        },
        "key_benefits": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "icon": {
                "$ref": "(max depth)"
              },
              "title": {
                "$ref": "(max depth)"
              },
              "desc": {
                "$ref": "(max depth)"
              }
            }
          }
        },
        "target_audience": {
          "type": "object",
          "properties": {
            "persona": {
              "type": "string"
            },
            "age": {
              "type": "string"
            },
            "region": {
              "type": "array",
              "items": {
                "$ref": "(max depth)"
              }
            }
          }
        }
      }
    },
    "selection_story": {
      "type": "object",
      "properties": {
        "headline": {
          "type": "string"
        },
        "bullets": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "moras_score": {
          "type": "number"
        }
      }
    },
    "videos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string"
          },
          "creator": {
            "type": "object",
            "properties": {
              "username": {
                "$ref": "(max depth)"
              },
              "display_name": {
                "$ref": "(max depth)"
              },
              "avatar": {
                "$ref": "(max depth)"
              },
              "followers": {
                "$ref": "(max depth)"
              }
            }
          },
          "thumbnail": {
            "type": "string",
            "nullable": true
          },
          "video_url": {
            "type": "string",
            "nullable": true
          },
          "duration_s": {
            "type": "integer"
          },
          "gmv_usd": {
            "type": "number"
          },
          "orders": {
            "type": "integer"
          },
          "views": {
            "type": "integer"
          },
          "conversion_score": {
            "type": "number"
          },
          "tiktok_video_url": {
            "type": "string",
            "nullable": true
          }
        }
      }
    },
    "cta": {
      "type": "object",
      "properties": {
        "primary": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string"
            },
            "url": {
              "type": "string",
              "description": "必须原样交给用户 — 内含归因 rec_id。"
            }
          }
        },
        "secondary": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string"
            },
            "url": {
              "type": "string"
            }
          }
        }
      }
    },
    "compliance": {
      "type": "object",
      "properties": {
        "region_allow": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "risk_level": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high"
          ]
        }
      }
    },
    "generated_at": {
      "type": "string",
      "format": "date-time"
    },
    "channel": {
      "type": "string",
      "nullable": true
    }
  },
  "required": [
    "rec_id",
    "product",
    "hero_pitch",
    "selection_story",
    "videos",
    "cta",
    "generated_at"
  ],
  "description": "商品种草卡（PCD）— 推荐与归因的最小单元。"
}

creator

浏览创作者带货橱窗。

GET /v1/creators/{username}/showcase 该创作者下表现突出的带货商品 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
username path 是 string —
limit query 否 integer —

返回

状态码说明
200

成功

响应体结构 — application/json · ShowcaseResponse

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "count": {
      "type": "integer"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rec_id": {
            "type": "string",
            "description": "全局唯一推荐 ID；归因主键。"
          },
          "product": {
            "$ref": "#/components/schemas/Product"
          },
          "hero_pitch": {
            "$ref": "#/components/schemas/HeroPitch"
          },
          "selection_story": {
            "$ref": "#/components/schemas/SelectionStory"
          },
          "videos": {
            "type": "array",
            "items": {
              "$ref": "(max depth)"
            }
          },
          "cta": {
            "$ref": "#/components/schemas/Cta"
          },
          "compliance": {
            "type": "object",
            "properties": {
              "region_allow": {
                "$ref": "(max depth)"
              },
              "risk_level": {
                "$ref": "(max depth)"
              }
            }
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "channel": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "rec_id",
          "product",
          "hero_pitch",
          "selection_story",
          "videos",
          "cta",
          "generated_at"
        ]
      }
    }
  }
}

intent

一等 Intent 对象：把自然语言需求变成可继续撮合的标准输入。

POST /v1/intent-mandates/sign 签发电商意图凭证 鉴权 详情

当你的集成已开通该能力时，返回用于有额度边界的 checkout 或 payment 授权流程的 Intent Mandate。

请求参数

无请求参数。

返回

状态码说明
201

Signed mandate

响应体结构 — application/json

{
  "type": "object"
}
400

invalid_body

503

当前集成暂未开放 Intent Mandate 签发能力。
POST /v1/intents 创建一等 Intent 鉴权 详情

请求参数

无请求参数。

返回

状态码说明
201

创建成功

响应体结构 — application/json · IntentResponse

{
  "type": "object",
  "properties": {
    "intent": {
      "type": "object",
      "properties": {
        "intent_id": {
          "type": "string"
        },
        "raw_query": {
          "type": "string"
        },
        "normalized_query": {
          "type": "string",
          "nullable": true
        },
        "intent_tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "target_audience": {
          "type": "string",
          "nullable": true
        },
        "budget_range": {
          "type": "object",
          "nullable": true
        },
        "region": {
          "type": "string",
          "nullable": true
        },
        "constraints": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "source_channel": {
          "type": "string",
          "nullable": true
        },
        "resolution_source": {
          "type": "string",
          "nullable": true
        },
        "resolution_summary": {
          "type": "string",
          "nullable": true
        },
        "metadata": {
          "type": "object"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "time_window": {
          "type": "object",
          "description": "Purchase deadline/urgency window used by agentic commerce workflows.",
          "nullable": true
        },
        "asset_refs": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "attribution_chain": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "workflow": {
          "type": "object",
          "description": "Skill/MCP/A2A execution context for replay and governance."
        },
        "experience_context": {
          "type": "object",
          "description": "Experience intent context: scene, self_context, desired_feeling, visual constraints and confirmation goal."
        }
      }
    }
  }
}
400

missing_fields
GET /v1/intents/{intentId} 按 intent_id 查询 Intent 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
intentId path 是 string —

返回

状态码说明
200

OK

响应体结构 — application/json · IntentResponse

{
  "type": "object",
  "properties": {
    "intent": {
      "type": "object",
      "properties": {
        "intent_id": {
          "type": "string"
        },
        "raw_query": {
          "type": "string"
        },
        "normalized_query": {
          "type": "string",
          "nullable": true
        },
        "intent_tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "target_audience": {
          "type": "string",
          "nullable": true
        },
        "budget_range": {
          "type": "object",
          "nullable": true
        },
        "region": {
          "type": "string",
          "nullable": true
        },
        "constraints": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "source_channel": {
          "type": "string",
          "nullable": true
        },
        "resolution_source": {
          "type": "string",
          "nullable": true
        },
        "resolution_summary": {
          "type": "string",
          "nullable": true
        },
        "metadata": {
          "type": "object"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "time_window": {
          "type": "object",
          "description": "Purchase deadline/urgency window used by agentic commerce workflows.",
          "nullable": true
        },
        "asset_refs": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "attribution_chain": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "workflow": {
          "type": "object",
          "description": "Skill/MCP/A2A execution context for replay and governance."
        },
        "experience_context": {
          "type": "object",
          "description": "Experience intent context: scene, self_context, desired_feeling, visual constraints and confirmation goal."
        }
      }
    }
  }
}
404

intent_not_found
GET /v1/intents/{intentId}/proposals 列出某个 Intent 下的 Proposal 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
intentId path 是 string —
include_expired query 否 boolean —

返回

状态码说明
200

OK

响应体结构 — application/json · IntentProposalListResponse

{
  "type": "object",
  "properties": {
    "intent_id": {
      "type": "string"
    },
    "count": {
      "type": "integer"
    },
    "proposals": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "proposal_id": {
            "type": "string"
          },
          "merchant_agent_id": {
            "type": "string"
          },
          "intent_id": {
            "type": "string"
          },
          "product_id": {
            "type": "integer"
          },
          "offer_title": {
            "type": "string"
          },
          "price": {
            "type": "number",
            "nullable": true
          },
          "inventory_status": {
            "type": "string"
          },
          "shipping_commitment": {
            "type": "object"
          },
          "commission_plan": {
            "type": "object"
          },
          "service_terms": {
            "type": "object"
          },
          "evidence": {
            "type": "array",
            "items": {
              "$ref": "(max depth)"
            }
          },
          "valid_until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "proposal_score_inputs": {
            "type": "object"
          },
          "product_snapshot": {
            "type": "object",
            "nullable": true
          },
          "metadata": {
            "type": "object"
          },
          "provenance": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "asset_refs": {
            "type": "array",
            "items": {
              "$ref": "(max depth)"
            }
          },
          "trust_score": {
            "type": "object",
            "description": "Normalized trust/risk score and basis used for ranking/audit."
          },
          "attribution_chain": {
            "type": "array",
            "items": {
              "$ref": "(max depth)"
            }
          },
          "proposal_state": {
            "type": "string",
            "description": "Commerce proposal lifecycle state.",
            "enum": [
              "draft",
              "quoted",
              "pending_confirmation",
              "accepted",
              "settled",
              "expired"
            ]
          },
          "workflow": {
            "type": "object",
            "description": "Skill/MCP/A2A execution context for replay and governance."
          },
          "experience_preview": {
            "type": "object",
            "description": "Generated or referenced preview asset, scene preview and remixable dimensions."
          },
          "experience_card": {
            "$ref": "#/components/schemas/ExperienceCard"
          }
        }
      }
    }
  }
}
404

intent_not_found

proposal

商家侧 Proposal：围绕某个 Intent 返回结构化报价与履约信息。

POST /v1/proposals 提交 Merchant Proposal 鉴权 详情

请求参数

无请求参数。

返回

状态码说明
201

创建成功

响应体结构 — application/json · ProposalResponse

{
  "type": "object",
  "properties": {
    "proposal": {
      "type": "object",
      "properties": {
        "proposal_id": {
          "type": "string"
        },
        "merchant_agent_id": {
          "type": "string"
        },
        "intent_id": {
          "type": "string"
        },
        "product_id": {
          "type": "integer"
        },
        "offer_title": {
          "type": "string"
        },
        "price": {
          "type": "number",
          "nullable": true
        },
        "inventory_status": {
          "type": "string"
        },
        "shipping_commitment": {
          "type": "object"
        },
        "commission_plan": {
          "type": "object"
        },
        "service_terms": {
          "type": "object"
        },
        "evidence": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "valid_until": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "proposal_score_inputs": {
          "type": "object"
        },
        "product_snapshot": {
          "type": "object",
          "nullable": true
        },
        "metadata": {
          "type": "object"
        },
        "provenance": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "asset_refs": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "trust_score": {
          "type": "object",
          "description": "Normalized trust/risk score and basis used for ranking/audit."
        },
        "attribution_chain": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "proposal_state": {
          "type": "string",
          "description": "Commerce proposal lifecycle state.",
          "enum": [
            "draft",
            "quoted",
            "pending_confirmation",
            "accepted",
            "settled",
            "expired"
          ]
        },
        "workflow": {
          "type": "object",
          "description": "Skill/MCP/A2A execution context for replay and governance."
        },
        "experience_preview": {
          "type": "object",
          "description": "Generated or referenced preview asset, scene preview and remixable dimensions."
        },
        "experience_card": {
          "type": "object",
          "properties": {
            "experience_id": {
              "$ref": "(max depth)"
            },
            "intent_id": {
              "$ref": "(max depth)"
            },
            "proposal_id": {
              "$ref": "(max depth)"
            },
            "scene": {
              "$ref": "(max depth)"
            },
            "preview": {
              "$ref": "(max depth)"
            },
            "products": {
              "$ref": "(max depth)"
            },
            "creator_evidence": {
              "$ref": "(max depth)"
            },
            "why_it_fits_you": {
              "$ref": "(max depth)"
            },
            "remix_actions": {
              "$ref": "(max depth)"
            },
            "cta": {
              "$ref": "(max depth)"
            }
          }
        }
      }
    }
  }
}
401

missing registration token

403

invalid registration token

404

intent_not_found or merchant_not_found
GET /v1/proposals/{proposalId} 按 proposal_id 查询 Proposal 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
proposalId path 是 string —

返回

状态码说明
200

OK

响应体结构 — application/json · ProposalResponse

{
  "type": "object",
  "properties": {
    "proposal": {
      "type": "object",
      "properties": {
        "proposal_id": {
          "type": "string"
        },
        "merchant_agent_id": {
          "type": "string"
        },
        "intent_id": {
          "type": "string"
        },
        "product_id": {
          "type": "integer"
        },
        "offer_title": {
          "type": "string"
        },
        "price": {
          "type": "number",
          "nullable": true
        },
        "inventory_status": {
          "type": "string"
        },
        "shipping_commitment": {
          "type": "object"
        },
        "commission_plan": {
          "type": "object"
        },
        "service_terms": {
          "type": "object"
        },
        "evidence": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "valid_until": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "proposal_score_inputs": {
          "type": "object"
        },
        "product_snapshot": {
          "type": "object",
          "nullable": true
        },
        "metadata": {
          "type": "object"
        },
        "provenance": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "asset_refs": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "trust_score": {
          "type": "object",
          "description": "Normalized trust/risk score and basis used for ranking/audit."
        },
        "attribution_chain": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "proposal_state": {
          "type": "string",
          "description": "Commerce proposal lifecycle state.",
          "enum": [
            "draft",
            "quoted",
            "pending_confirmation",
            "accepted",
            "settled",
            "expired"
          ]
        },
        "workflow": {
          "type": "object",
          "description": "Skill/MCP/A2A execution context for replay and governance."
        },
        "experience_preview": {
          "type": "object",
          "description": "Generated or referenced preview asset, scene preview and remixable dimensions."
        },
        "experience_card": {
          "type": "object",
          "properties": {
            "experience_id": {
              "$ref": "(max depth)"
            },
            "intent_id": {
              "$ref": "(max depth)"
            },
            "proposal_id": {
              "$ref": "(max depth)"
            },
            "scene": {
              "$ref": "(max depth)"
            },
            "preview": {
              "$ref": "(max depth)"
            },
            "products": {
              "$ref": "(max depth)"
            },
            "creator_evidence": {
              "$ref": "(max depth)"
            },
            "why_it_fits_you": {
              "$ref": "(max depth)"
            },
            "remix_actions": {
              "$ref": "(max depth)"
            },
            "cta": {
              "$ref": "(max depth)"
            }
          }
        }
      }
    }
  }
}
404

proposal_not_found

match

围绕 Intent + Proposal 生成 Match Session 与 Match Token。

POST /v1/match 基于 Intent 与 Proposal 创建 Match Session 鉴权 详情

请求参数

无请求参数。

返回

状态码说明
201

创建成功

响应体结构 — application/json · MatchSessionResponse

{
  "type": "object",
  "properties": {
    "match_session": {
      "type": "object",
      "properties": {
        "match_session_id": {
          "type": "string"
        },
        "intent_id": {
          "type": "string"
        },
        "best_proposal_id": {
          "type": "string",
          "nullable": true
        },
        "ranked_proposals": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "summary": {
          "type": "object"
        },
        "status": {
          "type": "string"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    }
  }
}
400

missing_fields

404

intent_not_found or proposal_not_found
GET /v1/match/{matchSessionId} 获取渲染后的 Match Session 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
matchSessionId path 是 string —
limit query 否 integer —

返回

状态码说明
200

OK

响应体结构 — application/json · MatchRenderedResponse

{
  "type": "object",
  "properties": {
    "match_session": {
      "type": "object",
      "properties": {
        "match_session_id": {
          "type": "string"
        },
        "intent_id": {
          "type": "string"
        },
        "best_proposal_id": {
          "type": "string",
          "nullable": true
        },
        "ranked_proposals": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "summary": {
          "type": "object"
        },
        "status": {
          "type": "string"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    },
    "ranked_proposals": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "match_tokens": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "match_token_id": {
            "type": "string"
          },
          "match_session_id": {
            "type": "string"
          },
          "intent_id": {
            "type": "string"
          },
          "proposal_id": {
            "type": "string"
          },
          "acceptance_state": {
            "type": "string"
          },
          "intent_snapshot": {
            "type": "object"
          },
          "proposal_snapshot": {
            "type": "object"
          },
          "ranking_snapshot": {
            "type": "object"
          },
          "trace_ids": {
            "type": "object"
          },
          "issued_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "accepted_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      }
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rec_id": {
            "type": "string",
            "description": "全局唯一推荐 ID；归因主键。"
          },
          "product": {
            "$ref": "#/components/schemas/Product"
          },
          "hero_pitch": {
            "$ref": "#/components/schemas/HeroPitch"
          },
          "selection_story": {
            "$ref": "#/components/schemas/SelectionStory"
          },
          "videos": {
            "type": "array",
            "items": {
              "$ref": "(max depth)"
            }
          },
          "cta": {
            "$ref": "#/components/schemas/Cta"
          },
          "compliance": {
            "type": "object",
            "properties": {
              "region_allow": {
                "$ref": "(max depth)"
              },
              "risk_level": {
                "$ref": "(max depth)"
              }
            }
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "channel": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "rec_id",
          "product",
          "hero_pitch",
          "selection_story",
          "videos",
          "cta",
          "generated_at"
        ]
      }
    }
  }
}
404

match_not_found
POST /v1/match/{matchSessionId}/accept 接受 Proposal 并铸造 / 确认 Match Token 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
matchSessionId path 是 string —

返回

状态码说明
200

OK

响应体结构 — application/json · MatchTokenResponse

{
  "type": "object",
  "properties": {
    "match_token": {
      "type": "object",
      "properties": {
        "match_token_id": {
          "type": "string"
        },
        "match_session_id": {
          "type": "string"
        },
        "intent_id": {
          "type": "string"
        },
        "proposal_id": {
          "type": "string"
        },
        "acceptance_state": {
          "type": "string"
        },
        "intent_snapshot": {
          "type": "object"
        },
        "proposal_snapshot": {
          "type": "object"
        },
        "ranking_snapshot": {
          "type": "object"
        },
        "trace_ids": {
          "type": "object"
        },
        "issued_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "accepted_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    }
  }
}
404

match_not_found
GET /v1/match-tokens/{matchTokenId} 按 id 查询 Match Token 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
matchTokenId path 是 string —

返回

状态码说明
200

OK

响应体结构 — application/json · MatchTokenResponse

{
  "type": "object",
  "properties": {
    "match_token": {
      "type": "object",
      "properties": {
        "match_token_id": {
          "type": "string"
        },
        "match_session_id": {
          "type": "string"
        },
        "intent_id": {
          "type": "string"
        },
        "proposal_id": {
          "type": "string"
        },
        "acceptance_state": {
          "type": "string"
        },
        "intent_snapshot": {
          "type": "object"
        },
        "proposal_snapshot": {
          "type": "object"
        },
        "ranking_snapshot": {
          "type": "object"
        },
        "trace_ids": {
          "type": "object"
        },
        "issued_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "accepted_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    }
  }
}
404

match_token_not_found

merchant

商家 / 供给侧 Agent 入驻与生命周期接口（持久化注册）。

POST /v1/merchant/register 注册商家 Agent（意图撮合 v0.2） 鉴权 详情

登记 webhook 与订阅标签、能力声明与区域范围。当前注册已持久化，支持心跳、健康检查、Proposal 提交与 Intent.Surge 分发。规范见本网关 /docs/INTENT_MATCHING_PROTOCOL.md。

请求参数

无请求参数。

返回

状态码说明
200

成功

响应体结构 — application/json · MerchantRegisterResponse

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "created": {
      "type": "boolean"
    },
    "merchant_id": {
      "type": "string"
    },
    "registration_token": {
      "type": "string",
      "description": "Secret token used for heartbeat, updates, deactivation, and proposal submission."
    },
    "merchant": {
      "type": "object",
      "properties": {
        "merchant_id": {
          "type": "string"
        },
        "agent_endpoint": {
          "type": "string"
        },
        "subscription_tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "regions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "category_tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "inventory_scope": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "protocol_version": {
          "type": "string",
          "nullable": true
        },
        "a2a_capabilities": {
          "type": "object"
        },
        "metadata": {
          "type": "object"
        },
        "status": {
          "type": "string"
        },
        "registered_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_seen_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "deactivated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "workflow_context": {
          "type": "object",
          "properties": {
            "origin_workflow": {
              "$ref": "(max depth)"
            },
            "accepted_intent_shapes": {
              "$ref": "(max depth)"
            },
            "required_context": {
              "$ref": "(max depth)"
            },
            "proposal_response_sla_seconds": {
              "$ref": "(max depth)"
            },
            "checkout_modes": {
              "$ref": "(max depth)"
            }
          }
        },
        "trust_evidence_policy": {
          "type": "object",
          "properties": {
            "community_proof_required": {
              "$ref": "(max depth)"
            },
            "accepted_sources": {
              "$ref": "(max depth)"
            },
            "min_consensus_score": {
              "$ref": "(max depth)"
            },
            "contradiction_handling": {
              "$ref": "(max depth)"
            }
          }
        },
        "agent_ready_profile": {
          "type": "object",
          "properties": {
            "destination_strategy": {
              "$ref": "(max depth)"
            },
            "proposal_contract": {
              "$ref": "(max depth)"
            },
            "attribution_mode": {
              "$ref": "(max depth)"
            }
          }
        }
      }
    }
  }
}
400

缺少必填字段
GET /v1/merchant/{merchantId} 按 merchant_id 查询注册中的商家 Agent 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
merchantId path 是 string —

返回

状态码说明
200

OK

响应体结构 — application/json · MerchantLookupResponse

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "nullable": true
    },
    "merchant": {
      "type": "object",
      "properties": {
        "merchant_id": {
          "type": "string"
        },
        "agent_endpoint": {
          "type": "string"
        },
        "subscription_tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "regions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "category_tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "inventory_scope": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "protocol_version": {
          "type": "string",
          "nullable": true
        },
        "a2a_capabilities": {
          "type": "object"
        },
        "metadata": {
          "type": "object"
        },
        "status": {
          "type": "string"
        },
        "registered_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_seen_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "deactivated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "workflow_context": {
          "type": "object",
          "properties": {
            "origin_workflow": {
              "$ref": "(max depth)"
            },
            "accepted_intent_shapes": {
              "$ref": "(max depth)"
            },
            "required_context": {
              "$ref": "(max depth)"
            },
            "proposal_response_sla_seconds": {
              "$ref": "(max depth)"
            },
            "checkout_modes": {
              "$ref": "(max depth)"
            }
          }
        },
        "trust_evidence_policy": {
          "type": "object",
          "properties": {
            "community_proof_required": {
              "$ref": "(max depth)"
            },
            "accepted_sources": {
              "$ref": "(max depth)"
            },
            "min_consensus_score": {
              "$ref": "(max depth)"
            },
            "contradiction_handling": {
              "$ref": "(max depth)"
            }
          }
        },
        "agent_ready_profile": {
          "type": "object",
          "properties": {
            "destination_strategy": {
              "$ref": "(max depth)"
            },
            "proposal_contract": {
              "$ref": "(max depth)"
            },
            "attribution_mode": {
              "$ref": "(max depth)"
            }
          }
        }
      }
    }
  }
}
404

merchant_not_found
GET /v1/merchant/{merchantId}/health 探测商家 Agent 健康状态 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
merchantId path 是 string —

返回

状态码说明
200

merchant healthy

503

merchant unhealthy or unreachable
POST /v1/merchant/heartbeat 商家 Agent 心跳 鉴权 详情

请求参数

无请求参数。

返回

状态码说明
200

OK

响应体结构 — application/json · MerchantLookupResponse

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "nullable": true
    },
    "merchant": {
      "type": "object",
      "properties": {
        "merchant_id": {
          "type": "string"
        },
        "agent_endpoint": {
          "type": "string"
        },
        "subscription_tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "regions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "category_tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "inventory_scope": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "protocol_version": {
          "type": "string",
          "nullable": true
        },
        "a2a_capabilities": {
          "type": "object"
        },
        "metadata": {
          "type": "object"
        },
        "status": {
          "type": "string"
        },
        "registered_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_seen_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "deactivated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "workflow_context": {
          "type": "object",
          "properties": {
            "origin_workflow": {
              "$ref": "(max depth)"
            },
            "accepted_intent_shapes": {
              "$ref": "(max depth)"
            },
            "required_context": {
              "$ref": "(max depth)"
            },
            "proposal_response_sla_seconds": {
              "$ref": "(max depth)"
            },
            "checkout_modes": {
              "$ref": "(max depth)"
            }
          }
        },
        "trust_evidence_policy": {
          "type": "object",
          "properties": {
            "community_proof_required": {
              "$ref": "(max depth)"
            },
            "accepted_sources": {
              "$ref": "(max depth)"
            },
            "min_consensus_score": {
              "$ref": "(max depth)"
            },
            "contradiction_handling": {
              "$ref": "(max depth)"
            }
          }
        },
        "agent_ready_profile": {
          "type": "object",
          "properties": {
            "destination_strategy": {
              "$ref": "(max depth)"
            },
            "proposal_contract": {
              "$ref": "(max depth)"
            },
            "attribution_mode": {
              "$ref": "(max depth)"
            }
          }
        }
      }
    }
  }
}
401

missing registration token

403

invalid registration token
POST /v1/merchant/{merchantId}/deactivate 停用商家 Agent 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
merchantId path 是 string —

返回

状态码说明
200

OK

响应体结构 — application/json · MerchantLookupResponse

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "nullable": true
    },
    "merchant": {
      "type": "object",
      "properties": {
        "merchant_id": {
          "type": "string"
        },
        "agent_endpoint": {
          "type": "string"
        },
        "subscription_tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "regions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "category_tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "inventory_scope": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "protocol_version": {
          "type": "string",
          "nullable": true
        },
        "a2a_capabilities": {
          "type": "object"
        },
        "metadata": {
          "type": "object"
        },
        "status": {
          "type": "string"
        },
        "registered_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_seen_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "deactivated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "workflow_context": {
          "type": "object",
          "properties": {
            "origin_workflow": {
              "$ref": "(max depth)"
            },
            "accepted_intent_shapes": {
              "$ref": "(max depth)"
            },
            "required_context": {
              "$ref": "(max depth)"
            },
            "proposal_response_sla_seconds": {
              "$ref": "(max depth)"
            },
            "checkout_modes": {
              "$ref": "(max depth)"
            }
          }
        },
        "trust_evidence_policy": {
          "type": "object",
          "properties": {
            "community_proof_required": {
              "$ref": "(max depth)"
            },
            "accepted_sources": {
              "$ref": "(max depth)"
            },
            "min_consensus_score": {
              "$ref": "(max depth)"
            },
            "contradiction_handling": {
              "$ref": "(max depth)"
            }
          }
        },
        "agent_ready_profile": {
          "type": "object",
          "properties": {
            "destination_strategy": {
              "$ref": "(max depth)"
            },
            "proposal_contract": {
              "$ref": "(max depth)"
            },
            "attribution_mode": {
              "$ref": "(max depth)"
            }
          }
        }
      }
    }
  }
}
401

missing registration token

403

invalid registration token
GET /v1/merchant/{merchantId}/agent-readiness Assess whether a merchant is ready for embedded AI shopping workflows 鉴权 详情

Scores a registered merchant against the Agent-ready commerce checklist: workflow context, committed proposal contract, trust evidence policy, and MatchToken attribution. This translates the AI-commerce shift from destination apps to embedded workflows into a concrete supply-side gate.

请求参数

名称 位置 是否必填 类型 说明
merchantId path 是 string —

返回

状态码说明
200

OK

响应体结构 — application/json · MerchantAgentReadinessResponse

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string"
    },
    "merchant_id": {
      "type": "string"
    },
    "score": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100
    },
    "summary": {
      "type": "object",
      "properties": {
        "ready_for_embedded_workflows": {
          "type": "boolean"
        },
        "insight": {
          "type": "string"
        },
        "next_upgrade": {
          "type": "string"
        }
      }
    },
    "checks": {
      "type": "object"
    },
    "merchant": {
      "type": "object",
      "properties": {
        "merchant_id": {
          "type": "string"
        },
        "agent_endpoint": {
          "type": "string"
        },
        "subscription_tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "regions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "category_tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "inventory_scope": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "protocol_version": {
          "type": "string",
          "nullable": true
        },
        "a2a_capabilities": {
          "type": "object"
        },
        "metadata": {
          "type": "object"
        },
        "status": {
          "type": "string"
        },
        "registered_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_seen_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "deactivated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "workflow_context": {
          "type": "object",
          "properties": {
            "origin_workflow": {
              "$ref": "(max depth)"
            },
            "accepted_intent_shapes": {
              "$ref": "(max depth)"
            },
            "required_context": {
              "$ref": "(max depth)"
            },
            "proposal_response_sla_seconds": {
              "$ref": "(max depth)"
            },
            "checkout_modes": {
              "$ref": "(max depth)"
            }
          }
        },
        "trust_evidence_policy": {
          "type": "object",
          "properties": {
            "community_proof_required": {
              "$ref": "(max depth)"
            },
            "accepted_sources": {
              "$ref": "(max depth)"
            },
            "min_consensus_score": {
              "$ref": "(max depth)"
            },
            "contradiction_handling": {
              "$ref": "(max depth)"
            }
          }
        },
        "agent_ready_profile": {
          "type": "object",
          "properties": {
            "destination_strategy": {
              "$ref": "(max depth)"
            },
            "proposal_contract": {
              "$ref": "(max depth)"
            },
            "attribution_mode": {
              "$ref": "(max depth)"
            }
          }
        }
      }
    }
  }
}
404

merchant_not_found
GET /v1/merchant/dispatch-queue List merchant dispatch queue and DLQ deliveries 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
X-Supply-Key header 是 string Supply/admin key for operational reporting and replay endpoints.
state query 否 string —
merchant_id query 否 string —
intent_id query 否 string —

返回

状态码说明
200

Queue summary and deliveries

401

Invalid or missing supply key
POST /v1/merchant/dispatch-queue/retry Retry one DLQ delivery or replay all DLQ deliveries 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
X-Supply-Key header 是 string Supply/admin key for operational reporting and replay endpoints.

返回

状态码说明
200

Retry results

401

Invalid or missing supply key
GET /v1/merchant/{merchantId}/sla Get merchant SLA metrics from feedback events 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
X-Supply-Key header 是 string Supply/admin key for operational reporting and replay endpoints.
merchantId path 是 string —

返回

状态码说明
200

Merchant SLA summary

401

Invalid or missing supply key
GET /v1/merchant/{merchantId}/reputation Recompute and return merchant reputation snapshot 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
X-Supply-Key header 是 string Supply/admin key for operational reporting and replay endpoints.
merchantId path 是 string —

返回

状态码说明
200

Merchant reputation snapshot

401

Invalid or missing supply key

agents

General Commerce Agent registry: merchant, payment, logistics, creator, demand-side, and SellToAI / Moras core agents.

POST /v1/agents/register Register a Commerce Agent 鉴权 详情

Registers any external commerce agent (merchant/payment/logistics/creator/demand) with protocol and capability declarations.

请求参数

无请求参数。

返回

状态码说明
200

Updated

响应体结构 — application/json · CommerceAgentRegisterResponse

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "created": {
      "type": "boolean"
    },
    "agent_id": {
      "type": "string"
    },
    "registration_token": {
      "type": "string",
      "description": "Secret token for heartbeat, updates and deactivation."
    },
    "agent": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "string"
        },
        "agent_type": {
          "type": "string"
        },
        "endpoint": {
          "type": "string"
        },
        "agent_card_url": {
          "type": "string",
          "nullable": true
        },
        "protocols": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "auth_methods": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capability_profile": {
          "type": "object"
        },
        "regions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "metadata": {
          "type": "object"
        },
        "status": {
          "type": "string"
        },
        "registered_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_seen_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "deactivated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    }
  }
}
201

Created

响应体结构 — application/json · CommerceAgentRegisterResponse

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "created": {
      "type": "boolean"
    },
    "agent_id": {
      "type": "string"
    },
    "registration_token": {
      "type": "string",
      "description": "Secret token for heartbeat, updates and deactivation."
    },
    "agent": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "string"
        },
        "agent_type": {
          "type": "string"
        },
        "endpoint": {
          "type": "string"
        },
        "agent_card_url": {
          "type": "string",
          "nullable": true
        },
        "protocols": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "auth_methods": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capability_profile": {
          "type": "object"
        },
        "regions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "metadata": {
          "type": "object"
        },
        "status": {
          "type": "string"
        },
        "registered_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_seen_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "deactivated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    }
  }
}
400

missing_fields
POST /v1/agents/import-card Import an A2A Agent Card 鉴权 详情

Imports an inline agent_card or fetches agent_card_url, maps skills/endpoints into a Commerce Agent capability profile, and registers it.

请求参数

无请求参数。

返回

状态码说明
201

Created

响应体结构 — application/json · CommerceAgentRegisterResponse

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "created": {
      "type": "boolean"
    },
    "agent_id": {
      "type": "string"
    },
    "registration_token": {
      "type": "string",
      "description": "Secret token for heartbeat, updates and deactivation."
    },
    "agent": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "string"
        },
        "agent_type": {
          "type": "string"
        },
        "endpoint": {
          "type": "string"
        },
        "agent_card_url": {
          "type": "string",
          "nullable": true
        },
        "protocols": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "auth_methods": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capability_profile": {
          "type": "object"
        },
        "regions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "metadata": {
          "type": "object"
        },
        "status": {
          "type": "string"
        },
        "registered_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_seen_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "deactivated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    }
  }
}
502

agent_card_fetch_failed
GET /v1/agents List Commerce Agents 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
agent_type query 否 string —
status query 否 string —

返回

状态码说明
200

OK

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "agents": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "agent_id": {
            "type": "string"
          },
          "agent_type": {
            "type": "string"
          },
          "endpoint": {
            "type": "string"
          },
          "agent_card_url": {
            "type": "string",
            "nullable": true
          },
          "protocols": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "auth_methods": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "capability_profile": {
            "type": "object"
          },
          "regions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "metadata": {
            "type": "object"
          },
          "status": {
            "type": "string"
          },
          "registered_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "last_seen_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "deactivated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      }
    }
  }
}
GET /v1/agents/{agentId} Fetch a Commerce Agent 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
agentId path 是 string —

返回

状态码说明
200

OK

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "agent": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "string"
        },
        "agent_type": {
          "type": "string"
        },
        "endpoint": {
          "type": "string"
        },
        "agent_card_url": {
          "type": "string",
          "nullable": true
        },
        "protocols": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "auth_methods": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capability_profile": {
          "type": "object"
        },
        "regions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "metadata": {
          "type": "object"
        },
        "status": {
          "type": "string"
        },
        "registered_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_seen_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "deactivated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    }
  }
}
404

agent_not_found
POST /v1/agents/{agentId}/heartbeat Heartbeat a Commerce Agent 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
agentId path 是 string —

返回

状态码说明
200

OK

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "agent": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "string"
        },
        "agent_type": {
          "type": "string"
        },
        "endpoint": {
          "type": "string"
        },
        "agent_card_url": {
          "type": "string",
          "nullable": true
        },
        "protocols": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "auth_methods": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capability_profile": {
          "type": "object"
        },
        "regions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "metadata": {
          "type": "object"
        },
        "status": {
          "type": "string"
        },
        "registered_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_seen_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "deactivated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    }
  }
}
401

X-Agent-Token required
POST /v1/agents/{agentId}/deactivate Deactivate a Commerce Agent 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
agentId path 是 string —

返回

状态码说明
200

OK

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "agent": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "string"
        },
        "agent_type": {
          "type": "string"
        },
        "endpoint": {
          "type": "string"
        },
        "agent_card_url": {
          "type": "string",
          "nullable": true
        },
        "protocols": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "auth_methods": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "capability_profile": {
          "type": "object"
        },
        "regions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "metadata": {
          "type": "object"
        },
        "status": {
          "type": "string"
        },
        "registered_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_seen_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "deactivated_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    }
  }
}

report

供给方 ROI 报表（需 X-Supply-Key）。

GET /v1/report/attribution ROI 报表（供给方，需 X-Supply-Key） 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
days query 否 integer —
channel query 否 string —
product_id query 否 string —

返回

状态码说明
200

成功

401

未授权

developer

开发者账号注册、登录、邀请码验证、API Key 管理与请求日志。

POST /v1/developers/register 注册开发者账号 详情

Creates a password-based developer account and returns a console session token. API keys are created separately after invite verification.

请求参数

无请求参数。

返回

状态码说明
201

Developer account created; use developer_token for console management endpoints.

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "developer": {
      "type": "object",
      "properties": {
        "developer_id": {
          "type": "string"
        },
        "display_name": {
          "type": "string"
        },
        "contact_email": {
          "type": "string"
        },
        "company": {
          "type": "string",
          "nullable": true
        },
        "website": {
          "type": "string",
          "nullable": true
        },
        "status": {
          "type": "string"
        },
        "invite_verified_at": {
          "type": "string",
          "nullable": true
        },
        "metadata": {
          "type": "object"
        },
        "created_at": {
          "type": "string",
          "nullable": true
        },
        "updated_at": {
          "type": "string",
          "nullable": true
        }
      }
    },
    "developer_token": {
      "type": "string",
      "description": "Console session token for developer management endpoints."
    },
    "session": {
      "type": "object",
      "properties": {
        "session_id": {
          "type": "string"
        },
        "developer_id": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "expires_at": {
          "type": "string",
          "nullable": true
        },
        "created_at": {
          "type": "string",
          "nullable": true
        },
        "last_used_at": {
          "type": "string",
          "nullable": true
        }
      }
    },
    "invite_verified": {
      "type": "boolean"
    }
  }
}
400

Invalid registration payload

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
409

Developer account already exists for this email

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
GET /v1/developers/me 获取当前开发者档案 鉴权 详情

Requires a developer_token from register or login, not an API key.

请求参数

无请求参数。

返回

状态码说明
200

Developer profile, console session, invite status, and API keys.

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "developer": {
      "type": "object",
      "properties": {
        "developer_id": {
          "type": "string"
        },
        "display_name": {
          "type": "string"
        },
        "contact_email": {
          "type": "string"
        },
        "company": {
          "type": "string",
          "nullable": true
        },
        "website": {
          "type": "string",
          "nullable": true
        },
        "status": {
          "type": "string"
        },
        "invite_verified_at": {
          "type": "string",
          "nullable": true
        },
        "metadata": {
          "type": "object"
        },
        "created_at": {
          "type": "string",
          "nullable": true
        },
        "updated_at": {
          "type": "string",
          "nullable": true
        }
      }
    },
    "session": {
      "type": "object",
      "properties": {
        "session_id": {
          "type": "string"
        },
        "developer_id": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "expires_at": {
          "type": "string",
          "nullable": true
        },
        "created_at": {
          "type": "string",
          "nullable": true
        },
        "last_used_at": {
          "type": "string",
          "nullable": true
        }
      }
    },
    "invite_verified": {
      "type": "boolean"
    },
    "keys": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key_id": {
            "type": "string"
          },
          "developer_id": {
            "type": "string"
          },
          "key_prefix": {
            "type": "string"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "revoked",
              "deleted"
            ]
          },
          "last_used_at": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "nullable": true
          },
          "revoked_at": {
            "type": "string",
            "nullable": true
          },
          "can_reveal": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
401

Missing or invalid developer session token

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
GET /v1/developers/keys 列出当前开发者的 API Keys 鉴权 详情

Requires a developer_token from register or login.

请求参数

无请求参数。

返回

状态码说明
200

API keys.

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "invite_verified": {
      "type": "boolean"
    },
    "keys": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key_id": {
            "type": "string"
          },
          "developer_id": {
            "type": "string"
          },
          "key_prefix": {
            "type": "string"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "revoked",
              "deleted"
            ]
          },
          "last_used_at": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "nullable": true
          },
          "revoked_at": {
            "type": "string",
            "nullable": true
          },
          "can_reveal": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
401

Missing or invalid developer session token

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
POST /v1/developers/keys 邀请码验证后创建新的 API Key 鉴权 详情

需要 developer_token 和已验证的邀请码。完整 API key 会随响应返回，也可在开发者控制台再次显示完整值并复制。

请求参数

无请求参数。

返回

状态码说明
201

API Key 已创建，可复制完整值。

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "api_key": {
      "type": "string"
    },
    "key": {
      "type": "object",
      "properties": {
        "key_id": {
          "type": "string"
        },
        "developer_id": {
          "type": "string"
        },
        "key_prefix": {
          "type": "string"
        },
        "label": {
          "type": "string",
          "nullable": true
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "revoked",
            "deleted"
          ]
        },
        "last_used_at": {
          "type": "string",
          "nullable": true
        },
        "created_at": {
          "type": "string",
          "nullable": true
        },
        "revoked_at": {
          "type": "string",
          "nullable": true
        },
        "can_reveal": {
          "type": "boolean"
        }
      }
    },
    "warning": {
      "type": "string"
    }
  }
}
401

Missing or invalid developer session token

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
403

Invite verification is required before creating API keys

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
POST /v1/developers/keys/{keyId}/revoke 停用 API Key（旧接口，建议用 DELETE 删除） 鉴权 详情

Requires a developer_token from register or login.

请求参数

名称 位置 是否必填 类型 说明
keyId path 是 string —

返回

状态码说明
200

Key revoked.

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "key": {
      "type": "object",
      "properties": {
        "key_id": {
          "type": "string"
        },
        "developer_id": {
          "type": "string"
        },
        "key_prefix": {
          "type": "string"
        },
        "label": {
          "type": "string",
          "nullable": true
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "revoked",
            "deleted"
          ]
        },
        "last_used_at": {
          "type": "string",
          "nullable": true
        },
        "created_at": {
          "type": "string",
          "nullable": true
        },
        "revoked_at": {
          "type": "string",
          "nullable": true
        },
        "can_reveal": {
          "type": "boolean"
        }
      }
    }
  }
}
401

Missing or invalid developer session token

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
404

API key not found

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
GET /v1/developers/logs 查看最近的已鉴权请求日志 鉴权 详情

Requires a developer_token from register or login.

请求参数

名称 位置 是否必填 类型 说明
limit query 否 integer —

返回

状态码说明
200

Request logs.

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "logs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string"
          },
          "key_id": {
            "type": "string"
          },
          "channel": {
            "type": "string",
            "nullable": true
          },
          "method": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "status_code": {
            "type": "integer"
          },
          "duration_ms": {
            "type": "integer"
          },
          "created_at": {
            "type": "string"
          }
        }
      }
    }
  }
}
401

Missing or invalid developer session token

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
POST /v1/developers/login 登录开发者控制台 详情

请求参数

无请求参数。

返回

状态码说明
200

Developer console session created.

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "developer": {
      "type": "object",
      "properties": {
        "developer_id": {
          "type": "string"
        },
        "display_name": {
          "type": "string"
        },
        "contact_email": {
          "type": "string"
        },
        "company": {
          "type": "string",
          "nullable": true
        },
        "website": {
          "type": "string",
          "nullable": true
        },
        "status": {
          "type": "string"
        },
        "invite_verified_at": {
          "type": "string",
          "nullable": true
        },
        "metadata": {
          "type": "object"
        },
        "created_at": {
          "type": "string",
          "nullable": true
        },
        "updated_at": {
          "type": "string",
          "nullable": true
        }
      }
    },
    "developer_token": {
      "type": "string",
      "description": "Console session token for developer management endpoints."
    },
    "session": {
      "type": "object",
      "properties": {
        "session_id": {
          "type": "string"
        },
        "developer_id": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "expires_at": {
          "type": "string",
          "nullable": true
        },
        "created_at": {
          "type": "string",
          "nullable": true
        },
        "last_used_at": {
          "type": "string",
          "nullable": true
        }
      }
    },
    "invite_verified": {
      "type": "boolean"
    }
  }
}
400

Invalid login payload

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
401

Invalid email or password

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
POST /v1/developers/invite/verify 验证开发者邀请码 鉴权 详情

Requires a developer_token. API key creation is blocked until invite verification succeeds.

请求参数

无请求参数。

返回

状态码说明
200

Invite verified.

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "developer": {
      "type": "object",
      "properties": {
        "developer_id": {
          "type": "string"
        },
        "display_name": {
          "type": "string"
        },
        "contact_email": {
          "type": "string"
        },
        "company": {
          "type": "string",
          "nullable": true
        },
        "website": {
          "type": "string",
          "nullable": true
        },
        "status": {
          "type": "string"
        },
        "invite_verified_at": {
          "type": "string",
          "nullable": true
        },
        "metadata": {
          "type": "object"
        },
        "created_at": {
          "type": "string",
          "nullable": true
        },
        "updated_at": {
          "type": "string",
          "nullable": true
        }
      }
    },
    "invite_verified": {
      "type": "boolean"
    }
  }
}
401

Missing or invalid developer session token

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
403

Invalid invite code

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
PATCH /v1/developers/keys/{keyId} 修改 API Key 名称 鉴权 详情

Requires a developer_token from register or login. Updates the key label shown in the developer console.

请求参数

名称 位置 是否必填 类型 说明
keyId path 是 string —

返回

状态码说明
200

API key label updated.

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "key": {
      "type": "object",
      "properties": {
        "key_id": {
          "type": "string"
        },
        "developer_id": {
          "type": "string"
        },
        "key_prefix": {
          "type": "string"
        },
        "label": {
          "type": "string",
          "nullable": true
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "revoked",
            "deleted"
          ]
        },
        "last_used_at": {
          "type": "string",
          "nullable": true
        },
        "created_at": {
          "type": "string",
          "nullable": true
        },
        "revoked_at": {
          "type": "string",
          "nullable": true
        },
        "can_reveal": {
          "type": "boolean"
        }
      }
    }
  }
}
401

Missing or invalid developer session token

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
404

API key not found

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
DELETE /v1/developers/keys/{keyId} 删除 API Key 鉴权 详情

需要 developer_token。删除后的 key 会立即停止鉴权，但记录会保留用于审计和请求日志关联。

请求参数

名称 位置 是否必填 类型 说明
keyId path 是 string —

返回

状态码说明
200

API Key 已删除并保留审计记录。

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "key": {
      "type": "object",
      "properties": {
        "key_id": {
          "type": "string"
        },
        "developer_id": {
          "type": "string"
        },
        "key_prefix": {
          "type": "string"
        },
        "label": {
          "type": "string",
          "nullable": true
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "revoked",
            "deleted"
          ]
        },
        "last_used_at": {
          "type": "string",
          "nullable": true
        },
        "created_at": {
          "type": "string",
          "nullable": true
        },
        "revoked_at": {
          "type": "string",
          "nullable": true
        },
        "can_reveal": {
          "type": "boolean"
        }
      }
    }
  }
}
401

Missing or invalid developer session token

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
404

API key not found

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
POST /v1/developers/keys/{keyId}/reveal 获取完整 API Key 用于复制 鉴权 详情

Requires a developer_token from register or login. Returns the full API key for keys created after encrypted key storage was enabled.

请求参数

名称 位置 是否必填 类型 说明
keyId path 是 string —

返回

状态码说明
200

Full API key returned.

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "api_key": {
      "type": "string"
    },
    "key": {
      "type": "object",
      "properties": {
        "key_id": {
          "type": "string"
        },
        "developer_id": {
          "type": "string"
        },
        "key_prefix": {
          "type": "string"
        },
        "can_reveal": {
          "type": "boolean"
        },
        "label": {
          "type": "string",
          "nullable": true
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "revoked",
            "deleted"
          ]
        },
        "last_used_at": {
          "type": "string",
          "nullable": true
        },
        "created_at": {
          "type": "string",
          "nullable": true
        },
        "revoked_at": {
          "type": "string",
          "nullable": true
        }
      }
    }
  }
}
401

Missing or invalid developer session token

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
404

API key not found

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
410

Full key is unavailable for older hash-only keys

响应体结构 — application/json

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}

commerce-proof

Outcome-backed creator video assets that external agents can use as commerce proof for proposal generation.

GET /v1/proof-feed List commerce proof assets, including automated community proof 鉴权 详情

Returns outcome-backed shoppable video assets by default. Pass source=community to return query-scoped Reddit/community trust evidence with an automation plan; this avoids manual curation and avoids full Reddit crawling.

请求参数

名称 位置 是否必填 类型 说明
limit query 否 integer —
source query 否 string Use community/community-proof/reddit to return automated Community Proof assets.
intent query 否 string Shopping intent used to build scoped Reddit search import URLs.
products query 否 string Comma-separated product names used for exact product mention import.
subreddits query 否 string Comma-separated subreddit allowlist for bounded import; not recursive crawling.

返回

状态码说明
200

Commerce or community proof feed

响应体结构 — application/json

{
  "oneOf": [
    {
      "$ref": "#/components/schemas/CommerceProofFeedResponse"
    },
    {
      "$ref": "#/components/schemas/CommunityProofFeedResponse"
    }
  ]
}

billing

Billing and settlement previews.

POST /v1/billing/settlement-preview Preview merchant billing/settlement from attributed orders and accepted matches 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
X-Supply-Key header 是 string Supply/admin key for operational reporting and replay endpoints.

返回

状态码说明
200

Billing preview

400

Missing merchant id

401

Invalid or missing supply key

reconciliation

Order reconciliation controls.

POST /v1/reconciliation/tiktok-affiliate/run Run TikTok Affiliate order reconciliation 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
X-Supply-Key header 是 string Supply/admin key for operational reporting and replay endpoints.

返回

状态码说明
200

Reconciliation result

401

Invalid supply key

checkout

Payment/checkout authorization against MatchToken credentials.

POST /v1/match-tokens/{matchTokenId}/payment-authorization Authorize checkout/payment against a verified MatchToken 鉴权 详情

请求参数

名称 位置 是否必填 类型 说明
matchTokenId path 是 string —

返回

状态码说明
200

Payment is authorized

409

Token, proposal, amount, or acceptance state is not valid for payment

experience-commerce

POST /v1/decision-events Record a proposal/experience decision feedback event 鉴权 详情

请求参数

无请求参数。

返回

状态码说明
201

created

响应体结构 — application/json · DecisionEventResponse

{
  "type": "object",
  "properties": {
    "decision_event": {
      "type": "object",
      "properties": {
        "feedback_id": {
          "type": "string"
        },
        "event_type": {
          "type": "string"
        },
        "intent_id": {
          "type": "string",
          "nullable": true
        },
        "proposal_id": {
          "type": "string",
          "nullable": true
        },
        "match_token_id": {
          "type": "string",
          "nullable": true
        },
        "payload": {
          "type": "object"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    }
  }
}
400

unsupported_decision_event
POST /v1/experience-feed Prepare proactive ready-to-experience proposal shells 鉴权 详情

请求参数

无请求参数。

返回

状态码说明
200

OK

响应体结构 — application/json · ExperienceFeedResponse

{
  "type": "object",
  "properties": {
    "feed": {
      "type": "object",
      "properties": {
        "feed_id": {
          "type": "string"
        },
        "agent_id": {
          "type": "string"
        },
        "taste_profile": {
          "type": "object"
        },
        "inspiration_refs": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "items": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "generated_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}

commerce-runtime

POST /v1/commerce-runtime Run an auditable SellToAI Commerce Agent Runtime loop 鉴权 详情

请求参数

无请求参数。

返回

状态码说明
201

created

响应体结构 — application/json · CommerceRuntimeResponse

{
  "type": "object",
  "properties": {
    "runtime": {
      "type": "object",
      "properties": {
        "runtime_session": {
          "type": "object",
          "properties": {
            "runtime_id": {
              "$ref": "(max depth)"
            },
            "entry_agent_id": {
              "$ref": "(max depth)"
            },
            "mode": {
              "$ref": "(max depth)"
            },
            "stage": {
              "$ref": "(max depth)"
            },
            "started_at": {
              "$ref": "(max depth)"
            }
          }
        },
        "intent": {
          "type": "object",
          "properties": {
            "intent_id": {
              "$ref": "(max depth)"
            },
            "raw_query": {
              "$ref": "(max depth)"
            },
            "normalized_query": {
              "$ref": "(max depth)"
            },
            "intent_tags": {
              "$ref": "(max depth)"
            },
            "target_audience": {
              "$ref": "(max depth)"
            },
            "budget_range": {
              "$ref": "(max depth)"
            },
            "region": {
              "$ref": "(max depth)"
            },
            "constraints": {
              "$ref": "(max depth)"
            },
            "source_channel": {
              "$ref": "(max depth)"
            },
            "resolution_source": {
              "$ref": "(max depth)"
            },
            "resolution_summary": {
              "$ref": "(max depth)"
            },
            "metadata": {
              "$ref": "(max depth)"
            },
            "created_at": {
              "$ref": "(max depth)"
            },
            "updated_at": {
              "$ref": "(max depth)"
            },
            "time_window": {
              "$ref": "(max depth)"
            },
            "asset_refs": {
              "$ref": "(max depth)"
            },
            "attribution_chain": {
              "$ref": "(max depth)"
            },
            "workflow": {
              "$ref": "(max depth)"
            },
            "experience_context": {
              "$ref": "(max depth)"
            }
          }
        },
        "proposal": {
          "type": "object",
          "properties": {
            "proposal_id": {
              "$ref": "(max depth)"
            },
            "merchant_agent_id": {
              "$ref": "(max depth)"
            },
            "intent_id": {
              "$ref": "(max depth)"
            },
            "product_id": {
              "$ref": "(max depth)"
            },
            "offer_title": {
              "$ref": "(max depth)"
            },
            "price": {
              "$ref": "(max depth)"
            },
            "inventory_status": {
              "$ref": "(max depth)"
            },
            "shipping_commitment": {
              "$ref": "(max depth)"
            },
            "commission_plan": {
              "$ref": "(max depth)"
            },
            "service_terms": {
              "$ref": "(max depth)"
            },
            "evidence": {
              "$ref": "(max depth)"
            },
            "valid_until": {
              "$ref": "(max depth)"
            },
            "proposal_score_inputs": {
              "$ref": "(max depth)"
            },
            "product_snapshot": {
              "$ref": "(max depth)"
            },
            "metadata": {
              "$ref": "(max depth)"
            },
            "provenance": {
              "$ref": "(max depth)"
            },
            "status": {
              "$ref": "(max depth)"
            },
            "created_at": {
              "$ref": "(max depth)"
            },
            "updated_at": {
              "$ref": "(max depth)"
            },
            "asset_refs": {
              "$ref": "(max depth)"
            },
            "trust_score": {
              "$ref": "(max depth)"
            },
            "attribution_chain": {
              "$ref": "(max depth)"
            },
            "proposal_state": {
              "$ref": "(max depth)"
            },
            "workflow": {
              "$ref": "(max depth)"
            },
            "experience_preview": {
              "$ref": "(max depth)"
            },
            "experience_card": {
              "$ref": "(max depth)"
            }
          }
        },
        "match_session": {
          "type": "object",
          "properties": {
            "match_session_id": {
              "$ref": "(max depth)"
            },
            "intent_id": {
              "$ref": "(max depth)"
            },
            "best_proposal_id": {
              "$ref": "(max depth)"
            },
            "ranked_proposals": {
              "$ref": "(max depth)"
            },
            "summary": {
              "$ref": "(max depth)"
            },
            "status": {
              "$ref": "(max depth)"
            },
            "created_at": {
              "$ref": "(max depth)"
            },
            "updated_at": {
              "$ref": "(max depth)"
            }
          }
        },
        "match_token": {
          "type": "object",
          "properties": {
            "match_token_id": {
              "$ref": "(max depth)"
            },
            "match_session_id": {
              "$ref": "(max depth)"
            },
            "intent_id": {
              "$ref": "(max depth)"
            },
            "proposal_id": {
              "$ref": "(max depth)"
            },
            "acceptance_state": {
              "$ref": "(max depth)"
            },
            "intent_snapshot": {
              "$ref": "(max depth)"
            },
            "proposal_snapshot": {
              "$ref": "(max depth)"
            },
            "ranking_snapshot": {
              "$ref": "(max depth)"
            },
            "trace_ids": {
              "$ref": "(max depth)"
            },
            "issued_at": {
              "$ref": "(max depth)"
            },
            "expires_at": {
              "$ref": "(max depth)"
            },
            "accepted_at": {
              "$ref": "(max depth)"
            }
          }
        },
        "agent_steps": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/AgentStep"
          }
        },
        "commerce_budget": {
          "type": "object",
          "properties": {
            "max_agent_iterations": {
              "$ref": "(max depth)"
            },
            "max_merchant_queries": {
              "$ref": "(max depth)"
            },
            "max_proposal_versions": {
              "$ref": "(max depth)"
            },
            "require_user_confirmation_before_payment": {
              "$ref": "(max depth)"
            }
          }
        },
        "commerce_memory_refs": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/CommerceMemoryRef"
          }
        },
        "skill_refs": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "runtime_trace": {
          "type": "object",
          "properties": {
            "loop": {
              "$ref": "(max depth)"
            },
            "current_step": {
              "$ref": "(max depth)"
            },
            "audit_status": {
              "$ref": "(max depth)"
            }
          }
        }
      }
    }
  }
}
400

missing_intent

agentic-checkout

POST /v1/agentic-checkout Create an Agentic Checkout transaction plan 鉴权 详情

Turns a buyer-agent intent and merchant proposal into an auditable intent→proposal→MatchToken→confirmation transaction plan. This is the SellToAI Agentic Commerce path: optimize for trusted successful transactions, not ad impressions.

请求参数

无请求参数。

返回

状态码说明
201

Checkout created and waiting for explicit buyer confirmation

响应体结构 — application/json

{
  "type": "object"
}
400

Invalid checkout request
POST /v1/agentic-checkout/{checkoutId}/confirm Confirm an Agentic Checkout with MatchToken payment authorization 鉴权 详情

Requires explicit buyer-agent consent, accepts the signed MatchToken, verifies proposal/amount/currency, and returns a merchant handoff receipt plus audit trail.

请求参数

名称 位置 是否必填 类型 说明
checkoutId path 是 string —

返回

状态码说明
200

Checkout confirmed and authorized for payment or merchant handoff

响应体结构 — application/json

{
  "type": "object"
}
409

Consent, token, proposal, amount, or currency mismatch

Developer API Keys

生产环境下 API 调用设计为使用 `Authorization: Bearer <SellToAI API key>`，避免公开文档变成未认证的算力入口。

先注册开发者账号、完成邀请码验证，再在开发者控制台创建 API key。网关会保存用于鉴权的 hash，以及用于控制台复制的加密密文。

鉴权快速上手

  1. 用 `display_name`、`contact_email`、`password` 和基本公司信息注册账号，然后登录开发者控制台。
  2. 邀请码验证通过后才能创建 API key。只要加密密钥保持稳定，新 key 就可以在开发者控制台显示完整值并复制。
  3. 在 app、agent、MCP wrapper 或脚本调用 `/v1/*` 时，带上 `Authorization: Bearer MA2A.xxx`。
curl -H 'Authorization: Bearer MA2A.xxx' '/v1/recommend?intent=desk+lamp&limit=3'

只保存在当前浏览器 localStorage，用于渲染可复制的调用片段。

开发者 OpenAPI

Commerce Agent Registry

网关现在有通用外部 Agent 目录，覆盖 merchant、payment、logistics、creator、demand-side 和 SellToAI-core Agent。

当你需要比 legacy merchant registry 更完整的协议与能力元数据时，使用 `/v1/agents/register`、`/v1/agents/import-card`、list/fetch、heartbeat 和 deactivate 接口。

Registry 快速上手

  1. 注册时传 `agent_id`、`agent_type`、`endpoint`、支持协议、鉴权方式和 capability profile。
  2. 保存返回的 `registration_token`；后续 heartbeat 与生命周期更新用 `X-Agent-Token`。
  3. 需求侧 Agent 可通过 `GET /v1/agents?agent_type=...` 或 A2A/MCP discovery 工具发现可用 peer。
OpenAPI 打开接入指南

意图撮合与商家 Agent

SellToAI 现在已经暴露出 true A-to-A commerce 需要的核心对象：Intent、Proposal、Match Session、Match Token。

merchant 标签与下列协议说明的是当前在线的 v0.2 注册、分发、proposal 与 match-token 契约： 《意图撮合协议》v0.2. Merchant Registry、heartbeat、health check、proposal submission、match session 和 match token 都已经在网关中落地。

商家侧快速上手（v0.2）

  1. 先调用 `POST /v1/merchant/register`，传 `merchant_id`、`agent_endpoint` 和可选 tags / capabilities，并保存返回的 `registration_token`。
  2. 之后对 `POST /v1/merchant/heartbeat`、商家更新 / 停用，以及 `POST /v1/proposals` 都带上 `X-Merchant-Token`。
  3. 消费 `Intent.Surge` 或轮询 `/v1/intents`，提交 `/v1/proposals`，再由需求侧 Agent 调用 `/v1/match` 或 `/v1/recommend` 做排序与接受。
《意图撮合协议》v0.2 打开接入指南

Experience Commerce Protocol

Experience Commerce 在 intent/proposal/match 之上增加场景化上下文、预览资产、remix action 与决策反馈。

当前在线端点是 `/v1/decision-events` 与 `/v1/experience-feed`；OpenAPI schema 也会保留 `experience_context`、`experience_preview`、`experience_card` 快照。 《体验电商协议》.

体验链路快速上手

  1. 如果用户需要先可视化或确认是否适合，再创建 intent 时附带 `experience_context`。
  2. 提交 proposal 时附带 `experience_preview`；SellToAI 会为下游 Agent 合成 `experience_card`。
  3. 通过 `/v1/decision-events` 记录 pick/nope/remix/confirm，也可以用 `/v1/experience-feed` 生成 ready-to-experience proposal shells。
《体验电商协议》 打开接入指南

Commerce Runtime Layer

Runtime 端点会跑一次可审计的 SellToAI Commerce Agent Loop，并返回串联后的 Intent、Proposal、Match Session、Match Token、agent steps、budget、memory refs、skill refs 与 runtime trace。

当 Agent host 希望用一次交易形态调用完成链路，而不是手动拼多个对象时，使用 `POST /v1/commerce-runtime`；设计说明见： 《Commerce Runtime Layer》.

Runtime 快速上手

  1. 传入 `runtime_session`、`commerce_budget`、`commerce_memory_refs`、`skill_refs` 和正常的 `intent` payload 来启动 agent loop。
  2. 可以附带 `proposal` shell，提供 merchant/product 上下文；SellToAI 会补齐 runtime metadata 并创建关联的 match token。
  3. 需要审计和结算 traceability 时，可通过 A2A `run_commerce_runtime`、MCP `run_commerce_runtime` 或 REST 端点调用同一能力。
《Commerce Runtime Layer》 打开接入指南

A2A Agent Card

机器可读的 A2A 卡片（实时）：/.well-known/agent-card.json。请将 Agent 运行时的卡片地址指向此处，以便能力与网关保持一致。

打开 JSON 
加载中…

SKILL.md

面向 Agent 的 SellToAI Shop 技能说明；仓库中的 Markdown 源：/skills/moras-shop/SKILL.md。以下为中文摘要；安装与字段细节以源文件为准。

打开 Markdown

该技能让任意兼容的 Agent 调用 SellToAI 网关：获取推荐卡片（PCD）、按商品或记录标识拉取卡片，以及查看达人带货 showcase。

典型流程：在 Agent 的技能目录安装本包 → 配置网关基址与渠道名 → 通过自然语言触发 `recommend_products`，必要时再调用 `get_product_card`、`lookup_card` 或 `get_creator_showcase`。

与 OpenAPI、Agent Card 一起构成接入「三件套」：REST 契约、A2A 发现元数据、自然语言层面的操作说明。