MorasA2A

文档与契约

API 参考

面向任意 Agent 的三份事实源：REST/OpenAPI、实时 A2A Agent Card、Skill 包。协议核心是 Intent、Proposal、Match Session、Match Token；PCD 只是展示工件。

本页内容怎么用

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

  1. OpenAPI：可以从 `GET /v1/recommend` 快速接入，也可以继续接 `/v1/intents`、`/v1/proposals`、`/v1/match`、`/v1/match-tokens`。现成片段在「接入指南 /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

Moras A2A 网关

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

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

OpenAPI 3.0.3 · v0.1.0

recommend

发现类接口：公开、免费；可附带渠道请求头。

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

意图引擎不可用：网关上需配置 GOOGLE_API_KEY 或 GEMINI_API_KEY；意图仅由 Gemini 实时解析。

响应体结构 — 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 签发电商意图凭证（RSA-SHA256；需网关配置私钥） 详情

Returns a signed Intent Mandate for checkout flows. Requires MORAS_PRIVATE_KEY (RSA PEM) on the gateway; returns 503 if unset.

请求参数

无请求参数。

返回

状态码说明
201

Signed mandate

响应体结构 — application/json

{
  "type": "object"
}
400

invalid_body

503

MORAS_PRIVATE_KEY not configured
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
        }
      }
    }
  }
}
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
        }
      }
    }
  }
}
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
          }
        }
      }
    }
  }
}
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
        }
      }
    }
  }
}
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
        }
      }
    }
  }
}
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
        }
      }
    }
  }
}
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
        }
      }
    }
  }
}
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
        }
      }
    }
  }
}
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
        }
      }
    }
  }
}
401

missing registration token

403

invalid registration token

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

未授权

意图撮合与商家 Agent

Moras 现在已经暴露出 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 打开接入指南

A2A Agent Card

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

打开 JSON 
加载中…

SKILL.md

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

打开 Markdown

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

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

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