{"openapi":"3.0.3","info":{"title":"Moras A2A 网关","version":"0.1.0","description":"根据自然语言意图推荐高转化的 TikTok Shop 商品，并附带 KOC 视频与带归因的购买链接；购买链接必须原样交给用户。\n\n在线试玩与接入说明：https://a2a.moras.ai/ — 可直接调试接口，并复制适用于各主流 Agent 客户端的现成片段。","contact":{"name":"Moras","url":"https://moras.ai"}},"servers":[{"url":"https://a2a.moras.ai","description":"生产"}],"tags":[{"name":"recommend","description":"发现类接口：公开、免费；可附带渠道请求头。"},{"name":"card","description":"获取或查询已生成的 PCD（商品种草卡）。"},{"name":"creator","description":"浏览创作者带货橱窗。"},{"name":"intent","description":"一等 Intent 对象：把自然语言需求变成可继续撮合的标准输入。"},{"name":"proposal","description":"商家侧 Proposal：围绕某个 Intent 返回结构化报价与履约信息。"},{"name":"match","description":"围绕 Intent + Proposal 生成 Match Session 与 Match Token。"},{"name":"merchant","description":"商家 / 供给侧 Agent 入驻与生命周期接口（持久化注册）。"},{"name":"report","description":"供给方 ROI 报表（需 X-Supply-Key）。"}],"paths":{"/v1/recommend":{"get":{"tags":["recommend"],"summary":"按自然语言意图推荐商品卡","operationId":"recommendProducts","parameters":[{"name":"intent","in":"query","required":true,"schema":{"type":"string"},"description":"用户自然语言意图，例如「给 3 岁侄子买的礼物」。"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":3}},{"name":"region","in":"query","required":false,"schema":{"type":"string"},"description":"国家或地区 ISO 代码（如 US、UK）。"},{"name":"channel","in":"query","required":false,"schema":{"type":"string"},"description":"渠道提示（openclaw、cursor、gemini、chatgpt、hermes 等）。"}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendResponse"}}}},"503":{"description":"意图引擎不可用：网关上需配置 GOOGLE_API_KEY 或 GEMINI_API_KEY；意图仅由 Gemini 实时解析。","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"intent_engine_unavailable"},"message":{"type":"string"}}}}}}}}},"/v1/cards/{recId}":{"get":{"tags":["card"],"summary":"按 recId 查询已生成的 PCD","operationId":"getCardByRecId","parameters":[{"name":"recId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PCD"}}}},"404":{"description":"未找到"}}}},"/v1/products/{productId}/card":{"get":{"tags":["card"],"summary":"按已知商品 ID 生成新的 PCD","operationId":"buildCardForProduct","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PCD"}}}}}}},"/v1/creators/{username}/showcase":{"get":{"tags":["creator"],"summary":"该创作者下表现突出的带货商品","operationId":"getCreatorShowcase","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":10,"default":6}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowcaseResponse"}}}}}}},"/v1/merchant/register":{"post":{"tags":["merchant"],"summary":"注册商家 Agent（意图撮合 v0.2）","description":"登记 webhook 与订阅标签、能力声明与区域范围。当前注册已持久化，支持心跳、健康检查、Proposal 提交与 Intent.Surge 分发。规范见本网关 /docs/INTENT_MATCHING_PROTOCOL.md。","operationId":"registerMerchantAgent","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantRegisterRequest"},"example":{"merchant_id":"mch_001","agent_endpoint":"https://agent.merchant.com/webhook","subscription_tags":["camping","outdoor"],"capabilities":["stock_check","price_quote"]}}}},"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantRegisterResponse"}}}},"400":{"description":"缺少必填字段"}}}},"/v1/merchant/{merchantId}":{"get":{"tags":["merchant"],"summary":"按 merchant_id 查询注册中的商家 Agent","operationId":"getMerchantAgent","parameters":[{"name":"merchantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantLookupResponse"}}}},"404":{"description":"merchant_not_found"}}}},"/v1/merchant/{merchantId}/health":{"get":{"tags":["merchant"],"summary":"探测商家 Agent 健康状态","operationId":"probeMerchantAgentHealth","parameters":[{"name":"merchantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"merchant healthy"},"503":{"description":"merchant unhealthy or unreachable"}}}},"/v1/merchant/heartbeat":{"post":{"tags":["merchant"],"summary":"商家 Agent 心跳","operationId":"heartbeatMerchantAgent","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["merchant_id"],"properties":{"merchant_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantLookupResponse"}}}},"401":{"description":"missing registration token"},"403":{"description":"invalid registration token"}}}},"/v1/merchant/{merchantId}/deactivate":{"post":{"tags":["merchant"],"summary":"停用商家 Agent","operationId":"deactivateMerchantAgent","parameters":[{"name":"merchantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantLookupResponse"}}}},"401":{"description":"missing registration token"},"403":{"description":"invalid registration token"}}}},"/v1/intent-mandates/sign":{"post":{"tags":["intent"],"summary":"签发电商意图凭证（RSA-SHA256；需网关配置私钥）","description":"Returns a signed Intent Mandate for checkout flows. Requires MORAS_PRIVATE_KEY (RSA PEM) on the gateway; returns 503 if unset.","operationId":"signIntentMandate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product_id","amount_limit"],"properties":{"product_id":{"type":"string"},"amount_limit":{"type":"number","exclusiveMinimum":0}}}}}},"responses":{"201":{"description":"Signed mandate","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_body"},"503":{"description":"MORAS_PRIVATE_KEY not configured"}}}},"/v1/intents":{"post":{"tags":["intent"],"summary":"创建一等 Intent","operationId":"createIntent","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentCreateRequest"}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentResponse"}}}},"400":{"description":"missing_fields"}}}},"/v1/intents/{intentId}":{"get":{"tags":["intent"],"summary":"按 intent_id 查询 Intent","operationId":"getIntent","parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentResponse"}}}},"404":{"description":"intent_not_found"}}}},"/v1/intents/{intentId}/proposals":{"get":{"tags":["intent"],"summary":"列出某个 Intent 下的 Proposal","operationId":"listIntentProposals","parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"include_expired","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentProposalListResponse"}}}},"404":{"description":"intent_not_found"}}}},"/v1/proposals":{"post":{"tags":["proposal"],"summary":"提交 Merchant Proposal","operationId":"createProposal","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalCreateRequest"}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalResponse"}}}},"401":{"description":"missing registration token"},"403":{"description":"invalid registration token"},"404":{"description":"intent_not_found or merchant_not_found"}}}},"/v1/proposals/{proposalId}":{"get":{"tags":["proposal"],"summary":"按 proposal_id 查询 Proposal","operationId":"getProposal","parameters":[{"name":"proposalId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalResponse"}}}},"404":{"description":"proposal_not_found"}}}},"/v1/match":{"post":{"tags":["match"],"summary":"基于 Intent 与 Proposal 创建 Match Session","operationId":"createMatchSession","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchCreateRequest"}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchSessionResponse"}}}},"400":{"description":"missing_fields"},"404":{"description":"intent_not_found or proposal_not_found"}}}},"/v1/match/{matchSessionId}":{"get":{"tags":["match"],"summary":"获取渲染后的 Match Session","operationId":"getMatchSession","parameters":[{"name":"matchSessionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchRenderedResponse"}}}},"404":{"description":"match_not_found"}}}},"/v1/match/{matchSessionId}/accept":{"post":{"tags":["match"],"summary":"接受 Proposal 并铸造 / 确认 Match Token","operationId":"acceptMatch","parameters":[{"name":"matchSessionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"proposal_id":{"type":"string"},"match_token_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchTokenResponse"}}}},"404":{"description":"match_not_found"}}}},"/v1/match-tokens/{matchTokenId}":{"get":{"tags":["match"],"summary":"按 id 查询 Match Token","operationId":"getMatchToken","parameters":[{"name":"matchTokenId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchTokenResponse"}}}},"404":{"description":"match_token_not_found"}}}},"/v1/report/attribution":{"get":{"tags":["report"],"summary":"ROI 报表（供给方，需 X-Supply-Key）","operationId":"getAttributionReport","security":[{"supplyKey":[]}],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30}},{"name":"channel","in":"query","schema":{"type":"string"}},{"name":"product_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"401":{"description":"未授权"}}}}},"components":{"securitySchemes":{"supplyKey":{"type":"apiKey","in":"header","name":"X-Supply-Key"}},"schemas":{"MerchantRegisterRequest":{"type":"object","required":["merchant_id","agent_endpoint"],"properties":{"merchant_id":{"type":"string","description":"Stable merchant / tenant id"},"agent_endpoint":{"type":"string","description":"HTTPS webhook URL for your Agent"},"subscription_tags":{"type":"array","items":{"type":"string"},"description":"Intent tags to subscribe to"},"capabilities":{"type":"array","items":{"type":"string"},"description":"e.g. stock_check, price_quote"}}},"MerchantRegisterResponse":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"created":{"type":"boolean"},"merchant_id":{"type":"string"},"registration_token":{"type":"string","description":"Secret token used for heartbeat, updates, deactivation, and proposal submission."},"merchant":{"$ref":"#/components/schemas/MerchantAgent"}}},"MerchantLookupResponse":{"type":"object","properties":{"status":{"type":"string","nullable":true},"merchant":{"$ref":"#/components/schemas/MerchantAgent"}}},"MerchantAgent":{"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}}},"IntentCreateRequest":{"type":"object","required":["raw_query"],"properties":{"raw_query":{"type":"string"},"region":{"type":"string","nullable":true},"audience":{"type":"string","nullable":true},"budget_range":{"type":"object","properties":{"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true}}},"constraints":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"object"},{"type":"string"}]}}},"IntentObject":{"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}}},"IntentResponse":{"type":"object","properties":{"intent":{"$ref":"#/components/schemas/IntentObject"}}},"ProposalCreateRequest":{"type":"object","required":["merchant_agent_id","intent_id","product_id"],"properties":{"merchant_agent_id":{"type":"string"},"intent_id":{"type":"string"},"product_id":{"type":"string"},"offer_title":{"type":"string","nullable":true},"price":{"type":"number","nullable":true},"inventory_status":{"type":"string","nullable":true},"shipping_commitment":{"type":"object","nullable":true},"commission_plan":{"type":"object","nullable":true},"service_terms":{"type":"object","nullable":true},"evidence":{"type":"array","items":{"type":"object"}},"valid_until":{"type":"string","format":"date-time","nullable":true},"product_snapshot":{"type":"object","nullable":true},"metadata":{"type":"object","nullable":true}}},"ProposalObject":{"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}}},"ProposalResponse":{"type":"object","properties":{"proposal":{"$ref":"#/components/schemas/ProposalObject"}}},"IntentProposalListResponse":{"type":"object","properties":{"intent_id":{"type":"string"},"count":{"type":"integer"},"proposals":{"type":"array","items":{"$ref":"#/components/schemas/ProposalObject"}}}},"MatchCreateRequest":{"type":"object","required":["intent_id"],"properties":{"intent_id":{"type":"string"},"proposal_ids":{"type":"array","items":{"type":"string"}},"limit":{"type":"integer","minimum":1,"maximum":10,"default":3}}},"MatchSessionObject":{"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}}},"MatchTokenObject":{"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}}},"MatchSessionResponse":{"type":"object","properties":{"match_session":{"$ref":"#/components/schemas/MatchSessionObject"}}},"MatchRenderedResponse":{"type":"object","properties":{"match_session":{"$ref":"#/components/schemas/MatchSessionObject"},"ranked_proposals":{"type":"array","items":{"type":"object"}},"match_tokens":{"type":"array","items":{"$ref":"#/components/schemas/MatchTokenObject"}},"items":{"type":"array","items":{"$ref":"#/components/schemas/PCD"}}}},"MatchTokenResponse":{"type":"object","properties":{"match_token":{"$ref":"#/components/schemas/MatchTokenObject"}}},"RecommendResponse":{"type":"object","properties":{"intent":{"type":"string"},"intent_id":{"type":"string"},"count":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PCD"}},"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","nullable":true,"description":"Optional machine hint e.g. intent_plus_trending, trending_suggested."},"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"}}},"ShowcaseResponse":{"type":"object","properties":{"username":{"type":"string"},"count":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PCD"}}}},"PCD":{"type":"object","description":"商品种草卡（PCD）— 推荐与归因的最小单元。","required":["rec_id","product","hero_pitch","selection_story","videos","cta","generated_at"],"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":"#/components/schemas/KocVideo"}},"cta":{"$ref":"#/components/schemas/Cta"},"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}}},"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}}},"HeroPitch":{"type":"object","properties":{"one_liner":{"type":"string"},"why_it_wins_on_tiktok":{"type":"string"},"key_benefits":{"type":"array","items":{"type":"object","properties":{"icon":{"type":"string"},"title":{"type":"string"},"desc":{"type":"string"}}}},"target_audience":{"type":"object","properties":{"persona":{"type":"string"},"age":{"type":"string"},"region":{"type":"array","items":{"type":"string"}}}}}},"SelectionStory":{"type":"object","properties":{"headline":{"type":"string"},"bullets":{"type":"array","items":{"type":"string"}},"moras_score":{"type":"number"}}},"KocVideo":{"type":"object","properties":{"task_id":{"type":"string"},"creator":{"type":"object","properties":{"username":{"type":"string"},"display_name":{"type":"string"},"avatar":{"type":"string","nullable":true},"followers":{"type":"integer"}}},"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"}}}}}}}}