{"id":"9aa706d3-262c-4843-8a79-a95897caa94d","entityType":"agent","slug":"clawhub-linkfox-ai-linkfox-temu-ads-us","name":"Temu美国站-广告","canonicalUrl":"https://www.xpersona.co/agent/clawhub-linkfox-ai-linkfox-temu-ads-us","canonicalPath":"/agent/clawhub-linkfox-ai-linkfox-temu-ads-us","generatedAt":"2026-10-10T21:52:15.857Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:45:17.635Z","emptyReason":null},"description":"Temu 美国站电商广告 Ads API，经 LinkFox 网关转发 Partner US Ads / 广告投放 相关 bg/temu 接口（广告计划、广告组、创意、报表、预算出价等，接口将按 Partner 文档逐条接入）。当用户提到 Temu US 广告、Ads、广告投放、广告计划、广告组、创意、出价、预算、广告报表、ad campaign、product-inventory 广告 时触发。商品管理用 linkfox-temu-manage-product-us；促销用 linkfox-temu-promotion-us；订单用 linkfox-temu-order-us。","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.3K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-temu-ads-us","sourceUrl":"https://clawhub.ai/linkfox-ai/linkfox-temu-ads-us","homepage":"https://clawhub.ai/linkfox-ai/skills/linkfox-temu-ads-us","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/linkfox-ai/linkfox-temu-ads-us","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/linkfox-ai/skills/linkfox-temu-ads-us","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":63,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Temu美国站-广告 technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:45:17.635Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:45:17.635Z","emptyReason":null},"stars":null,"forks":null,"downloads":1333,"packageName":null,"latestVersion":"1.0.6","tractionLabel":"1.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:45:17.635Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T16:45:17.635Z","lastCrawledAt":"2026-10-10T16:45:17.635Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T16:45:17.635Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.6","createdAt":"2026-08-14T15:12:02.359Z","changelog":"Update from 1.0.5 to 1.0.6","fileCount":38,"zipByteSize":55628},{"version":"1.0.5","createdAt":"2026-08-07T11:12:34.761Z","changelog":"Update from 1.0.4 to 1.0.5","fileCount":38,"zipByteSize":55344},{"version":"1.0.4","createdAt":"2026-07-13T12:29:43.938Z","changelog":"Update from 1.0.3 to 1.0.4","fileCount":36,"zipByteSize":46504},{"version":"1.0.3","createdAt":"2026-07-06T11:38:18.715Z","changelog":"Update from 1.0.2 to 1.0.3","fileCount":36,"zipByteSize":45945},{"version":"1.0.2","createdAt":"2026-07-03T09:38:03.076Z","changelog":"Update from 1.0.0 to 1.0.2","fileCount":35,"zipByteSize":44216},{"version":"1.0.0","createdAt":"2026-05-27T05:24:39.577Z","changelog":"Initial release","fileCount":36,"zipByteSize":42911}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-temu-ads-us","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-temu-ads-us` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/linkfox-ai/linkfox-temu-ads-us before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-temu-ads-us/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-temu-ads-us/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-temu-ads-us/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-temu-ads-us/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-temu-ads-us/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-temu-ads-us/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T21:52:15.854Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-temu-ads-us/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-temu-ads-us/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-temu-ads-us/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-temu-ads-us/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:45:17.635Z","emptyReason":null},"readme":"Skill: Temu美国站-广告\n\nOwner: linkfox-ai\n\nSummary: Temu 美国站电商广告 Ads API，经 LinkFox 网关转发 Partner US Ads / 广告投放 相关 bg/temu 接口（广告计划、广告组、创意、报表、预算出价等，接口将按 Partner 文档逐条接入）。当用户提到 Temu US 广告、Ads、广告投放、广告计划、广告组、创意、出价、预算、广告报表、ad campaign、product-inventory 广告 时触发。商品管理用 linkfox-temu-manage-product-us；促销用 linkfox-temu-promotion-us；订单用 linkfox-temu-order-us。\n\nTags: latest:1.0.6\n\nVersion history:\n\nv1.0.6 | 2026-08-14T15:12:02.359Z | user\n\nUpdate from 1.0.5 to 1.0.6\n\nv1.0.5 | 2026-08-07T11:12:34.761Z | user\n\nUpdate from 1.0.4 to 1.0.5\n\nv1.0.4 | 2026-07-13T12:29:43.938Z | user\n\nUpdate from 1.0.3 to 1.0.4\n\nv1.0.3 | 2026-07-06T11:38:18.715Z | user\n\nUpdate from 1.0.2 to 1.0.3\n\nv1.0.2 | 2026-07-03T09:38:03.076Z | user\n\nUpdate from 1.0.0 to 1.0.2\n\nv1.0.0 | 2026-05-27T05:24:39.577Z | user\n\nInitial release\n\nArchive index:\n\nArchive v1.0.6: 38 files, 55628 bytes\n\nFiles: references/access-token.md (4527b), references/api.md (5161b), references/apis/README.md (1301b), references/apis/temu-searchrec-ad-create.md (4617b), references/apis/temu-searchrec-ad-detail-query.md (5249b), references/apis/temu-searchrec-ad-goods-create-query.md (3518b), references/apis/temu-searchrec-ad-log-query.md (3811b), references/apis/temu-searchrec-ad-modify.md (4203b), references/apis/temu-searchrec-ad-reports-mall-query.md (6156b), references/apis/temu-searchrec-ad-roas-pred.md (3687b), references/authorization-flow.md (1186b), references/onboarding.md (2046b), references/partner-us-catalog.md (3173b), scripts/_temu_auth_guide.py (6198b), scripts/_temu_common.py (12422b), scripts/_temu_token_store.py (4273b), scripts/_temu_us_common.py (3162b), scripts/_us_ads_script.py (510b), scripts/check_linkfox_token.py (1798b), scripts/get_temu_access_token.py (1843b), scripts/list_temu_access_tokens.py (652b), scripts/onboarding.py (24089b), scripts/save_temu_access_token.py (1377b), scripts/temu_file_download.py (1681b), scripts/temu_proxy.py (2124b), scripts/temu_token_guide.py (1594b), scripts/temu_us_file_download.py (708b), scripts/temu_us_proxy.py (923b), scripts/us_ads_searchrec_ad_create.py (234b), scripts/us_ads_searchrec_ad_detail_query.py (258b), scripts/us_ads_searchrec_ad_goods_create_query.py (285b), scripts/us_ads_searchrec_ad_log_query.py (255b), scripts/us_ads_searchrec_ad_modify.py (234b), scripts/us_ads_searchrec_ad_reports_mall_query.py (282b), scripts/us_ads_searchrec_ad_roas_pred.py (249b), skill-card.md (4137b), SKILL.md (6094b), _meta.json (138b)\n\nFile v1.0.6:SKILL.md\n\n---\nname: linkfox-temu-ads-us\ndescription: Temu 美国站电商广告 Ads API，经 LinkFox 网关转发 Partner US Ads / 广告投放 相关 bg/temu 接口（广告计划、广告组、创意、报表、预算出价等，接口将按 Partner 文档逐条接入）。当用户提到 Temu US 广告、Ads、广告投放、广告计划、广告组、创意、出价、预算、广告报表、ad campaign、product-inventory 广告 时触发。商品管理用 linkfox-temu-manage-product-us；促销用 linkfox-temu-promotion-us；订单用 linkfox-temu-order-us。\n---\n\n# Temu 美国站 — 电商广告（Ads）\n\n本 skill（`linkfox-temu-ads-us`）覆盖 Partner Platform for US **Ads / 电商广告**（广告计划、投放、报表等；`menu_code` 与各 `sub_menu_code` 以 Partner 后台为准，见 [partner-us-catalog.md](./references/partner-us-catalog.md)）。\n\n已接入 **7** 条 Partner **Ads**（`temu.searchrec.ad.*`）接口，清单见 [partner-us-catalog.md](./references/partner-us-catalog.md)。\n\n**网关（本 skill 内置）**：\n\n| 能力 | 方法 | 路径 |\n|------|------|------|\n| 广告 OpenAPI（`us_ads_*`、`temu_us_proxy`） | POST | `https://tool-gateway.linkfox.com/temu/proxy` |\n| 加签文件下载 | POST | `https://tool-gateway.linkfox.com/temu/fileDownload` |\n\n## 相关 skill\n\n| 场景 | skill |\n|------|--------|\n| **广告 Ads**（本 skill） | **`linkfox-temu-ads-us`** |\n| 商品列表/详情/编辑/库存/上下架 | `linkfox-temu-manage-product-us` |\n| 促销/营销活动 | `linkfox-temu-promotion-us` |\n| 发品 | `linkfox-temu-add-product-us` |\n| 价格/供货价、定价单 | `linkfox-temu-price-us` |\n| 订单列表/详情 | `linkfox-temu-order-us` |\n| 退货与退款 | `linkfox-temu-returns-refunds-us` |\n| 网关与 Temu token | 本 skill `scripts/` |\n\n## 调用方式\n\n- **API 端点**：`POST /temu/proxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '<JSON 参数>' [--inline]`（可用脚本见上文脚本一览）\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-temu-ads-us-<timestamp>.json`（`<cwd>` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n## 默认参数\n\n| 字段 | 默认 | 说明 |\n|------|------|------|\n| site | `us` | Partner US |\n| managementType | `semi-managed` | 半托管（具体接口以 Partner 文档为准） |\n| tokenPurpose | `product-inventory` | 卖家助手默认（若 Partner 某 Ads 接口要求其他 `tokenPurpose`，以该接口文档为准） |\n\n## 鉴权\n\n1. **LinkFox**：`LINKFOXAGENT_API_KEY` → Header `Authorization` + `Token`\n2. **Temu**：`accessToken` 或 `storeKey`（`storeKey` 时建议带 `tokenPurpose=product-inventory`）\n\n## Scripts\n\n| 脚本 | 说明 |\n|------|------|\n| `temu_us_proxy.py` | 任意 type |\n| `temu_us_file_download.py` | 加签下载 |\n| `us_ads_searchrec_ad_roas_pred.py` | `temu.searchrec.ad.roas.pred` |\n| `us_ads_searchrec_ad_reports_mall_query.py` | `temu.searchrec.ad.reports.mall.query` |\n| `us_ads_searchrec_ad_create.py` | `temu.searchrec.ad.create` |\n| `us_ads_searchrec_ad_detail_query.py` | `temu.searchrec.ad.detail.query` |\n| `us_ads_searchrec_ad_log_query.py` | `temu.searchrec.ad.log.query` |\n| `us_ads_searchrec_ad_goods_create_query.py` | `temu.searchrec.ad.goods.create.query` |\n| `us_ads_searchrec_ad_modify.py` | `temu.searchrec.ad.modify` |\n\n## 接入新接口（约定）\n\n你每提供一条 Partner 文档（`type` + `sub_menu_code` + URL + Request/Response 参数表），将：\n\n1. 新增 `references/apis/<type-slug>.md`（完整入参/出参层级）\n2. 新增 `scripts/us_ads_<slug>.py`（调用 `_us_ads_script.run_cli`）\n3. 更新 [partner-us-catalog.md](./references/partner-us-catalog.md)、[apis/README.md](./references/apis/README.md) 与本表\n\n## 示例（通用代理）\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\n\npython scripts/temu_us_proxy.py '{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"type\": \"<TEMU_API_TYPE>\",\n  \"params\": {\n    \"request\": {}\n  }\n}'\n```\n\n**Feedback：** `skillName`：`linkfox-temu-ads-us`\n\n## 网关与授权脚本\n\n| 脚本 | 说明 |\n|------|------|\n| `check_linkfox_token.py` | 校验 LinkFox 用户 Token |\n| `temu_token_guide.py` | Temu accessToken 后台授权步骤 |\n| `save_temu_access_token.py` | 保存 accessToken 到本地 |\n| `list_temu_access_tokens.py` | 列出已保存 token |\n| `get_temu_access_token.py` | 读取已保存 token |\n| `temu_proxy.py` | 通用网关转发（多 site） |\n| `temu_file_download.py` | 加签文件下载（多 site） |\n\n授权说明：[references/access-token.md](./references/access-token.md)\n\n## 积分消耗规则\n\n不消耗积分。\n\nFile v1.0.6:references/apis/README.md\n\n# Ads — 接口文档索引\n\n网关见 [../api.md](../api.md)；目录见 [../partner-us-catalog.md](../partner-us-catalog.md)。\n\n## 查询 / 预测\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.roas.pred` | 广告 ROAS 预测 | [temu-searchrec-ad-roas-pred.md](./apis/temu-searchrec-ad-roas-pred.md) |\n| `temu.searchrec.ad.goods.create.query` | 广告可创建商品查询 | [temu-searchrec-ad-goods-create-query.md](./apis/temu-searchrec-ad-goods-create-query.md) |\n\n## 创建 / 修改\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.create` | 创建广告 | [temu-searchrec-ad-create.md](./apis/temu-searchrec-ad-create.md) |\n| `temu.searchrec.ad.modify` | 修改广告 | [temu-searchrec-ad-modify.md](./apis/temu-searchrec-ad-modify.md) |\n\n## 报表 / 日志\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.reports.mall.query` | 店铺广告报表查询 | [temu-searchrec-ad-reports-mall-query.md](./apis/temu-searchrec-ad-reports-mall-query.md) |\n| `temu.searchrec.ad.detail.query` | 广告详情查询 | [temu-searchrec-ad-detail-query.md](./apis/temu-searchrec-ad-detail-query.md) |\n| `temu.searchrec.ad.log.query` | 广告操作日志查询 | [temu-searchrec-ad-log-query.md](./apis/temu-searchrec-ad-log-query.md) |\n\nFile v1.0.6:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-temu-ads-us\",\n  \"version\": \"1.0.6\",\n  \"publishedAt\": 1786720322359\n}\n\nFile v1.0.6:references/access-token.md\n\n# Temu accessToken 授权与获取\n\nTemu **没有** LinkFox 侧自动 OAuth；`accessToken` 须在 Temu 卖家后台「服务市场 → 授权管理」**手动复制**。与 `LINKFOXAGENT_API_KEY`（LinkFox 用户鉴权）是两套令牌。\n\n## 两种鉴权（勿混淆）\n\n| 令牌 | 用途 | 获取方式 |\n|------|------|----------|\n| **LinkFox 用户 Token** | 调用 `/temu/proxy`、`/temu/fileDownload` **必填** | `LINKFOXAGENT_API_KEY` 或请求 JSON 的 `token`；Header `Authorization` + `Token`（同 amazon-store-auth）（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理） |\n| **Temu accessToken** | Temu 业务 API（经紫鸟转发） | Temu 卖家后台授权后复制 |\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<your-key>\"\npython scripts/check_linkfox_token.py\n```\n\n## tokenPurpose 与场景\n\n| tokenPurpose | 店铺类型 | 推荐 site | 授权应用 |\n|--------------|----------|-----------|----------|\n| `product-inventory` | 半托管 | `cn` / `partner` | 酷鸟卖家助手 |\n| `order-shipping` | 半托管 | `us` / `global` / `eu` | Cyber-ERP酷鸟助手 |\n| `full-managed` | 全托管 | `cn` / `partner` | 酷鸟卖家助手 |\n| `local-native` | 本土（美/欧主体） | `us` 等 | Cyber-ERP |\n\n## 1. 半托管 — 商品/库存 Token\n\n1. 登录 [seller.kuajingmaihuo.com](https://seller.kuajingmaihuo.com) 或 [agentseller.temu.com](https://agentseller.temu.com)\n2. **系统管理** → **服务市场** → **授权管理**\n3. **获取授权** → 选择 **「酷鸟卖家助手」**\n4. 全选常规和特殊授权 → 确认 → **复制 access_token**\n5. 调用 API：`site=cn` 或 `partner`，`managementType=semi-managed`\n\n## 2. 半托管 — 订单/发货 Token\n\n1. 登录 Temu 卖家后台\n2. 右上角 **Seller Central** → 切换到目标区域（美区 / 欧区 / 全球）\n3. **服务市场** → **授权管理**\n4. **获取授权** → 选择 **「Cyber-ERP酷鸟助手」**\n5. 全选授权 → 确认 → 复制 token\n6. 调用 API：`site=us` / `global` / `eu`，`managementType=semi-managed`\n\n## 3. 全托管店铺\n\n1. 登录 Temu 平台\n2. **系统管理** → **服务市场** → **授权管理**\n3. **获取授权** → **「酷鸟卖家助手」** → 全选 → 复制 token\n4. 调用 API：`managementType=full-managed`，`site` 通常 `cn` 或 `partner`\n\n## 4. 本土店铺（美区、欧区主体）\n\n1. 登录 Temu\n2. **Apps And Services** → **Manage Your Apps**\n3. **Authorize a new app** → 搜索 **「Cyber-ERP」**\n4. 一般权限与敏感权限全选 → 确认 → 复制 token\n\n## 站点与 OpenAPI 网关\n\n| site | 说明 | Temu 网关 |\n|------|------|-----------|\n| cn | 中国站 | openapi.kuajingmaihuo.com |\n| partner | Partner 网关 | openapi-b-partner.temu.com |\n| us | 美国站 | openapi-b-us.temu.com |\n| global | 全球区 | openapi-b-global.temu.com |\n| eu | 欧洲站 | openapi-b-eu.temu.com |\n\n## 本地保存 Token（推荐）\n\n默认存储：`~/.linkfox/temu-access-tokens.json`（可用 `TEMU_TOKEN_STORE_PATH` 覆盖）。\n\n```bash\n# 查看授权步骤\npython scripts/temu_token_guide.py '{\"shopType\":\"semi-managed\",\"tokenPurpose\":\"product-inventory\",\"site\":\"cn\"}'\n\n# 保存 token\npython scripts/save_temu_access_token.py '{\n  \"storeKey\": \"my-shop\",\n  \"label\": \"中国半托管\",\n  \"site\": \"cn\",\n  \"managementType\": \"semi-managed\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"accessToken\": \"PASTE_TOKEN\"\n}'\n\n# 列出已保存（脱敏）\npython scripts/list_temu_access_tokens.py\n\n# 用 storeKey 调 API（无需每次粘贴 token）\npython scripts/temu_proxy.py '{\n  \"storeKey\": \"my-shop\",\n  \"site\": \"cn\",\n  \"managementType\": \"semi-managed\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"type\": \"bg.goods.category.mapping\",\n  \"params\": {\"goodsName\": \"测试\", \"goodsNameEn\": \"Test\"}\n}'\n```\n\n## 注意事项\n\n1. **子账号**：可能无法进入服务市场，需主账号授权。\n2. **多站点**：美国站、英国站等需分别登录对应后台获取 Token。\n3. **有效期**：Token 会过期，过期后重新在后台复制并 `save_temu_access_token.py`。\n4. **IP 白名单**：需联系紫鸟开放平台配置调用 IP。\n5. **参数小写**：`site`、`managementType` 必须小写。\n\n## 脚本一览\n\n| 脚本 | 说明 |\n|------|------|\n| `temu_token_guide.py` | 按店铺类型/用途输出授权步骤 |\n| `save_temu_access_token.py` | 保存 accessToken 到本地 |\n| `list_temu_access_tokens.py` | 列出已保存 token（默认脱敏）|\n| `get_temu_access_token.py` | 读取指定 store 的 token |\n\nFile v1.0.6:references/api.md\n\n# linkfox-temu-ads-us — API 参考\r\n\r\nTemu **美国站电商广告（Ads）**，经本 skill `temu_us_proxy`（`POST /temu/proxy`） 转发。Temu 的 `type` 写在 Body，**不是** URL 路径。\r\n\r\n> 网关与鉴权：本 skill `scripts/`（`LINKFOXAGENT_API_KEY`、`accessToken` / `storeKey`）。授权见 `references/access-token.md`。\r\n\r\n---\r\n\r\n## 调用规范\r\n\r\n| 项 | 说明 |\r\n|----|------|\r\n| 网关根地址 | `${LINKFOX_TOOL_GATEWAY}`（可用 `LINKFOX_TOOL_GATEWAY` / `TEMU_API_BASE_URL` / `STORE_API_BASE_URL` 覆盖） |\r\n| 广告 OpenAPI | `POST /temu/proxy` |\r\n| 加签文件下载 | `POST /temu/fileDownload`（`temu_us_file_download.py`） |\r\n| LinkFox 鉴权 | Header **`Authorization`** 与 **`Token`**（同值）；或 `LINKFOX_AGENT_API_KEY` / `LINKFOXAGENT_API_KEY`；或 JSON `token`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理） |\r\n| Temu 鉴权 | Body `accessToken`，或 `storeKey` + `site` + `managementType` + `tokenPurpose` |\r\n| 默认 | `site=us`，`managementType=semi-managed`，`tokenPurpose=product-inventory` |\r\n| 上游 OpenAPI（US） | `https://openapi-b-us.temu.com/openapi/router`（网关按 `site` 解析） |\r\n\r\n### 网关请求 Body（`/temu/proxy`）\r\n\r\n| 参数 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| site | string | 是 | `us`（本 skill 默认） |\r\n| managementType | string | 是 | `semi-managed` |\r\n| accessToken | string | 与 storeKey 二选一 | Temu 店铺令牌 |\r\n| storeKey | string | 与 accessToken 二选一 | `~/.linkfox/temu-access-tokens.json` 中的键 |\r\n| tokenPurpose | string | 否 | 建议 **`product-inventory`**（以各 Ads 接口 Partner 文档为准） |\r\n| type | string | 是 | Temu 接口名，如 Partner **Ads** 菜单下的 `bg.*` / `temu.*` |\r\n| params | object | 否 | 业务参数；多数接口业务块在 **`params.request`** |\r\n\r\n### 网关响应\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| body | string | Temu 原始 JSON 字符串；脚本解析为 `temuBody` |\r\n| code | integer | 网关错误码：`1002` 参数/Token，`1003` 转发失败 |\r\n\r\n解析顺序：**网关 `code`** → `JSON.parse(body)` → `success` / `errorCode` / `errorMsg` / `result`。\r\n\r\n### 脚本调用\r\n\r\n```bash\r\nexport LINKFOXAGENT_API_KEY=\"<key>\"\r\npython scripts/temu_us_proxy.py '{\"accessToken\":\"TOKEN\",\"tokenPurpose\":\"product-inventory\",\"type\":\"<API_TYPE>\",\"params\":{\"request\":{}}}'\r\n```\r\n\r\n业务字段可放在顶层或嵌套 `params`；含 `request` 时通常整体作为 `params` 转发。\r\n\r\n---\r\n\r\n## 接口一览\r\n\r\n完整 `sub_menu_code` 与 Partner 文档 URL 见 [partner-us-catalog.md](./partner-us-catalog.md)。\r\n\r\n**每个接口单独一份文档**：[apis/README.md](./apis/README.md)（随接入递增）。\r\n\r\n| type | 说明 | 文档 |\r\n|------|------|------|\r\n| `temu.searchrec.ad.roas.pred` | 广告 ROAS 预测 | [apis/temu-searchrec-ad-roas-pred.md](./apis/temu-searchrec-ad-roas-pred.md) |\r\n| `temu.searchrec.ad.reports.mall.query` | 店铺广告报表查询 | [apis/temu-searchrec-ad-reports-mall-query.md](./apis/temu-searchrec-ad-reports-mall-query.md) |\r\n| `temu.searchrec.ad.create` | 创建广告 | [apis/temu-searchrec-ad-create.md](./apis/temu-searchrec-ad-create.md) |\r\n| `temu.searchrec.ad.detail.query` | 广告详情查询 | [apis/temu-searchrec-ad-detail-query.md](./apis/temu-searchrec-ad-detail-query.md) |\r\n| `temu.searchrec.ad.log.query` | 广告操作日志查询 | [apis/temu-searchrec-ad-log-query.md](./apis/temu-searchrec-ad-log-query.md) |\r\n| `temu.searchrec.ad.goods.create.query` | 广告可创建商品查询 | [apis/temu-searchrec-ad-goods-create-query.md](./apis/temu-searchrec-ad-goods-create-query.md) |\r\n| `temu.searchrec.ad.modify` | 修改广告 | [apis/temu-searchrec-ad-modify.md](./apis/temu-searchrec-ad-modify.md) |\r\n\r\n---\r\n\r\n## 典型广告流程\r\n\r\n```text\r\n1. temu.searchrec.ad.goods.create.query     → 商品是否可创建广告\r\n2. temu.searchrec.ad.roas.pred              → ROAS 预测\r\n3. temu.searchrec.ad.create                 → 创建广告\r\n4. temu.searchrec.ad.detail.query           → 广告详情\r\n5. temu.searchrec.ad.modify                 → 暂停/改预算/改 ROAS/删除\r\n6. temu.searchrec.ad.reports.mall.query     → 店铺报表\r\n7. temu.searchrec.ad.log.query              → 操作日志\r\n```\r\n\r\n---\r\n\r\n## 与其他 Temu US skill 的区分\r\n\r\n| 能力 | skill |\r\n|------|--------|\r\n| **广告 Ads**（本 skill） | **`linkfox-temu-ads-us`** |\r\n| 促销/营销活动 | `linkfox-temu-promotion-us` |\r\n| 商品管理 | `linkfox-temu-manage-product-us` |\r\n| 价格/供货价 | `linkfox-temu-price-us` |\r\n| 订单 | `linkfox-temu-order-us` |\r\n\r\n---\r\n\r\n## 网关错误码\r\n\r\n| code | 说明 | 处理 |\r\n|------|------|------|\r\n| 1002 | 参数或 LinkFox Token 无效 | 修正参数与 `LINKFOXAGENT_API_KEY` |\r\n| 1003 | 转发失败 | 检查 Temu token、`tokenPurpose`、白名单、网络 |\r\n| 402 | HTTP 402 | 按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\r\n\r\n---\r\n\r\n## Feedback API\r\n\r\n- **POST** `https://skill-api.linkfox.com/api/v1/public/feedback`\r\n- `skillName`: **`linkfox-temu-ads-us`**\n\nFile v1.0.6:references/apis/temu-searchrec-ad-create.md\n\n# 创建广告 — `temu.searchrec.ad.create`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_create.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=7bc9231776304158a895e41a816b7805 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.create`，业务载荷放在 Body 的 `params` |\n\n**Description:** Create search recommendation ads.\n\n> **`createAdReqs`** 为必填；子字段在 Partner 表中为折叠行，按 **Request Example** 展开。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    └── createAdReqs[] (OBJECT[], 必填)\n        ├── goodsId (LONG, 必填)\n        ├── budget (LONG, 必填)\n        ├── roas (LONG, 必填)\n        └── roasType (INTEGER, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| createAdReqs | OBJECT[] | **是** | CreateAd parameter |\n\n#### `createAdReqs[]`（Request Example 展开）\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsId | LONG | 是 | Goods id |\n| budget | LONG | 是 | Ad budget（广告预算） |\n| roas | LONG/INTEGER | 是 | Target ROAS（目标 ROAS） |\n| roasType | INTEGER | 是 | ROAS type（ROAS 类型；具体枚举以 Partner 文档为准） |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"createAdReqs\": [\n      {\n        \"goodsId\": 100001,\n        \"budget\": 5000,\n        \"roas\": 350,\n        \"roasType\": 1\n      }\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    ├── alreadyCreatedGoodsNum (INTEGER)\n    ├── successCreateProductNum (INTEGER)\n    ├── successGoodsIdLists[] (LONG)\n    ├── createGoodsFailMap (OBJECT)\n    └── createGoodsFailObjList[]\n        ├── goodsId, reason, success\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| alreadyCreatedGoodsNum | INTEGER | Number of goods that already had ads created |\n| successCreateProductNum | INTEGER | Number of successfully created ad products |\n| successGoodsIdLists | LONG[] | Successfully created goods id list |\n| createGoodsFailMap | OBJECT | Fail map（Example 键为 `$key`/`$value`，表示失败 goodsId → 原因） |\n| createGoodsFailObjList | OBJECT[] | Fail list with details |\n\n#### `createGoodsFailObjList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| reason | STRING | Failure reason |\n| success | BOOLEAN | Whether succeeded（Example 中存在，以实际返回为准） |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_create.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"createAdReqs\": [{\"goodsId\": 100001, \"budget\": 5000, \"roas\": 350, \"roasType\": 1}]}}'\n```\n\n**典型流程：** 可先 [goods.create.query](./temu-searchrec-ad-goods-create-query.md) 确认可投 → [roas.pred](./temu-searchrec-ad-roas-pred.md) 预估 → 本接口创建。\n\nFile v1.0.6:references/apis/temu-searchrec-ad-detail-query.md\n\n# 广告详情查询 — `temu.searchrec.ad.detail.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_detail_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=66db5438c37446f49c122829489ac6d4 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.detail.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query ad detail by goods list.\n\n> **`goodsList`**（LONG[]）必填，单次传入 goodsId 列表。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    └── goodsList (LONG[], 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsList | LONG[] | **是** | Goods list |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsList\": [\n      100001,\n      100002\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    └── adsDetail[]\n        ├── goodsId, roas, budget, adShowStatus, adPhase\n        ├── summary (OBJECT)\n        ├── reportsSummaryDTO (OBJECT)\n        └── siteStatusInfoList[]\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| adsDetail | OBJECT[] | Ad detail per goods |\n\n#### `adsDetail[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| roas | LONG/NUMBER | Current ROAS setting |\n| budget | LONG/NUMBER | Ad budget |\n| adShowStatus | INTEGER | Ad show status |\n| adPhase | INTEGER | Ad phase |\n| summary | OBJECT | Metrics summary（结构同 [reports.mall.query](./temu-searchrec-ad-reports-mall-query.md) 之 `summary`） |\n| reportsSummaryDTO | OBJECT | Aggregated report metrics（全量汇总，字段均为 `*All.val`） |\n| siteStatusInfoList | OBJECT[] | Per-site ad status |\n\n#### `summary` 指标对象通用结构\n\n以下指标名在 **`summary`** 下各出现一次，每个指标均为 **OBJECT**，包含 **`total`**、**`ad`**、**`netTotal`**、**`netAd`** 四个子对象，每个子对象含 **`val`**（数值）：\n\n| 指标字段 | 说明 |\n|----------|------|\n| ctr | Click-through rate（点击率） |\n| cartCnt | Add-to-cart count（加购数） |\n| clkCnt | Click count（点击数） |\n| orderPayAmt | Order payment amount（订单支付金额） |\n| spend | Ad spend（广告花费） |\n| orderPayCnt | Order payment count（支付订单数） |\n| roas | Return on ad spend |\n| acos | Advertising cost of sales |\n| transactionCost | Transaction cost |\n| goodsNum | Goods number |\n| imprCnt | Impression count（曝光数） |\n| cvr | Conversion rate（转化率） |\n\n每个子路径示例：`summary.spend.ad.val`（广告归因花费）。\n\n#### `reportsSummaryDTO`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| clkCntAll | OBJECT | `val` — all clicks |\n| orderPayCntAll | OBJECT | `val` — all order pay count |\n| adSpendAll | OBJECT | `val` — all ad spend |\n| acosAll | OBJECT | `val` |\n| ctrAll | OBJECT | `val` |\n| imprCntAll | OBJECT | `val` |\n| orderPayAmtAll | OBJECT | `val` |\n| cartCntAll | OBJECT | `val` |\n| roasAll | OBJECT | `val` |\n\n#### `siteStatusInfoList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| adShowStatus | INTEGER | Ad show status for site |\n| forbidReason | STRING | Forbid reason if not shown |\n| siteNameList | STRING[] | Site names |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_detail_query.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"goodsList\": [100001, 100002]}}'\n```\n\n**典型流程：** 按 **`goodsList`** 查投放状态、预算、ROAS 与报表摘要。\n\nFile v1.0.6:references/apis/temu-searchrec-ad-goods-create-query.md\n\n# 广告可创建商品查询 — `temu.searchrec.ad.goods.create.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_goods_create_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=374d1f7fefdb4232b7b7a0239cb4465d |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.goods.create.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query whether goods can create ads.\n\n> **`goodsIdList`** 必填。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    └── goodsIdList (LONG[], 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsIdList | LONG[] | **是** | Goods id list |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsIdList\": [\n      100001,\n      100002\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    └── goodsInfoList[]\n        ├── goodsId (LONG)\n        └── grayReason[]\n            ├── type (INTEGER)\n            └── reason (STRING)\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsInfoList | OBJECT[] | Goods create-ad eligibility info |\n\n#### `goodsInfoList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| grayReason | OBJECT[] | Reasons if not eligible for ad creation（不可创建原因列表） |\n\n#### `grayReason[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| type | INTEGER | Reason type code |\n| reason | STRING | Reason description |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_goods_create_query.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"goodsIdList\": [100001, 100002]}}'\n```\n\n**典型流程：** 创建前检查商品是否可投 → [ad.create](./temu-searchrec-ad-create.md)。\n\nFile v1.0.6:references/apis/temu-searchrec-ad-log-query.md\n\n# 广告操作日志查询 — `temu.searchrec.ad.log.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_log_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=c2c5eda51c414e788bab914a297d1881 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.log.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query ad operation logs for a goods.\n\n> **`goodsId`**、**`startTime`**、**`endTime`** 均为必填（毫秒时间戳，规则同报表查询）。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    ├── goodsId (LONG, 必填)\n    ├── startTime (LONG, 必填)\n    └── endTime (LONG, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsId | LONG | **是** | Goods id |\n| startTime | LONG | **是** | Query start time, millisecond level timestamp (the value starts at 0:00 local time) |\n| endTime | LONG | **是** | Query end time, millisecond-level timestamp (the value is based on local time 23:59:59 seconds 999 milliseconds) |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsId\": 100001,\n    \"startTime\": 1714521600000,\n    \"endTime\": 1714607999999\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result[]\n    ├── eventType (STRING)\n    ├── updateSellerName (STRING)\n    ├── changeInfo (STRING)\n    └── updatedAt (STRING)\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`（OBJECT[]）\n\nPartner Response Example 中 **`result`** 直接为数组。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| eventType | STRING | Event type（操作事件类型） |\n| updateSellerName | STRING | Seller name who made the change |\n| changeInfo | STRING | Change information（变更内容描述） |\n| updatedAt | STRING | Update time（更新时间，Example 为字符串） |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_log_query.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"goodsId\": 100001, \"startTime\": 1714521600000, \"endTime\": 1714607999999}}'\n```\n\n**典型流程：** 排查某 **`goodsId`** 广告变更历史。\n\nFile v1.0.6:references/apis/temu-searchrec-ad-modify.md\n\n# 修改广告 — `temu.searchrec.ad.modify`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_modify.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=0b7140898262428eb8a4b28609112651 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.modify`，业务载荷放在 Body 的 `params` |\n\n**Description:** Modify ads (delete, pause, budget, ROAS, etc.).\n\n> **`status`**、**`modifyAdDTO`** 均为必填；**`status`** 决定 **`modifyAdDTO`** 中哪些字段生效。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    ├── modifyAdDTO (OBJECT, 必填)\n    │   ├── goodsId (LONG, 必填)\n    │   ├── budget (LONG, 否)\n    │   └── roas (LONG, 否)\n    └── status (INTEGER, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| modifyAdDTO | OBJECT | **是** | ModifyAdDTO request body |\n| status | INTEGER | **是** | Modification type: 1:delete, 2:pause, 3:open, 4:modify budget, 5:modify roas |\n\n#### `status`（必填）\n\n| 值 | 说明 |\n|----|------|\n| `1` | delete |\n| `2` | pause |\n| `3` | open |\n| `4` | modify budget |\n| `5` | modify roas |\n\n#### `modifyAdDTO`（OBJECT，必填）\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id（必填） |\n| budget | LONG | New budget（`status=4` 时使用） |\n| roas | LONG/NUMBER | New ROAS（`status=5` 时使用） |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"status\": 4,\n    \"modifyAdDTO\": {\n      \"goodsId\": 100001,\n      \"budget\": 8000,\n      \"roas\": 400\n    }\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    ├── successModifyProductNum (INTEGER)\n    └── modifyGoodsRespList[]\n        ├── goodsId, reason, success\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| successModifyProductNum | INTEGER | Number of successfully modified products |\n| modifyGoodsRespList | OBJECT[] | Per-goods modify result |\n\n#### `modifyGoodsRespList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| reason | STRING | Failure reason（失败时） |\n| success | BOOLEAN | Whether modify succeeded |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_modify.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"status\": 4, \"modifyAdDTO\": {\"goodsId\": 100001, \"budget\": 8000, \"roas\": 400}}}'\n```\n\n**典型流程：** 按 **`status`** 删除/暂停/开启/改预算/改 ROAS。\n\nFile v1.0.6:references/apis/temu-searchrec-ad-reports-mall-query.md\n\n# 店铺广告报表查询 — `temu.searchrec.ad.reports.mall.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_reports_mall_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=595f05856989480aa03abd58da203047 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.reports.mall.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query mall-level ad reports.\n\n> **`startTs`**、**`endTs`** 均为必填，毫秒时间戳（当地时区 0:00 至 23:59:59.999）。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    ├── startTs (LONG, 必填)\n    └── endTs (LONG, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| startTs | LONG | **是** | Query start time, millisecond level timestamp (the value starts at 0:00 local time) |\n| endTs | LONG | **是** | Query end time, millisecond-level timestamp (the value is based on local time 23:59:59 seconds 999 milliseconds) |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"startTs\": 1714521600000,\n    \"endTs\": 1714607999999\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    ├── summary (OBJECT) → ctr/cartCnt/clkCnt/… 各含 total/ad/netTotal/netAd.val\n    └── reportsItemList[] → goodsId, ts, roas, spend 等 { val }\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| summary | OBJECT | Mall-level aggregated metrics（店铺维度汇总） |\n| reportsItemList | OBJECT[] | Per-goods / per-time report items（明细列表） |\n\n#### `summary` 指标对象通用结构\n\n以下指标名在 **`summary`** 下各出现一次，每个指标均为 **OBJECT**，包含 **`total`**、**`ad`**、**`netTotal`**、**`netAd`** 四个子对象，每个子对象含 **`val`**（数值）：\n\n| 指标字段 | 说明 |\n|----------|------|\n| ctr | Click-through rate（点击率） |\n| cartCnt | Add-to-cart count（加购数） |\n| clkCnt | Click count（点击数） |\n| orderPayAmt | Order payment amount（订单支付金额） |\n| spend | Ad spend（广告花费） |\n| orderPayCnt | Order payment count（支付订单数） |\n| roas | Return on ad spend |\n| acos | Advertising cost of sales |\n| transactionCost | Transaction cost |\n| goodsNum | Goods number |\n| imprCnt | Impression count（曝光数） |\n| cvr | Conversion rate（转化率） |\n\n每个子路径示例：`summary.spend.ad.val`（广告归因花费）。\n\n#### `reportsItemList[]` 元素字段\n\n各指标多为 **`{ \"val\": <number> }`** 包装（Partner Response Example）：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| ts | LONG | Timestamp（报表时间点，毫秒） |\n| roas | OBJECT | ROAS，`val` |\n| totalRoas | OBJECT | Total ROAS，`val` |\n| netRoas | OBJECT | Net ROAS，`val` |\n| acos | OBJECT | ACOS，`val` |\n| totalAcos | OBJECT | Total ACOS，`val` |\n| netAcos | OBJECT | Net ACOS，`val` |\n| adSpend | OBJECT | Ad spend，`val` |\n| netAdSpend | OBJECT | Net ad spend，`val` |\n| orderPayAmt | OBJECT | Order pay amount，`val` |\n| totalOrderPayAmt | OBJECT | Total order pay amount，`val` |\n| netOrderPayAmt | OBJECT | Net order pay amount，`val` |\n| orderPayCnt | OBJECT | Order pay count，`val` |\n| totalOrderPayCnt | OBJECT | Total order pay count，`val` |\n| netOrderPayCnt | OBJECT | Net order pay count，`val` |\n| clkCnt | OBJECT | Click count，`val` |\n| totalClkCnt | OBJECT | Total click count，`val` |\n| ctr | OBJECT | CTR，`val` |\n| totalCtr | OBJECT | Total CTR，`val` |\n| cvr | OBJECT | CVR，`val` |\n| totalCvr | OBJECT | Total CVR，`val` |\n| cartCnt | OBJECT | Cart count，`val` |\n| imprCnt | OBJECT | Impression count，`val` |\n| totalImprCnt | OBJECT | Total impression count，`val` |\n| goodsNum | OBJECT | Goods number，`val` |\n| totalGoodsNum | OBJECT | Total goods number，`val` |\n| netGoodsNum | OBJECT | Net goods number，`val` |\n| transactionCost | OBJECT | Transaction cost，`val` |\n| totalTransactionCost | OBJECT | Total transaction cost，`val` |\n| netTransactionCost | OBJECT | Net transaction cost，`val` |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_reports_mall_query.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"startTs\": 1714521600000, \"endTs\": 1714607999999}}'\n```\n\n**典型流程：** 按时间窗拉店铺广告汇总与明细 → 单商品详情见 [ad.detail.query](./temu-searchrec-ad-detail-query.md)。\n\nFile v1.0.6:references/apis/temu-searchrec-ad-roas-pred.md\n\n# 广告 ROAS 预测 — `temu.searchrec.ad.roas.pred`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_roas_pred.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=dfff26bad8e94ed5abaaf5cdade50c26 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.roas.pred`，业务载荷放在 Body 的 `params` |\n\n**Description:** Predict ad ROAS for goods.\n\n> **`goodsInfoList`** 为必填。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    ├── goodsInfoList (OBJECT[], 必填)\n    ├── goodsInfoList[] (OBJECT[], 必填)\n    └──     └── goodsId (LONG, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsInfoList | OBJECT[] | **是** | Goods information list |\n\n#### `goodsInfoList[]`（Request Example 展开）\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsId | LONG | 是 | Goods id |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsInfoList\": [\n      {\n        \"goodsId\": 100001\n      }\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    └── queryAdBidResult[]\n        ├── goodsId (LONG)\n        └── predList[]\n            └── roas (STRING)\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| queryAdBidResult | OBJECT[] | Query ad bid / ROAS prediction results |\n\n#### `queryAdBidResult[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| predList | OBJECT[] | Prediction list |\n\n#### `predList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| roas | STRING | Predicted ROAS value（Partner Example 为字符串） |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_roas_pred.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"goodsInfoList\": [{\"goodsId\": 100001}]}}'\n```\n\n**典型流程：** 创建广告前可用本接口预估 ROAS → [ad.create](./temu-searchrec-ad-create.md)。\n\nArchive v1.0.5: 38 files, 55344 bytes\n\nFiles: references/access-token.md (4527b), references/api.md (5161b), references/apis/README.md (1301b), references/apis/temu-searchrec-ad-create.md (4617b), references/apis/temu-searchrec-ad-detail-query.md (5249b), references/apis/temu-searchrec-ad-goods-create-query.md (3518b), references/apis/temu-searchrec-ad-log-query.md (3811b), references/apis/temu-searchrec-ad-modify.md (4203b), references/apis/temu-searchrec-ad-reports-mall-query.md (6156b), references/apis/temu-searchrec-ad-roas-pred.md (3687b), references/authorization-flow.md (1186b), references/onboarding.md (2046b), references/partner-us-catalog.md (3173b), scripts/_temu_auth_guide.py (6198b), scripts/_temu_common.py (12421b), scripts/_temu_token_store.py (4273b), scripts/_temu_us_common.py (3161b), scripts/_us_ads_script.py (510b), scripts/check_linkfox_token.py (1797b), scripts/get_temu_access_token.py (1843b), scripts/list_temu_access_tokens.py (652b), scripts/onboarding.py (24089b), scripts/save_temu_access_token.py (1377b), scripts/temu_file_download.py (1681b), scripts/temu_proxy.py (2124b), scripts/temu_token_guide.py (1594b), scripts/temu_us_file_download.py (708b), scripts/temu_us_proxy.py (923b), scripts/us_ads_searchrec_ad_create.py (234b), scripts/us_ads_searchrec_ad_detail_query.py (258b), scripts/us_ads_searchrec_ad_goods_create_query.py (285b), scripts/us_ads_searchrec_ad_log_query.py (255b), scripts/us_ads_searchrec_ad_modify.py (234b), scripts/us_ads_searchrec_ad_reports_mall_query.py (282b), scripts/us_ads_searchrec_ad_roas_pred.py (249b), skill-card.md (3058b), SKILL.md (6094b), _meta.json (138b)\n\nFile v1.0.5:SKILL.md\n\n---\nname: linkfox-temu-ads-us\ndescription: Temu 美国站电商广告 Ads API，经 LinkFox 网关转发 Partner US Ads / 广告投放 相关 bg/temu 接口（广告计划、广告组、创意、报表、预算出价等，接口将按 Partner 文档逐条接入）。当用户提到 Temu US 广告、Ads、广告投放、广告计划、广告组、创意、出价、预算、广告报表、ad campaign、product-inventory 广告 时触发。商品管理用 linkfox-temu-manage-product-us；促销用 linkfox-temu-promotion-us；订单用 linkfox-temu-order-us。\n---\n\n# Temu 美国站 — 电商广告（Ads）\n\n本 skill（`linkfox-temu-ads-us`）覆盖 Partner Platform for US **Ads / 电商广告**（广告计划、投放、报表等；`menu_code` 与各 `sub_menu_code` 以 Partner 后台为准，见 [partner-us-catalog.md](./references/partner-us-catalog.md)）。\n\n已接入 **7** 条 Partner **Ads**（`temu.searchrec.ad.*`）接口，清单见 [partner-us-catalog.md](./references/partner-us-catalog.md)。\n\n**网关（本 skill 内置）**：\n\n| 能力 | 方法 | 路径 |\n|------|------|------|\n| 广告 OpenAPI（`us_ads_*`、`temu_us_proxy`） | POST | `https://tool-gateway.linkfox.com/temu/proxy` |\n| 加签文件下载 | POST | `https://tool-gateway.linkfox.com/temu/fileDownload` |\n\n## 相关 skill\n\n| 场景 | skill |\n|------|--------|\n| **广告 Ads**（本 skill） | **`linkfox-temu-ads-us`** |\n| 商品列表/详情/编辑/库存/上下架 | `linkfox-temu-manage-product-us` |\n| 促销/营销活动 | `linkfox-temu-promotion-us` |\n| 发品 | `linkfox-temu-add-product-us` |\n| 价格/供货价、定价单 | `linkfox-temu-price-us` |\n| 订单列表/详情 | `linkfox-temu-order-us` |\n| 退货与退款 | `linkfox-temu-returns-refunds-us` |\n| 网关与 Temu token | 本 skill `scripts/` |\n\n## 调用方式\n\n- **API 端点**：`POST /temu/proxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '<JSON 参数>' [--inline]`（可用脚本见上文脚本一览）\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-temu-ads-us-<timestamp>.json`（`<cwd>` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n## 默认参数\n\n| 字段 | 默认 | 说明 |\n|------|------|------|\n| site | `us` | Partner US |\n| managementType | `semi-managed` | 半托管（具体接口以 Partner 文档为准） |\n| tokenPurpose | `product-inventory` | 卖家助手默认（若 Partner 某 Ads 接口要求其他 `tokenPurpose`，以该接口文档为准） |\n\n## 鉴权\n\n1. **LinkFox**：`LINKFOXAGENT_API_KEY` → Header `Authorization` + `Token`\n2. **Temu**：`accessToken` 或 `storeKey`（`storeKey` 时建议带 `tokenPurpose=product-inventory`）\n\n## Scripts\n\n| 脚本 | 说明 |\n|------|------|\n| `temu_us_proxy.py` | 任意 type |\n| `temu_us_file_download.py` | 加签下载 |\n| `us_ads_searchrec_ad_roas_pred.py` | `temu.searchrec.ad.roas.pred` |\n| `us_ads_searchrec_ad_reports_mall_query.py` | `temu.searchrec.ad.reports.mall.query` |\n| `us_ads_searchrec_ad_create.py` | `temu.searchrec.ad.create` |\n| `us_ads_searchrec_ad_detail_query.py` | `temu.searchrec.ad.detail.query` |\n| `us_ads_searchrec_ad_log_query.py` | `temu.searchrec.ad.log.query` |\n| `us_ads_searchrec_ad_goods_create_query.py` | `temu.searchrec.ad.goods.create.query` |\n| `us_ads_searchrec_ad_modify.py` | `temu.searchrec.ad.modify` |\n\n## 接入新接口（约定）\n\n你每提供一条 Partner 文档（`type` + `sub_menu_code` + URL + Request/Response 参数表），将：\n\n1. 新增 `references/apis/<type-slug>.md`（完整入参/出参层级）\n2. 新增 `scripts/us_ads_<slug>.py`（调用 `_us_ads_script.run_cli`）\n3. 更新 [partner-us-catalog.md](./references/partner-us-catalog.md)、[apis/README.md](./references/apis/README.md) 与本表\n\n## 示例（通用代理）\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\n\npython scripts/temu_us_proxy.py '{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"type\": \"<TEMU_API_TYPE>\",\n  \"params\": {\n    \"request\": {}\n  }\n}'\n```\n\n**Feedback：** `skillName`：`linkfox-temu-ads-us`\n\n## 网关与授权脚本\n\n| 脚本 | 说明 |\n|------|------|\n| `check_linkfox_token.py` | 校验 LinkFox 用户 Token |\n| `temu_token_guide.py` | Temu accessToken 后台授权步骤 |\n| `save_temu_access_token.py` | 保存 accessToken 到本地 |\n| `list_temu_access_tokens.py` | 列出已保存 token |\n| `get_temu_access_token.py` | 读取已保存 token |\n| `temu_proxy.py` | 通用网关转发（多 site） |\n| `temu_file_download.py` | 加签文件下载（多 site） |\n\n授权说明：[references/access-token.md](./references/access-token.md)\n\n## 积分消耗规则\n\n不消耗积分。\n\nFile v1.0.5:references/apis/README.md\n\n# Ads — 接口文档索引\n\n网关见 [../api.md](../api.md)；目录见 [../partner-us-catalog.md](../partner-us-catalog.md)。\n\n## 查询 / 预测\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.roas.pred` | 广告 ROAS 预测 | [temu-searchrec-ad-roas-pred.md](./apis/temu-searchrec-ad-roas-pred.md) |\n| `temu.searchrec.ad.goods.create.query` | 广告可创建商品查询 | [temu-searchrec-ad-goods-create-query.md](./apis/temu-searchrec-ad-goods-create-query.md) |\n\n## 创建 / 修改\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.create` | 创建广告 | [temu-searchrec-ad-create.md](./apis/temu-searchrec-ad-create.md) |\n| `temu.searchrec.ad.modify` | 修改广告 | [temu-searchrec-ad-modify.md](./apis/temu-searchrec-ad-modify.md) |\n\n## 报表 / 日志\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.reports.mall.query` | 店铺广告报表查询 | [temu-searchrec-ad-reports-mall-query.md](./apis/temu-searchrec-ad-reports-mall-query.md) |\n| `temu.searchrec.ad.detail.query` | 广告详情查询 | [temu-searchrec-ad-detail-query.md](./apis/temu-searchrec-ad-detail-query.md) |\n| `temu.searchrec.ad.log.query` | 广告操作日志查询 | [temu-searchrec-ad-log-query.md](./apis/temu-searchrec-ad-log-query.md) |\n\nFile v1.0.5:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-temu-ads-us\",\n  \"version\": \"1.0.5\",\n  \"publishedAt\": 1786101154761\n}\n\nFile v1.0.5:references/access-token.md\n\n# Temu accessToken 授权与获取\n\nTemu **没有** LinkFox 侧自动 OAuth；`accessToken` 须在 Temu 卖家后台「服务市场 → 授权管理」**手动复制**。与 `LINKFOXAGENT_API_KEY`（LinkFox 用户鉴权）是两套令牌。\n\n## 两种鉴权（勿混淆）\n\n| 令牌 | 用途 | 获取方式 |\n|------|------|----------|\n| **LinkFox 用户 Token** | 调用 `/temu/proxy`、`/temu/fileDownload` **必填** | `LINKFOXAGENT_API_KEY` 或请求 JSON 的 `token`；Header `Authorization` + `Token`（同 amazon-store-auth）（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理） |\n| **Temu accessToken** | Temu 业务 API（经紫鸟转发） | Temu 卖家后台授权后复制 |\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<your-key>\"\npython scripts/check_linkfox_token.py\n```\n\n## tokenPurpose 与场景\n\n| tokenPurpose | 店铺类型 | 推荐 site | 授权应用 |\n|--------------|----------|-----------|----------|\n| `product-inventory` | 半托管 | `cn` / `partner` | 酷鸟卖家助手 |\n| `order-shipping` | 半托管 | `us` / `global` / `eu` | Cyber-ERP酷鸟助手 |\n| `full-managed` | 全托管 | `cn` / `partner` | 酷鸟卖家助手 |\n| `local-native` | 本土（美/欧主体） | `us` 等 | Cyber-ERP |\n\n## 1. 半托管 — 商品/库存 Token\n\n1. 登录 [seller.kuajingmaihuo.com](https://seller.kuajingmaihuo.com) 或 [agentseller.temu.com](https://agentseller.temu.com)\n2. **系统管理** → **服务市场** → **授权管理**\n3. **获取授权** → 选择 **「酷鸟卖家助手」**\n4. 全选常规和特殊授权 → 确认 → **复制 access_token**\n5. 调用 API：`site=cn` 或 `partner`，`managementType=semi-managed`\n\n## 2. 半托管 — 订单/发货 Token\n\n1. 登录 Temu 卖家后台\n2. 右上角 **Seller Central** → 切换到目标区域（美区 / 欧区 / 全球）\n3. **服务市场** → **授权管理**\n4. **获取授权** → 选择 **「Cyber-ERP酷鸟助手」**\n5. 全选授权 → 确认 → 复制 token\n6. 调用 API：`site=us` / `global` / `eu`，`managementType=semi-managed`\n\n## 3. 全托管店铺\n\n1. 登录 Temu 平台\n2. **系统管理** → **服务市场** → **授权管理**\n3. **获取授权** → **「酷鸟卖家助手」** → 全选 → 复制 token\n4. 调用 API：`managementType=full-managed`，`site` 通常 `cn` 或 `partner`\n\n## 4. 本土店铺（美区、欧区主体）\n\n1. 登录 Temu\n2. **Apps And Services** → **Manage Your Apps**\n3. **Authorize a new app** → 搜索 **「Cyber-ERP」**\n4. 一般权限与敏感权限全选 → 确认 → 复制 token\n\n## 站点与 OpenAPI 网关\n\n| site | 说明 | Temu 网关 |\n|------|------|-----------|\n| cn | 中国站 | openapi.kuajingmaihuo.com |\n| partner | Partner 网关 | openapi-b-partner.temu.com |\n| us | 美国站 | openapi-b-us.temu.com |\n| global | 全球区 | openapi-b-global.temu.com |\n| eu | 欧洲站 | openapi-b-eu.temu.com |\n\n## 本地保存 Token（推荐）\n\n默认存储：`~/.linkfox/temu-access-tokens.json`（可用 `TEMU_TOKEN_STORE_PATH` 覆盖）。\n\n```bash\n# 查看授权步骤\npython scripts/temu_token_guide.py '{\"shopType\":\"semi-managed\",\"tokenPurpose\":\"product-inventory\",\"site\":\"cn\"}'\n\n# 保存 token\npython scripts/save_temu_access_token.py '{\n  \"storeKey\": \"my-shop\",\n  \"label\": \"中国半托管\",\n  \"site\": \"cn\",\n  \"managementType\": \"semi-managed\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"accessToken\": \"PASTE_TOKEN\"\n}'\n\n# 列出已保存（脱敏）\npython scripts/list_temu_access_tokens.py\n\n# 用 storeKey 调 API（无需每次粘贴 token）\npython scripts/temu_proxy.py '{\n  \"storeKey\": \"my-shop\",\n  \"site\": \"cn\",\n  \"managementType\": \"semi-managed\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"type\": \"bg.goods.category.mapping\",\n  \"params\": {\"goodsName\": \"测试\", \"goodsNameEn\": \"Test\"}\n}'\n```\n\n## 注意事项\n\n1. **子账号**：可能无法进入服务市场，需主账号授权。\n2. **多站点**：美国站、英国站等需分别登录对应后台获取 Token。\n3. **有效期**：Token 会过期，过期后重新在后台复制并 `save_temu_access_token.py`。\n4. **IP 白名单**：需联系紫鸟开放平台配置调用 IP。\n5. **参数小写**：`site`、`managementType` 必须小写。\n\n## 脚本一览\n\n| 脚本 | 说明 |\n|------|------|\n| `temu_token_guide.py` | 按店铺类型/用途输出授权步骤 |\n| `save_temu_access_token.py` | 保存 accessToken 到本地 |\n| `list_temu_access_tokens.py` | 列出已保存 token（默认脱敏）|\n| `get_temu_access_token.py` | 读取指定 store 的 token |\n\nFile v1.0.5:references/api.md\n\n# linkfox-temu-ads-us — API 参考\r\n\r\nTemu **美国站电商广告（Ads）**，经本 skill `temu_us_proxy`（`POST /temu/proxy`） 转发。Temu 的 `type` 写在 Body，**不是** URL 路径。\r\n\r\n> 网关与鉴权：本 skill `scripts/`（`LINKFOXAGENT_API_KEY`、`accessToken` / `storeKey`）。授权见 `references/access-token.md`。\r\n\r\n---\r\n\r\n## 调用规范\r\n\r\n| 项 | 说明 |\r\n|----|------|\r\n| 网关根地址 | `${LINKFOX_TOOL_GATEWAY}`（可用 `LINKFOX_TOOL_GATEWAY` / `TEMU_API_BASE_URL` / `STORE_API_BASE_URL` 覆盖） |\r\n| 广告 OpenAPI | `POST /temu/proxy` |\r\n| 加签文件下载 | `POST /temu/fileDownload`（`temu_us_file_download.py`） |\r\n| LinkFox 鉴权 | Header **`Authorization`** 与 **`Token`**（同值）；或 `LINKFOX_AGENT_API_KEY` / `LINKFOXAGENT_API_KEY`；或 JSON `token`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理） |\r\n| Temu 鉴权 | Body `accessToken`，或 `storeKey` + `site` + `managementType` + `tokenPurpose` |\r\n| 默认 | `site=us`，`managementType=semi-managed`，`tokenPurpose=product-inventory` |\r\n| 上游 OpenAPI（US） | `https://openapi-b-us.temu.com/openapi/router`（网关按 `site` 解析） |\r\n\r\n### 网关请求 Body（`/temu/proxy`）\r\n\r\n| 参数 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| site | string | 是 | `us`（本 skill 默认） |\r\n| managementType | string | 是 | `semi-managed` |\r\n| accessToken | string | 与 storeKey 二选一 | Temu 店铺令牌 |\r\n| storeKey | string | 与 accessToken 二选一 | `~/.linkfox/temu-access-tokens.json` 中的键 |\r\n| tokenPurpose | string | 否 | 建议 **`product-inventory`**（以各 Ads 接口 Partner 文档为准） |\r\n| type | string | 是 | Temu 接口名，如 Partner **Ads** 菜单下的 `bg.*` / `temu.*` |\r\n| params | object | 否 | 业务参数；多数接口业务块在 **`params.request`** |\r\n\r\n### 网关响应\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| body | string | Temu 原始 JSON 字符串；脚本解析为 `temuBody` |\r\n| code | integer | 网关错误码：`1002` 参数/Token，`1003` 转发失败 |\r\n\r\n解析顺序：**网关 `code`** → `JSON.parse(body)` → `success` / `errorCode` / `errorMsg` / `result`。\r\n\r\n### 脚本调用\r\n\r\n```bash\r\nexport LINKFOXAGENT_API_KEY=\"<key>\"\r\npython scripts/temu_us_proxy.py '{\"accessToken\":\"TOKEN\",\"tokenPurpose\":\"product-inventory\",\"type\":\"<API_TYPE>\",\"params\":{\"request\":{}}}'\r\n```\r\n\r\n业务字段可放在顶层或嵌套 `params`；含 `request` 时通常整体作为 `params` 转发。\r\n\r\n---\r\n\r\n## 接口一览\r\n\r\n完整 `sub_menu_code` 与 Partner 文档 URL 见 [partner-us-catalog.md](./partner-us-catalog.md)。\r\n\r\n**每个接口单独一份文档**：[apis/README.md](./apis/README.md)（随接入递增）。\r\n\r\n| type | 说明 | 文档 |\r\n|------|------|------|\r\n| `temu.searchrec.ad.roas.pred` | 广告 ROAS 预测 | [apis/temu-searchrec-ad-roas-pred.md](./apis/temu-searchrec-ad-roas-pred.md) |\r\n| `temu.searchrec.ad.reports.mall.query` | 店铺广告报表查询 | [apis/temu-searchrec-ad-reports-mall-query.md](./apis/temu-searchrec-ad-reports-mall-query.md) |\r\n| `temu.searchrec.ad.create` | 创建广告 | [apis/temu-searchrec-ad-create.md](./apis/temu-searchrec-ad-create.md) |\r\n| `temu.searchrec.ad.detail.query` | 广告详情查询 | [apis/temu-searchrec-ad-detail-query.md](./apis/temu-searchrec-ad-detail-query.md) |\r\n| `temu.searchrec.ad.log.query` | 广告操作日志查询 | [apis/temu-searchrec-ad-log-query.md](./apis/temu-searchrec-ad-log-query.md) |\r\n| `temu.searchrec.ad.goods.create.query` | 广告可创建商品查询 | [apis/temu-searchrec-ad-goods-create-query.md](./apis/temu-searchrec-ad-goods-create-query.md) |\r\n| `temu.searchrec.ad.modify` | 修改广告 | [apis/temu-searchrec-ad-modify.md](./apis/temu-searchrec-ad-modify.md) |\r\n\r\n---\r\n\r\n## 典型广告流程\r\n\r\n```text\r\n1. temu.searchrec.ad.goods.create.query     → 商品是否可创建广告\r\n2. temu.searchrec.ad.roas.pred              → ROAS 预测\r\n3. temu.searchrec.ad.create                 → 创建广告\r\n4. temu.searchrec.ad.detail.query           → 广告详情\r\n5. temu.searchrec.ad.modify                 → 暂停/改预算/改 ROAS/删除\r\n6. temu.searchrec.ad.reports.mall.query     → 店铺报表\r\n7. temu.searchrec.ad.log.query              → 操作日志\r\n```\r\n\r\n---\r\n\r\n## 与其他 Temu US skill 的区分\r\n\r\n| 能力 | skill |\r\n|------|--------|\r\n| **广告 Ads**（本 skill） | **`linkfox-temu-ads-us`** |\r\n| 促销/营销活动 | `linkfox-temu-promotion-us` |\r\n| 商品管理 | `linkfox-temu-manage-product-us` |\r\n| 价格/供货价 | `linkfox-temu-price-us` |\r\n| 订单 | `linkfox-temu-order-us` |\r\n\r\n---\r\n\r\n## 网关错误码\r\n\r\n| code | 说明 | 处理 |\r\n|------|------|------|\r\n| 1002 | 参数或 LinkFox Token 无效 | 修正参数与 `LINKFOXAGENT_API_KEY` |\r\n| 1003 | 转发失败 | 检查 Temu token、`tokenPurpose`、白名单、网络 |\r\n| 402 | HTTP 402 | 按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\r\n\r\n---\r\n\r\n## Feedback API\r\n\r\n- **POST** `https://skill-api.linkfox.com/api/v1/public/feedback`\r\n- `skillName`: **`linkfox-temu-ads-us`**\n\nFile v1.0.5:references/apis/temu-searchrec-ad-create.md\n\n# 创建广告 — `temu.searchrec.ad.create`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_create.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=7bc9231776304158a895e41a816b7805 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.create`，业务载荷放在 Body 的 `params` |\n\n**Description:** Create search recommendation ads.\n\n> **`createAdReqs`** 为必填；子字段在 Partner 表中为折叠行，按 **Request Example** 展开。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    └── createAdReqs[] (OBJECT[], 必填)\n        ├── goodsId (LONG, 必填)\n        ├── budget (LONG, 必填)\n        ├── roas (LONG, 必填)\n        └── roasType (INTEGER, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| createAdReqs | OBJECT[] | **是** | CreateAd parameter |\n\n#### `createAdReqs[]`（Request Example 展开）\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsId | LONG | 是 | Goods id |\n| budget | LONG | 是 | Ad budget（广告预算） |\n| roas | LONG/INTEGER | 是 | Target ROAS（目标 ROAS） |\n| roasType | INTEGER | 是 | ROAS type（ROAS 类型；具体枚举以 Partner 文档为准） |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"createAdReqs\": [\n      {\n        \"goodsId\": 100001,\n        \"budget\": 5000,\n        \"roas\": 350,\n        \"roasType\": 1\n      }\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    ├── alreadyCreatedGoodsNum (INTEGER)\n    ├── successCreateProductNum (INTEGER)\n    ├── successGoodsIdLists[] (LONG)\n    ├── createGoodsFailMap (OBJECT)\n    └── createGoodsFailObjList[]\n        ├── goodsId, reason, success\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| alreadyCreatedGoodsNum | INTEGER | Number of goods that already had ads created |\n| successCreateProductNum | INTEGER | Number of successfully created ad products |\n| successGoodsIdLists | LONG[] | Successfully created goods id list |\n| createGoodsFailMap | OBJECT | Fail map（Example 键为 `$key`/`$value`，表示失败 goodsId → 原因） |\n| createGoodsFailObjList | OBJECT[] | Fail list with details |\n\n#### `createGoodsFailObjList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| reason | STRING | Failure reason |\n| success | BOOLEAN | Whether succeeded（Example 中存在，以实际返回为准） |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_create.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"createAdReqs\": [{\"goodsId\": 100001, \"budget\": 5000, \"roas\": 350, \"roasType\": 1}]}}'\n```\n\n**典型流程：** 可先 [goods.create.query](./temu-searchrec-ad-goods-create-query.md) 确认可投 → [roas.pred](./temu-searchrec-ad-roas-pred.md) 预估 → 本接口创建。\n\nFile v1.0.5:references/apis/temu-searchrec-ad-detail-query.md\n\n# 广告详情查询 — `temu.searchrec.ad.detail.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_detail_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=66db5438c37446f49c122829489ac6d4 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.detail.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query ad detail by goods list.\n\n> **`goodsList`**（LONG[]）必填，单次传入 goodsId 列表。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    └── goodsList (LONG[], 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsList | LONG[] | **是** | Goods list |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsList\": [\n      100001,\n      100002\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    └── adsDetail[]\n        ├── goodsId, roas, budget, adShowStatus, adPhase\n        ├── summary (OBJECT)\n        ├── reportsSummaryDTO (OBJECT)\n        └── siteStatusInfoList[]\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| adsDetail | OBJECT[] | Ad detail per goods |\n\n#### `adsDetail[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| roas | LONG/NUMBER | Current ROAS setting |\n| budget | LONG/NUMBER | Ad budget |\n| adShowStatus | INTEGER | Ad show status |\n| adPhase | INTEGER | Ad phase |\n| summary | OBJECT | Metrics summary（结构同 [reports.mall.query](./temu-searchrec-ad-reports-mall-query.md) 之 `summary`） |\n| reportsSummaryDTO | OBJECT | Aggregated report metrics（全量汇总，字段均为 `*All.val`） |\n| siteStatusInfoList | OBJECT[] | Per-site ad status |\n\n#### `summary` 指标对象通用结构\n\n以下指标名在 **`summary`** 下各出现一次，每个指标均为 **OBJECT**，包含 **`total`**、**`ad`**、**`netTotal`**、**`netAd`** 四个子对象，每个子对象含 **`val`**（数值）：\n\n| 指标字段 | 说明 |\n|----------|------|\n| ctr | Click-through rate（点击率） |\n| cartCnt | Add-to-cart count（加购数） |\n| clkCnt | Click count（点击数） |\n| orderPayAmt | Order payment amount（订单支付金额） |\n| spend | Ad spend（广告花费） |\n| orderPayCnt | Order payment count（支付订单数） |\n| roas | Return on ad spend |\n| acos | Advertising cost of sales |\n| transactionCost | Transaction cost |\n| goodsNum | Goods number |\n| imprCnt | Impression count（曝光数） |\n| cvr | Conversion rate（转化率） |\n\n每个子路径示例：`summary.spend.ad.val`（广告归因花费）。\n\n#### `reportsSummaryDTO`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| clkCntAll | OBJECT | `val` — all clicks |\n| orderPayCntAll | OBJECT | `val` — all order pay count |\n| adSpendAll | OBJECT | `val` — all ad spend |\n| acosAll | OBJECT | `val` |\n| ctrAll | OBJECT | `val` |\n| imprCntAll | OBJECT | `val` |\n| orderPayAmtAll | OBJECT | `val` |\n| cartCntAll | OBJECT | `val` |\n| roasAll | OBJECT | `val` |\n\n#### `siteStatusInfoList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| adShowStatus | INTEGER | Ad show status for site |\n| forbidReason | STRING | Forbid reason if not shown |\n| siteNameList | STRING[] | Site names |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_detail_query.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"goodsList\": [100001, 100002]}}'\n```\n\n**典型流程：** 按 **`goodsList`** 查投放状态、预算、ROAS 与报表摘要。\n\nFile v1.0.5:references/apis/temu-searchrec-ad-goods-create-query.md\n\n# 广告可创建商品查询 — `temu.searchrec.ad.goods.create.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_goods_create_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=374d1f7fefdb4232b7b7a0239cb4465d |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.goods.create.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query whether goods can create ads.\n\n> **`goodsIdList`** 必填。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    └── goodsIdList (LONG[], 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsIdList | LONG[] | **是** | Goods id list |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsIdList\": [\n      100001,\n      100002\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    └── goodsInfoList[]\n        ├── goodsId (LONG)\n        └── grayReason[]\n            ├── type (INTEGER)\n            └── reason (STRING)\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsInfoList | OBJECT[] | Goods create-ad eligibility info |\n\n#### `goodsInfoList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| grayReason | OBJECT[] | Reasons if not eligible for ad creation（不可创建原因列表） |\n\n#### `grayReason[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| type | INTEGER | Reason type code |\n| reason | STRING | Reason description |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_goods_create_query.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"goodsIdList\": [100001, 100002]}}'\n```\n\n**典型流程：** 创建前检查商品是否可投 → [ad.create](./temu-searchrec-ad-create.md)。\n\nFile v1.0.5:references/apis/temu-searchrec-ad-log-query.md\n\n# 广告操作日志查询 — `temu.searchrec.ad.log.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_log_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=c2c5eda51c414e788bab914a297d1881 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.log.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query ad operation logs for a goods.\n\n> **`goodsId`**、**`startTime`**、**`endTime`** 均为必填（毫秒时间戳，规则同报表查询）。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    ├── goodsId (LONG, 必填)\n    ├── startTime (LONG, 必填)\n    └── endTime (LONG, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsId | LONG | **是** | Goods id |\n| startTime | LONG | **是** | Query start time, millisecond level timestamp (the value starts at 0:00 local time) |\n| endTime | LONG | **是** | Query end time, millisecond-level timestamp (the value is based on local time 23:59:59 seconds 999 milliseconds) |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsId\": 100001,\n    \"startTime\": 1714521600000,\n    \"endTime\": 1714607999999\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result[]\n    ├── eventType (STRING)\n    ├── updateSellerName (STRING)\n    ├── changeInfo (STRING)\n    └── updatedAt (STRING)\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`（OBJECT[]）\n\nPartner Response Example 中 **`result`** 直接为数组。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| eventType | STRING | Event type（操作事件类型） |\n| updateSellerName | STRING | Seller name who made the change |\n| changeInfo | STRING | Change information（变更内容描述） |\n| updatedAt | STRING | Update time（更新时间，Example 为字符串） |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_log_query.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"goodsId\": 100001, \"startTime\": 1714521600000, \"endTime\": 1714607999999}}'\n```\n\n**典型流程：** 排查某 **`goodsId`** 广告变更历史。\n\nFile v1.0.5:references/apis/temu-searchrec-ad-modify.md\n\n# 修改广告 — `temu.searchrec.ad.modify`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_modify.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=0b7140898262428eb8a4b28609112651 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.modify`，业务载荷放在 Body 的 `params` |\n\n**Description:** Modify ads (delete, pause, budget, ROAS, etc.).\n\n> **`status`**、**`modifyAdDTO`** 均为必填；**`status`** 决定 **`modifyAdDTO`** 中哪些字段生效。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    ├── modifyAdDTO (OBJECT, 必填)\n    │   ├── goodsId (LONG, 必填)\n    │   ├── budget (LONG, 否)\n    │   └── roas (LONG, 否)\n    └── status (INTEGER, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| modifyAdDTO | OBJECT | **是** | ModifyAdDTO request body |\n| status | INTEGER | **是** | Modification type: 1:delete, 2:pause, 3:open, 4:modify budget, 5:modify roas |\n\n#### `status`（必填）\n\n| 值 | 说明 |\n|----|------|\n| `1` | delete |\n| `2` | pause |\n| `3` | open |\n| `4` | modify budget |\n| `5` | modify roas |\n\n#### `modifyAdDTO`（OBJECT，必填）\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id（必填） |\n| budget | LONG | New budget（`status=4` 时使用） |\n| roas | LONG/NUMBER | New ROAS（`status=5` 时使用） |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"status\": 4,\n    \"modifyAdDTO\": {\n      \"goodsId\": 100001,\n      \"budget\": 8000,\n      \"roas\": 400\n    }\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    ├── successModifyProductNum (INTEGER)\n    └── modifyGoodsRespList[]\n        ├── goodsId, reason, success\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| successModifyProductNum | INTEGER | Number of successfully modified products |\n| modifyGoodsRespList | OBJECT[] | Per-goods modify result |\n\n#### `modifyGoodsRespList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| reason | STRING | Failure reason（失败时） |\n| success | BOOLEAN | Whether modify succeeded |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_modify.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"status\": 4, \"modifyAdDTO\": {\"goodsId\": 100001, \"budget\": 8000, \"roas\": 400}}}'\n```\n\n**典型流程：** 按 **`status`** 删除/暂停/开启/改预算/改 ROAS。\n\nFile v1.0.5:references/apis/temu-searchrec-ad-reports-mall-query.md\n\n# 店铺广告报表查询 — `temu.searchrec.ad.reports.mall.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_reports_mall_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=595f05856989480aa03abd58da203047 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.reports.mall.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query mall-level ad reports.\n\n> **`startTs`**、**`endTs`** 均为必填，毫秒时间戳（当地时区 0:00 至 23:59:59.999）。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    ├── startTs (LONG, 必填)\n    └── endTs (LONG, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| startTs | LONG | **是** | Query start time, millisecond level timestamp (the value starts at 0:00 local time) |\n| endTs | LONG | **是** | Query end time, millisecond-level timestamp (the value is based on local time 23:59:59 seconds 999 milliseconds) |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"startTs\": 1714521600000,\n    \"endTs\": 1714607999999\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    ├── summary (OBJECT) → ctr/cartCnt/clkCnt/… 各含 total/ad/netTotal/netAd.val\n    └── reportsItemList[] → goodsId, ts, roas, spend 等 { val }\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| summary | OBJECT | Mall-level aggregated metrics（店铺维度汇总） |\n| reportsItemList | OBJECT[] | Per-goods / per-time report items（明细列表） |\n\n#### `summary` 指标对象通用结构\n\n以下指标名在 **`summary`** 下各出现一次，每个指标均为 **OBJECT**，包含 **`total`**、**`ad`**、**`netTotal`**、**`netAd`** 四个子对象，每个子对象含 **`val`**（数值）：\n\n| 指标字段 | 说明 |\n|----------|------|\n| ctr | Click-through rate（点击率） |\n| cartCnt | Add-to-cart count（加购数） |\n| clkCnt | Click count（点击数） |\n| orderPayAmt | Order payment amount（订单支付金额） |\n| spend | Ad spend（广告花费） |\n| orderPayCnt | Order payment count（支付订单数） |\n| roas | Return on ad spend |\n| acos | Advertising cost of sales |\n| transactionCost | Transaction cost |\n| goodsNum | Goods number |\n| imprCnt | Impression count（曝光数） |\n| cvr | Conversion rate（转化率） |\n\n每个子路径示例：`summary.spend.ad.val`（广告归因花费）。\n\n#### `reportsItemList[]` 元素字段\n\n各指标多为 **`{ \"val\": <number> }`** 包装（Partner Response Example）：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| ts | LONG | Timestamp（报表时间点，毫秒） |\n| roas | OBJECT | ROAS，`val` |\n| totalRoas | OBJECT | Total ROAS，`val` |\n| netRoas | OBJECT | Net ROAS，`val` |\n| acos | OBJECT | ACOS，`val` |\n| totalAcos | OBJECT | Total ACOS，`val` |\n| netAcos | OBJECT | Net ACOS，`val` |\n| adSpend | OBJECT | Ad spend，`val` |\n| netAdSpend | OBJECT | Net ad spend，`val` |\n| orderPayAmt | OBJECT | Order pay amount，`val` |\n| totalOrderPayAmt | OBJECT | Total order pay amount，`val` |\n| netOrderPayAmt | OBJECT | Net order pay amount，`val` |\n| orderPayCnt | OBJECT | Order pay count，`val` |\n| totalOrderPayCnt | OBJECT | Total order pay count，`val` |\n| netOrderPayCnt | OBJECT | Net order pay count，`val` |\n| clkCnt | OBJECT | Click count，`val` |\n| totalClkCnt | OBJECT | Total click count，`val` |\n| ctr | OBJECT | CTR，`val` |\n| totalCtr | OBJECT | Total CTR，`val` |\n| cvr | OBJECT | CVR，`val` |\n| totalCvr | OBJECT | Total CVR，`val` |\n| cartCnt | OBJECT | Cart count，`val` |\n| imprCnt | OBJECT | Impression count，`val` |\n| totalImprCnt | OBJECT | Total impression count，`val` |\n| goodsNum | OBJECT | Goods number，`val` |\n| totalGoodsNum | OBJECT | Total goods number，`val` |\n| netGoodsNum | OBJECT | Net goods number，`val` |\n| transactionCost | OBJECT | Transaction cost，`val` |\n| totalTransactionCost | OBJECT | Total transaction cost，`val` |\n| netTransactionCost | OBJECT | Net transaction cost，`val` |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_reports_mall_query.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"startTs\": 1714521600000, \"endTs\": 1714607999999}}'\n```\n\n**典型流程：** 按时间窗拉店铺广告汇总与明细 → 单商品详情见 [ad.detail.query](./temu-searchrec-ad-detail-query.md)。\n\nFile v1.0.5:references/apis/temu-searchrec-ad-roas-pred.md\n\n# 广告 ROAS 预测 — `temu.searchrec.ad.roas.pred`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_roas_pred.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=dfff26bad8e94ed5abaaf5cdade50c26 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.roas.pred`，业务载荷放在 Body 的 `params` |\n\n**Description:** Predict ad ROAS for goods.\n\n> **`goodsInfoList`** 为必填。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    ├── goodsInfoList (OBJECT[], 必填)\n    ├── goodsInfoList[] (OBJECT[], 必填)\n    └──     └── goodsId (LONG, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsInfoList | OBJECT[] | **是** | Goods information list |\n\n#### `goodsInfoList[]`（Request Example 展开）\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsId | LONG | 是 | Goods id |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsInfoList\": [\n      {\n        \"goodsId\": 100001\n      }\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    └── queryAdBidResult[]\n        ├── goodsId (LONG)\n        └── predList[]\n            └── roas (STRING)\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| queryAdBidResult | OBJECT[] | Query ad bid / ROAS prediction results |\n\n#### `queryAdBidResult[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| predList | OBJECT[] | Prediction list |\n\n#### `predList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| roas | STRING | Predicted ROAS value（Partner Example 为字符串） |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_roas_pred.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"goodsInfoList\": [{\"goodsId\": 100001}]}}'\n```\n\n**典型流程：** 创建广告前可用本接口预估 ROAS → [ad.create](./temu-searchrec-ad-create.md)。\n\nArchive v1.0.4: 36 files, 46504 bytes\n\nFiles: references/access-token.md (4527b), references/api.md (5161b), references/apis/README.md (1301b), references/apis/temu-searchrec-ad-create.md (4617b), references/apis/temu-searchrec-ad-detail-query.md (5249b), references/apis/temu-searchrec-ad-goods-create-query.md (3518b), references/apis/temu-searchrec-ad-log-query.md (3811b), references/apis/temu-searchrec-ad-modify.md (4203b), references/apis/temu-searchrec-ad-reports-mall-query.md (6156b), references/apis/temu-searchrec-ad-roas-pred.md (3687b), references/authorization-flow.md (1186b), references/partner-us-catalog.md (3173b), scripts/_temu_auth_guide.py (6198b), scripts/_temu_common.py (12421b), scripts/_temu_token_store.py (4273b), scripts/_temu_us_common.py (3161b), scripts/_us_ads_script.py (510b), scripts/check_linkfox_token.py (1797b), scripts/get_temu_access_token.py (1843b), scripts/list_temu_access_tokens.py (652b), scripts/save_temu_access_token.py (1377b), scripts/temu_file_download.py (1681b), scripts/temu_proxy.py (2124b), scripts/temu_token_guide.py (1594b), scripts/temu_us_file_download.py (708b), scripts/temu_us_proxy.py (923b), scripts/us_ads_searchrec_ad_create.py (234b), scripts/us_ads_searchrec_ad_detail_query.py (258b), scripts/us_ads_searchrec_ad_goods_create_query.py (285b), scripts/us_ads_searchrec_ad_log_query.py (255b), scripts/us_ads_searchrec_ad_modify.py (234b), scripts/us_ads_searchrec_ad_reports_mall_query.py (282b), scripts/us_ads_searchrec_ad_roas_pred.py (249b), skill-card.md (3198b), SKILL.md (6711b), _meta.json (138b)\n\nFile v1.0.4:SKILL.md\n\n---\nname: linkfox-temu-ads-us\ndescription: Temu 美国站电商广告 Ads API，经 LinkFox 网关转发 Partner US Ads / 广告投放 相关 bg/temu 接口（广告计划、广告组、创意、报表、预算出价等，接口将按 Partner 文档逐条接入）。当用户提到 Temu US 广告、Ads、广告投放、广告计划、广告组、创意、出价、预算、广告报表、ad campaign、product-inventory 广告 时触发。商品管理用 linkfox-temu-manage-product-us；促销用 linkfox-temu-promotion-us；订单用 linkfox-temu-order-us。\n---\n\n# Temu 美国站 — 电商广告（Ads）\n\n本 skill（`linkfox-temu-ads-us`）覆盖 Partner Platform for US **Ads / 电商广告**（广告计划、投放、报表等；`menu_code` 与各 `sub_menu_code` 以 Partner 后台为准，见 [partner-us-catalog.md](./references/partner-us-catalog.md)）。\n\n已接入 **7** 条 Partner **Ads**（`temu.searchrec.ad.*`）接口，清单见 [partner-us-catalog.md](./references/partner-us-catalog.md)。\n\n**网关（本 skill 内置）**：\n\n| 能力 | 方法 | 路径 |\n|------|------|------|\n| 广告 OpenAPI（`us_ads_*`、`temu_us_proxy`） | POST | `https://tool-gateway.linkfox.com/temu/proxy` |\n| 加签文件下载 | POST | `https://tool-gateway.linkfox.com/temu/fileDownload` |\n\n## 相关 skill\n\n| 场景 | skill |\n|------|--------|\n| **广告 Ads**（本 skill） | **`linkfox-temu-ads-us`** |\n| 商品列表/详情/编辑/库存/上下架 | `linkfox-temu-manage-product-us` |\n| 促销/营销活动 | `linkfox-temu-promotion-us` |\n| 发品 | `linkfox-temu-add-product-us` |\n| 价格/供货价、定价单 | `linkfox-temu-price-us` |\n| 订单列表/详情 | `linkfox-temu-order-us` |\n| 退货与退款 | `linkfox-temu-returns-refunds-us` |\n| 网关与 Temu token | 本 skill `scripts/` |\n\n## 调用方式\n\n- **API 端点**：`POST /temu/proxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '<JSON 参数>' [--inline]`（可用脚本见上文脚本一览）\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-temu-ads-us-<timestamp>.json`（`<cwd>` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用以下措施来处理：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n### 措施\n- 优先采用skill内的 onboarding.md 引导解决问题。\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个skill并根据它的引导来处理。如未安装请先安装：\n    - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个skill。如需用户授权才可下载，要询问用户获得授权，你不能自己放弃下载。\n- 兜底措施：仅当前面两个措施经过所有努力都走不通时，才提示用户依据 https://skill.linkfox.com/linkfoxskills/guide.htm 指引获取API Key，或去 https://os.linkfox.com/ 补充积分。\n\n## 默认参数\n\n| 字段 | 默认 | 说明 |\n|------|------|------|\n| site | `us` | Partner US |\n| managementType | `semi-managed` | 半托管（具体接口以 Partner 文档为准） |\n| tokenPurpose | `product-inventory` | 卖家助手默认（若 Partner 某 Ads 接口要求其他 `tokenPurpose`，以该接口文档为准） |\n\n## 鉴权\n\n1. **LinkFox**：`LINKFOXAGENT_API_KEY` → Header `Authorization` + `Token`\n2. **Temu**：`accessToken` 或 `storeKey`（`storeKey` 时建议带 `tokenPurpose=product-inventory`）\n\n## Scripts\n\n| 脚本 | 说明 |\n|------|------|\n| `temu_us_proxy.py` | 任意 type |\n| `temu_us_file_download.py` | 加签下载 |\n| `us_ads_searchrec_ad_roas_pred.py` | `temu.searchrec.ad.roas.pred` |\n| `us_ads_searchrec_ad_reports_mall_query.py` | `temu.searchrec.ad.reports.mall.query` |\n| `us_ads_searchrec_ad_create.py` | `temu.searchrec.ad.create` |\n| `us_ads_searchrec_ad_detail_query.py` | `temu.searchrec.ad.detail.query` |\n| `us_ads_searchrec_ad_log_query.py` | `temu.searchrec.ad.log.query` |\n| `us_ads_searchrec_ad_goods_create_query.py` | `temu.searchrec.ad.goods.create.query` |\n| `us_ads_searchrec_ad_modify.py` | `temu.searchrec.ad.modify` |\n\n## 接入新接口（约定）\n\n你每提供一条 Partner 文档（`type` + `sub_menu_code` + URL + Request/Response 参数表），将：\n\n1. 新增 `references/apis/<type-slug>.md`（完整入参/出参层级）\n2. 新增 `scripts/us_ads_<slug>.py`（调用 `_us_ads_script.run_cli`）\n3. 更新 [partner-us-catalog.md](./references/partner-us-catalog.md)、[apis/README.md](./references/apis/README.md) 与本表\n\n## 示例（通用代理）\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\n\npython scripts/temu_us_proxy.py '{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"type\": \"<TEMU_API_TYPE>\",\n  \"params\": {\n    \"request\": {}\n  }\n}'\n```\n\n**Feedback：** `skillName`：`linkfox-temu-ads-us`\n\n## 网关与授权脚本\n\n| 脚本 | 说明 |\n|------|------|\n| `check_linkfox_token.py` | 校验 LinkFox 用户 Token |\n| `temu_token_guide.py` | Temu accessToken 后台授权步骤 |\n| `save_temu_access_token.py` | 保存 accessToken 到本地 |\n| `list_temu_access_tokens.py` | 列出已保存 token |\n| `get_temu_access_token.py` | 读取已保存 token |\n| `temu_proxy.py` | 通用网关转发（多 site） |\n| `temu_file_download.py` | 加签文件下载（多 site） |\n\n授权说明：[references/access-token.md](./references/access-token.md)\n\n## 积分消耗规则\n\n不消耗积分。\n\nFile v1.0.4:references/apis/README.md\n\n# Ads — 接口文档索引\n\n网关见 [../api.md](../api.md)；目录见 [../partner-us-catalog.md](../partner-us-catalog.md)。\n\n## 查询 / 预测\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.roas.pred` | 广告 ROAS 预测 | [temu-searchrec-ad-roas-pred.md](./apis/temu-searchrec-ad-roas-pred.md) |\n| `temu.searchrec.ad.goods.create.query` | 广告可创建商品查询 | [temu-searchrec-ad-goods-create-query.md](./apis/temu-searchrec-ad-goods-create-query.md) |\n\n## 创建 / 修改\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.create` | 创建广告 | [temu-searchrec-ad-create.md](./apis/temu-searchrec-ad-create.md) |\n| `temu.searchrec.ad.modify` | 修改广告 | [temu-searchrec-ad-modify.md](./apis/temu-searchrec-ad-modify.md) |\n\n## 报表 / 日志\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.reports.mall.query` | 店铺广告报表查询 | [temu-searchrec-ad-reports-mall-query.md](./apis/temu-searchrec-ad-reports-mall-query.md) |\n| `temu.searchrec.ad.detail.query` | 广告详情查询 | [temu-searchrec-ad-detail-query.md](./apis/temu-searchrec-ad-detail-query.md) |\n| `temu.searchrec.ad.log.query` | 广告操作日志查询 | [temu-searchrec-ad-log-query.md](./apis/temu-searchrec-ad-log-query.md) |\n\nFile v1.0.4:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-temu-ads-us\",\n  \"version\": \"1.0.4\",\n  \"publishedAt\": 1783945783938\n}\n\nFile v1.0.4:references/access-token.md\n\n# Temu accessToken 授权与获取\n\nTemu **没有** LinkFox 侧自动 OAuth；`accessToken` 须在 Temu 卖家后台「服务市场 → 授权管理」**手动复制**。与 `LINKFOXAGENT_API_KEY`（LinkFox 用户鉴权）是两套令牌。\n\n## 两种鉴权（勿混淆）\n\n| 令牌 | 用途 | 获取方式 |\n|------|------|----------|\n| **LinkFox 用户 Token** | 调用 `/temu/proxy`、`/temu/fileDownload` **必填** | `LINKFOXAGENT_API_KEY` 或请求 JSON 的 `token`；Header `Authorization` + `Token`（同 amazon-store-auth）（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理） |\n| **Temu accessToken** | Temu 业务 API（经紫鸟转发） | Temu 卖家后台授权后复制 |\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<your-key>\"\npython scripts/check_linkfox_token.py\n```\n\n## tokenPurpose 与场景\n\n| tokenPurpose | 店铺类型 | 推荐 site | 授权应用 |\n|--------------|----------|-----------|----------|\n| `product-inventory` | 半托管 | `cn` / `partner` | 酷鸟卖家助手 |\n| `order-shipping` | 半托管 | `us` / `global` / `eu` | Cyber-ERP酷鸟助手 |\n| `full-managed` | 全托管 | `cn` / `partner` | 酷鸟卖家助手 |\n| `local-native` | 本土（美/欧主体） | `us` 等 | Cyber-ERP |\n\n## 1. 半托管 — 商品/库存 Token\n\n1. 登录 [seller.kuajingmaihuo.com](https://seller.kuajingmaihuo.com) 或 [agentseller.temu.com](https://agentseller.temu.com)\n2. **系统管理** → **服务市场** → **授权管理**\n3. **获取授权** → 选择 **「酷鸟卖家助手」**\n4. 全选常规和特殊授权 → 确认 → **复制 access_token**\n5. 调用 API：`site=cn` 或 `partner`，`managementType=semi-managed`\n\n## 2. 半托管 — 订单/发货 Token\n\n1. 登录 Temu 卖家后台\n2. 右上角 **Seller Central** → 切换到目标区域（美区 / 欧区 / 全球）\n3. **服务市场** → **授权管理**\n4. **获取授权** → 选择 **「Cyber-ERP酷鸟助手」**\n5. 全选授权 → 确认 → 复制 token\n6. 调用 API：`site=us` / `global` / `eu`，`managementType=semi-managed`\n\n## 3. 全托管店铺\n\n1. 登录 Temu 平台\n2. **系统管理** → **服务市场** → **授权管理**\n3. **获取授权** → **「酷鸟卖家助手」** → 全选 → 复制 token\n4. 调用 API：`managementType=full-managed`，`site` 通常 `cn` 或 `partner`\n\n## 4. 本土店铺（美区、欧区主体）\n\n1. 登录 Temu\n2. **Apps And Services** → **Manage Your Apps**\n3. **Authorize a new app** → 搜索 **「Cyber-ERP」**\n4. 一般权限与敏感权限全选 → 确认 → 复制 token\n\n## 站点与 OpenAPI 网关\n\n| site | 说明 | Temu 网关 |\n|------|------|-----------|\n| cn | 中国站 | openapi.kuajingmaihuo.com |\n| partner | Partner 网关 | openapi-b-partner.temu.com |\n| us | 美国站 | openapi-b-us.temu.com |\n| global | 全球区 | openapi-b-global.temu.com |\n| eu | 欧洲站 | openapi-b-eu.temu.com |\n\n## 本地保存 Token（推荐）\n\n默认存储：`~/.linkfox/temu-access-tokens.json`（可用 `TEMU_TOKEN_STORE_PATH` 覆盖）。\n\n```bash\n# 查看授权步骤\npython scripts/temu_token_guide.py '{\"shopType\":\"semi-managed\",\"tokenPurpose\":\"product-inventory\",\"site\":\"cn\"}'\n\n# 保存 token\npython scripts/save_temu_access_token.py '{\n  \"storeKey\": \"my-shop\",\n  \"label\": \"中国半托管\",\n  \"site\": \"cn\",\n  \"managementType\": \"semi-managed\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"accessToken\": \"PASTE_TOKEN\"\n}'\n\n# 列出已保存（脱敏）\npython scripts/list_temu_access_tokens.py\n\n# 用 storeKey 调 API（无需每次粘贴 token）\npython scripts/temu_proxy.py '{\n  \"storeKey\": \"my-shop\",\n  \"site\": \"cn\",\n  \"managementType\": \"semi-managed\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"type\": \"bg.goods.category.mapping\",\n  \"params\": {\"goodsName\": \"测试\", \"goodsNameEn\": \"Test\"}\n}'\n```\n\n## 注意事项\n\n1. **子账号**：可能无法进入服务市场，需主账号授权。\n2. **多站点**：美国站、英国站等需分别登录对应后台获取 Token。\n3. **有效期**：Token 会过期，过期后重新在后台复制并 `save_temu_access_token.py`。\n4. **IP 白名单**：需联系紫鸟开放平台配置调用 IP。\n5. **参数小写**：`site`、`managementType` 必须小写。\n\n## 脚本一览\n\n| 脚本 | 说明 |\n|------|------|\n| `temu_token_guide.py` | 按店铺类型/用途输出授权步骤 |\n| `save_temu_access_token.py` | 保存 accessToken 到本地 |\n| `list_temu_access_tokens.py` | 列出已保存 token（默认脱敏）|\n| `get_temu_access_token.py` | 读取指定 store 的 token |\n\nFile v1.0.4:references/api.md\n\n# linkfox-temu-ads-us — API 参考\r\n\r\nTemu **美国站电商广告（Ads）**，经本 skill `temu_us_proxy`（`POST /temu/proxy`） 转发。Temu 的 `type` 写在 Body，**不是** URL 路径。\r\n\r\n> 网关与鉴权：本 skill `scripts/`（`LINKFOXAGENT_API_KEY`、`accessToken` / `storeKey`）。授权见 `references/access-token.md`。\r\n\r\n---\r\n\r\n## 调用规范\r\n\r\n| 项 | 说明 |\r\n|----|------|\r\n| 网关根地址 | `${LINKFOX_TOOL_GATEWAY}`（可用 `LINKFOX_TOOL_GATEWAY` / `TEMU_API_BASE_URL` / `STORE_API_BASE_URL` 覆盖） |\r\n| 广告 OpenAPI | `POST /temu/proxy` |\r\n| 加签文件下载 | `POST /temu/fileDownload`（`temu_us_file_download.py`） |\r\n| LinkFox 鉴权 | Header **`Authorization`** 与 **`Token`**（同值）；或 `LINKFOX_AGENT_API_KEY` / `LINKFOXAGENT_API_KEY`；或 JSON `token`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理） |\r\n| Temu 鉴权 | Body `accessToken`，或 `storeKey` + `site` + `managementType` + `tokenPurpose` |\r\n| 默认 | `site=us`，`managementType=semi-managed`，`tokenPurpose=product-inventory` |\r\n| 上游 OpenAPI（US） | `https://openapi-b-us.temu.com/openapi/router`（网关按 `site` 解析） |\r\n\r\n### 网关请求 Body（`/temu/proxy`）\r\n\r\n| 参数 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| site | string | 是 | `us`（本 skill 默认） |\r\n| managementType | string | 是 | `semi-managed` |\r\n| accessToken | string | 与 storeKey 二选一 | Temu 店铺令牌 |\r\n| storeKey | string | 与 accessToken 二选一 | `~/.linkfox/temu-access-tokens.json` 中的键 |\r\n| tokenPurpose | string | 否 | 建议 **`product-inventory`**（以各 Ads 接口 Partner 文档为准） |\r\n| type | string | 是 | Temu 接口名，如 Partner **Ads** 菜单下的 `bg.*` / `temu.*` |\r\n| params | object | 否 | 业务参数；多数接口业务块在 **`params.request`** |\r\n\r\n### 网关响应\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| body | string | Temu 原始 JSON 字符串；脚本解析为 `temuBody` |\r\n| code | integer | 网关错误码：`1002` 参数/Token，`1003` 转发失败 |\r\n\r\n解析顺序：**网关 `code`** → `JSON.parse(body)` → `success` / `errorCode` / `errorMsg` / `result`。\r\n\r\n### 脚本调用\r\n\r\n```bash\r\nexport LINKFOXAGENT_API_KEY=\"<key>\"\r\npython scripts/temu_us_proxy.py '{\"accessToken\":\"TOKEN\",\"tokenPurpose\":\"product-inventory\",\"type\":\"<API_TYPE>\",\"params\":{\"request\":{}}}'\r\n```\r\n\r\n业务字段可放在顶层或嵌套 `params`；含 `request` 时通常整体作为 `params` 转发。\r\n\r\n---\r\n\r\n## 接口一览\r\n\r\n完整 `sub_menu_code` 与 Partner 文档 URL 见 [partner-us-catalog.md](./partner-us-catalog.md)。\r\n\r\n**每个接口单独一份文档**：[apis/README.md](./apis/README.md)（随接入递增）。\r\n\r\n| type | 说明 | 文档 |\r\n|------|------|------|\r\n| `temu.searchrec.ad.roas.pred` | 广告 ROAS 预测 | [apis/temu-searchrec-ad-roas-pred.md](./apis/temu-searchrec-ad-roas-pred.md) |\r\n| `temu.searchrec.ad.reports.mall.query` | 店铺广告报表查询 | [apis/temu-searchrec-ad-reports-mall-query.md](./apis/temu-searchrec-ad-reports-mall-query.md) |\r\n| `temu.searchrec.ad.create` | 创建广告 | [apis/temu-searchrec-ad-create.md](./apis/temu-searchrec-ad-create.md) |\r\n| `temu.searchrec.ad.detail.query` | 广告详情查询 | [apis/temu-searchrec-ad-detail-query.md](./apis/temu-searchrec-ad-detail-query.md) |\r\n| `temu.searchrec.ad.log.query` | 广告操作日志查询 | [apis/temu-searchrec-ad-log-query.md](./apis/temu-searchrec-ad-log-query.md) |\r\n| `temu.searchrec.ad.goods.create.query` | 广告可创建商品查询 | [apis/temu-searchrec-ad-goods-create-query.md](./apis/temu-searchrec-ad-goods-create-query.md) |\r\n| `temu.searchrec.ad.modify` | 修改广告 | [apis/temu-searchrec-ad-modify.md](./apis/temu-searchrec-ad-modify.md) |\r\n\r\n---\r\n\r\n## 典型广告流程\r\n\r\n```text\r\n1. temu.searchrec.ad.goods.create.query     → 商品是否可创建广告\r\n2. temu.searchrec.ad.roas.pred              → ROAS 预测\r\n3. temu.searchrec.ad.create                 → 创建广告\r\n4. temu.searchrec.ad.detail.query           → 广告详情\r\n5. temu.searchrec.ad.modify                 → 暂停/改预算/改 ROAS/删除\r\n6. temu.searchrec.ad.reports.mall.query     → 店铺报表\r\n7. temu.searchrec.ad.log.query              → 操作日志\r\n```\r\n\r\n---\r\n\r\n## 与其他 Temu US skill 的区分\r\n\r\n| 能力 | skill |\r\n|------|--------|\r\n| **广告 Ads**（本 skill） | **`linkfox-temu-ads-us`** |\r\n| 促销/营销活动 | `linkfox-temu-promotion-us` |\r\n| 商品管理 | `linkfox-temu-manage-product-us` |\r\n| 价格/供货价 | `linkfox-temu-price-us` |\r\n| 订单 | `linkfox-temu-order-us` |\r\n\r\n---\r\n\r\n## 网关错误码\r\n\r\n| code | 说明 | 处理 |\r\n|------|------|------|\r\n| 1002 | 参数或 LinkFox Token 无效 | 修正参数与 `LINKFOXAGENT_API_KEY` |\r\n| 1003 | 转发失败 | 检查 Temu token、`tokenPurpose`、白名单、网络 |\r\n| 402 | HTTP 402 | 按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\r\n\r\n---\r\n\r\n## Feedback API\r\n\r\n- **POST** `https://skill-api.linkfox.com/api/v1/public/feedback`\r\n- `skillName`: **`linkfox-temu-ads-us`**\n\nFile v1.0.4:references/apis/temu-searchrec-ad-create.md\n\n# 创建广告 — `temu.searchrec.ad.create`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_create.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=7bc9231776304158a895e41a816b7805 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.create`，业务载荷放在 Body 的 `params` |\n\n**Description:** Create search recommendation ads.\n\n> **`createAdReqs`** 为必填；子字段在 Partner 表中为折叠行，按 **Request Example** 展开。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    └── createAdReqs[] (OBJECT[], 必填)\n        ├── goodsId (LONG, 必填)\n        ├── budget (LONG, 必填)\n        ├── roas (LONG, 必填)\n        └── roasType (INTEGER, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| createAdReqs | OBJECT[] | **是** | CreateAd parameter |\n\n#### `createAdReqs[]`（Request Example 展开）\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsId | LONG | 是 | Goods id |\n| budget | LONG | 是 | Ad budget（广告预算） |\n| roas | LONG/INTEGER | 是 | Target ROAS（目标 ROAS） |\n| roasType | INTEGER | 是 | ROAS type（ROAS 类型；具体枚举以 Partner 文档为准） |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"createAdReqs\": [\n      {\n        \"goodsId\": 100001,\n        \"budget\": 5000,\n        \"roas\": 350,\n        \"roasType\": 1\n      }\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    ├── alreadyCreatedGoodsNum (INTEGER)\n    ├── successCreateProductNum (INTEGER)\n    ├── successGoodsIdLists[] (LONG)\n    ├── createGoodsFailMap (OBJECT)\n    └── createGoodsFailObjList[]\n        ├── goodsId, reason, success\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| alreadyCreatedGoodsNum | INTEGER | Number of goods that already had ads created |\n| successCreateProductNum | INTEGER | Number of successfully created ad products |\n| successGoodsIdLists | LONG[] | Successfully created goods id list |\n| createGoodsFailMap | OBJECT | Fail map（Example 键为 `$key`/`$value`，表示失败 goodsId → 原因） |\n| createGoodsFailObjList | OBJECT[] | Fail list with details |\n\n#### `createGoodsFailObjList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| reason | STRING | Failure reason |\n| success | BOOLEAN | Whether succeeded（Example 中存在，以实际返回为准） |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_create.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"createAdReqs\": [{\"goodsId\": 100001, \"budget\": 5000, \"roas\": 350, \"roasType\": 1}]}}'\n```\n\n**典型流程：** 可先 [goods.create.query](./temu-searchrec-ad-goods-create-query.md) 确认可投 → [roas.pred](./temu-searchrec-ad-roas-pred.md) 预估 → 本接口创建。\n\nFile v1.0.4:references/apis/temu-searchrec-ad-detail-query.md\n\n# 广告详情查询 — `temu.searchrec.ad.detail.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_detail_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=66db5438c37446f49c122829489ac6d4 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.detail.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query ad detail by goods list.\n\n> **`goodsList`**（LONG[]）必填，单次传入 goodsId 列表。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    └── goodsList (LONG[], 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsList | LONG[] | **是** | Goods list |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsList\": [\n      100001,\n      100002\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    └── adsDetail[]\n        ├── goodsId, roas, budget, adShowStatus, adPhase\n        ├── summary (OBJECT)\n        ├── reportsSummaryDTO (OBJECT)\n        └── siteStatusInfoList[]\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| adsDetail | OBJECT[] | Ad detail per goods |\n\n#### `adsDetail[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| roas | LONG/NUMBER | Current ROAS setting |\n| budget | LONG/NUMBER | Ad budget |\n| adShowStatus | INTEGER | Ad show status |\n| adPhase | INTEGER | Ad phase |\n| summary | OBJECT | Metrics summary（结构同 [reports.mall.query](./temu-searchrec-ad-reports-mall-query.md) 之 `summary`） |\n| reportsSummaryDTO | OBJECT | Aggregated report metrics（全量汇总，字段均为 `*All.val`） |\n| siteStatusInfoList | OBJECT[] | Per-site ad status |\n\n#### `summary` 指标对象通用结构\n\n以下指标名在 **`summary`** 下各出现一次，每个指标均为 **OBJECT**，包含 **`total`**、**`ad`**、**`netTotal`**、**`netAd`** 四个子对象，每个子对象含 **`val`**（数值）：\n\n| 指标字段 | 说明 |\n|----------|------|\n| ctr | Click-through rate（点击率） |\n| cartCnt | Add-to-cart count（加购数） |\n| clkCnt | Click count（点击数） |\n| orderPayAmt | Order payment amount（订单支付金额） |\n| spend | Ad spend（广告花费） |\n| orderPayCnt | Order payment count（支付订单数） |\n| roas | Return on ad spend |\n| acos | Advertising cost of sales |\n| transactionCost | Transaction cost |\n| goodsNum | Goods number |\n| imprCnt | Impression count（曝光数） |\n| cvr | Conversion rate（转化率） |\n\n每个子路径示例：`summary.spend.ad.val`（广告归因花费）。\n\n#### `reportsSummaryDTO`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| clkCntAll | OBJECT | `val` — all clicks |\n| orderPayCntAll | OBJECT | `val` — all order pay count |\n| adSpendAll | OBJECT | `val` — all ad spend |\n| acosAll | OBJECT | `val` |\n| ctrAll | OBJECT | `val` |\n| imprCntAll | OBJECT | `val` |\n| orderPayAmtAll | OBJECT | `val` |\n| cartCntAll | OBJECT | `val` |\n| roasAll | OBJECT | `val` |\n\n#### `siteStatusInfoList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| adShowStatus | INTEGER | Ad show status for site |\n| forbidReason | STRING | Forbid reason if not shown |\n| siteNameList | STRING[] | Site names |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_detail_query.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"goodsList\": [100001, 100002]}}'\n```\n\n**典型流程：** 按 **`goodsList`** 查投放状态、预算、ROAS 与报表摘要。\n\nFile v1.0.4:references/apis/temu-searchrec-ad-goods-create-query.md\n\n# 广告可创建商品查询 — `temu.searchrec.ad.goods.create.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_goods_create_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=374d1f7fefdb4232b7b7a0239cb4465d |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.goods.create.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query whether goods can create ads.\n\n> **`goodsIdList`** 必填。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    └── goodsIdList (LONG[], 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsIdList | LONG[] | **是** | Goods id list |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsIdList\": [\n      100001,\n      100002\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    └── goodsInfoList[]\n        ├── goodsId (LONG)\n        └── grayReason[]\n            ├── type (INTEGER)\n            └── reason (STRING)\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsInfoList | OBJECT[] | Goods create-ad eligibility info |\n\n#### `goodsInfoList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| grayReason | OBJECT[] | Reasons if not eligible for ad creation（不可创建原因列表） |\n\n#### `grayReason[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| type | INTEGER | Reason type code |\n| reason | STRING | Reason description |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_goods_create_query.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"goodsIdList\": [100001, 100002]}}'\n```\n\n**典型流程：** 创建前检查商品是否可投 → [ad.create](./temu-searchrec-ad-create.md)。\n\nFile v1.0.4:references/apis/temu-searchrec-ad-log-query.md\n\n# 广告操作日志查询 — `temu.searchrec.ad.log.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_log_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=c2c5eda51c414e788bab914a297d1881 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.log.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query ad operation logs for a goods.\n\n> **`goodsId`**、**`startTime`**、**`endTime`** 均为必填（毫秒时间戳，规则同报表查询）。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    ├── goodsId (LONG, 必填)\n    ├── startTime (LONG, 必填)\n    └── endTime (LONG, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsId | LONG | **是** | Goods id |\n| startTime | LONG | **是** | Query start time, millisecond level timestamp (the value starts at 0:00 local time) |\n| endTime | LONG | **是** | Query end time, millisecond-level timestamp (the value is based on local time 23:59:59 seconds 999 milliseconds) |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsId\": 100001,\n    \"startTime\": 1714521600000,\n    \"endTime\": 1714607999999\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result[]\n    ├── eventType (STRING)\n    ├── updateSellerName (STRING)\n    ├── changeInfo (STRING)\n    └── updatedAt (STRING)\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`（OBJECT[]）\n\nPartner Response Example 中 **`result`** 直接为数组。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| eventType | STRING | Event type（操作事件类型） |\n| updateSellerName | STRING | Seller name who made the change |\n| changeInfo | STRING | Change information（变更内容描述） |\n| updatedAt | STRING | Update time（更新时间，Example 为字符串） |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_log_query.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"goodsId\": 100001, \"startTime\": 1714521600000, \"endTime\": 1714607999999}}'\n```\n\n**典型流程：** 排查某 **`goodsId`** 广告变更历史。\n\nFile v1.0.4:references/apis/temu-searchrec-ad-modify.md\n\n# 修改广告 — `temu.searchrec.ad.modify`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_modify.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=0b7140898262428eb8a4b28609112651 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.modify`，业务载荷放在 Body 的 `params` |\n\n**Description:** Modify ads (delete, pause, budget, ROAS, etc.).\n\n> **`status`**、**`modifyAdDTO`** 均为必填；**`status`** 决定 **`modifyAdDTO`** 中哪些字段生效。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    ├── modifyAdDTO (OBJECT, 必填)\n    │   ├── goodsId (LONG, 必填)\n    │   ├── budget (LONG, 否)\n    │   └── roas (LONG, 否)\n    └── status (INTEGER, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| modifyAdDTO | OBJECT | **是** | ModifyAdDTO request body |\n| status | INTEGER | **是** | Modification type: 1:delete, 2:pause, 3:open, 4:modify budget, 5:modify roas |\n\n#### `status`（必填）\n\n| 值 | 说明 |\n|----|------|\n| `1` | delete |\n| `2` | pause |\n| `3` | open |\n| `4` | modify budget |\n| `5` | modify roas |\n\n#### `modifyAdDTO`（OBJECT，必填）\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id（必填） |\n| budget | LONG | New budget（`status=4` 时使用） |\n| roas | LONG/NUMBER | New ROAS（`status=5` 时使用） |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"status\": 4,\n    \"modifyAdDTO\": {\n      \"goodsId\": 100001,\n      \"budget\": 8000,\n      \"roas\": 400\n    }\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    ├── successModifyProductNum (INTEGER)\n    └── modifyGoodsRespList[]\n        ├── goodsId, reason, success\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| successModifyProductNum | INTEGER | Number of successfully modified products |\n| modifyGoodsRespList | OBJECT[] | Per-goods modify result |\n\n#### `modifyGoodsRespList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| reason | STRING | Failure reason（失败时） |\n| success | BOOLEAN | Whether modify succeeded |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_modify.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"status\": 4, \"modifyAdDTO\": {\"goodsId\": 100001, \"budget\": 8000, \"roas\": 400}}}'\n```\n\n**典型流程：** 按 **`status`** 删除/暂停/开启/改预算/改 ROAS。\n\nFile v1.0.4:references/apis/temu-searchrec-ad-reports-mall-query.md\n\n# 店铺广告报表查询 — `temu.searchrec.ad.reports.mall.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_reports_mall_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=595f05856989480aa03abd58da203047 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.reports.mall.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query mall-level ad reports.\n\n> **`startTs`**、**`endTs`** 均为必填，毫秒时间戳（当地时区 0:00 至 23:59:59.999）。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    ├── startTs (LONG, 必填)\n    └── endTs (LONG, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| startTs | LONG | **是** | Query start time, millisecond level timestamp (the value starts at 0:00 local time) |\n| endTs | LONG | **是** | Query end time, millisecond-level timestamp (the value is based on local time 23:59:59 seconds 999 milliseconds) |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"startTs\": 1714521600000,\n    \"endTs\": 1714607999999\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    ├── summary (OBJECT) → ctr/cartCnt/clkCnt/… 各含 total/ad/netTotal/netAd.val\n    └── reportsItemList[] → goodsId, ts, roas, spend 等 { val }\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| summary | OBJECT | Mall-level aggregated metrics（店铺维度汇总） |\n| reportsItemList | OBJECT[] | Per-goods / per-time report items（明细列表） |\n\n#### `summary` 指标对象通用结构\n\n以下指标名在 **`summary`** 下各出现一次，每个指标均为 **OBJECT**，包含 **`total`**、**`ad`**、**`netTotal`**、**`netAd`** 四个子对象，每个子对象含 **`val`**（数值）：\n\n| 指标字段 | 说明 |\n|----------|------|\n| ctr | Click-through rate（点击率） |\n| cartCnt | Add-to-cart count（加购数） |\n| clkCnt | Click count（点击数） |\n| orderPayAmt | Order payment amount（订单支付金额） |\n| spend | Ad spend（广告花费） |\n| orderPayCnt | Order payment count（支付订单数） |\n| roas | Return on ad spend |\n| acos | Advertising cost of sales |\n| transactionCost | Transaction cost |\n| goodsNum | Goods number |\n| imprCnt | Impression count（曝光数） |\n| cvr | Conversion rate（转化率） |\n\n每个子路径示例：`summary.spend.ad.val`（广告归因花费）。\n\n#### `reportsItemList[]` 元素字段\n\n各指标多为 **`{ \"val\": <number> }`** 包装（Partner Response Example）：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| ts | LONG | Timestamp（报表时间点，毫秒） |\n| roas | OBJECT | ROAS，`val` |\n| totalRoas | OBJECT | Total ROAS，`val` |\n| netRoas | OBJECT | Net ROAS，`val` |\n| acos | OBJECT | ACOS，`val` |\n| totalAcos | OBJECT | Total ACOS，`val` |\n| netAcos | OBJECT | Net ACOS，`val` |\n| adSpend | OBJECT | Ad spend，`val` |\n| netAdSpend | OBJECT | Net ad spend，`val` |\n| orderPayAmt | OBJECT | Order pay amount，`val` |\n| totalOrderPayAmt | OBJECT | Total order pay amount，`val` |\n| netOrderPayAmt | OBJECT | Net order pay amount，`val` |\n| orderPayCnt | OBJECT | Order pay count，`val` |\n| totalOrderPayCnt | OBJECT | Total order pay count，`val` |\n| netOrderPayCnt | OBJECT | Net order pay count，`val` |\n| clkCnt | OBJECT | Click count，`val` |\n| totalClkCnt | OBJECT | Total click count，`val` |\n| ctr | OBJECT | CTR，`val` |\n| totalCtr | OBJECT | Total CTR，`val` |\n| cvr | OBJECT | CVR，`val` |\n| totalCvr | OBJECT | Total CVR，`val` |\n| cartCnt | OBJECT | Cart count，`val` |\n| imprCnt | OBJECT | Impression count，`val` |\n| totalImprCnt | OBJECT | Total impression count，`val` |\n| goodsNum | OBJECT | Goods number，`val` |\n| totalGoodsNum | OBJECT | Total goods number，`val` |\n| netGoodsNum | OBJECT | Net goods number，`val` |\n| transactionCost | OBJECT | Transaction cost，`val` |\n| totalTransactionCost | OBJECT | Total transaction cost，`val` |\n| netTransactionCost | OBJECT | Net transaction cost，`val` |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_reports_mall_query.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"startTs\": 1714521600000, \"endTs\": 1714607999999}}'\n```\n\n**典型流程：** 按时间窗拉店铺广告汇总与明细 → 单商品详情见 [ad.detail.query](./temu-searchrec-ad-detail-query.md)。\n\nFile v1.0.4:references/apis/temu-searchrec-ad-roas-pred.md\n\n# 广告 ROAS 预测 — `temu.searchrec.ad.roas.pred`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_roas_pred.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=dfff26bad8e94ed5abaaf5cdade50c26 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.roas.pred`，业务载荷放在 Body 的 `params` |\n\n**Description:** Predict ad ROAS for goods.\n\n> **`goodsInfoList`** 为必填。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    ├── goodsInfoList (OBJECT[], 必填)\n    ├── goodsInfoList[] (OBJECT[], 必填)\n    └──     └── goodsId (LONG, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsInfoList | OBJECT[] | **是** | Goods information list |\n\n#### `goodsInfoList[]`（Request Example 展开）\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsId | LONG | 是 | Goods id |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsInfoList\": [\n      {\n        \"goodsId\": 100001\n      }\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    └── queryAdBidResult[]\n        ├── goodsId (LONG)\n        └── predList[]\n            └── roas (STRING)\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| queryAdBidResult | OBJECT[] | Query ad bid / ROAS prediction results |\n\n#### `queryAdBidResult[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| predList | OBJECT[] | Prediction list |\n\n#### `predList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| roas | STRING | Predicted ROAS value（Partner Example 为字符串） |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_roas_pred.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"goodsInfoList\": [{\"goodsId\": 100001}]}}'\n```\n\n**典型流程：** 创建广告前可用本接口预估 ROAS → [ad.create](./temu-searchrec-ad-create.md)。\n\nArchive v1.0.3: 36 files, 45945 bytes\n\nFiles: references/access-token.md (4450b), references/api.md (5000b), references/apis/README.md (1301b), references/apis/temu-searchrec-ad-create.md (4617b), references/apis/temu-searchrec-ad-detail-query.md (5249b), references/apis/temu-searchrec-ad-goods-create-query.md (3518b), references/apis/temu-searchrec-ad-log-query.md (3811b), references/apis/temu-searchrec-ad-modify.md (4203b), references/apis/temu-searchrec-ad-reports-mall-query.md (6156b), references/apis/temu-searchrec-ad-roas-pred.md (3687b), references/authorization-flow.md (1186b), references/partner-us-catalog.md (3173b), scripts/_temu_auth_guide.py (6198b), scripts/_temu_common.py (12421b), scripts/_temu_token_store.py (4273b), scripts/_temu_us_common.py (3161b), scripts/_us_ads_script.py (510b), scripts/check_linkfox_token.py (1797b), scripts/get_temu_access_token.py (1843b), scripts/list_temu_access_tokens.py (652b), scripts/save_temu_access_token.py (1377b), scripts/temu_file_download.py (1681b), scripts/temu_proxy.py (2124b), scripts/temu_token_guide.py (1594b), scripts/temu_us_file_download.py (708b), scripts/temu_us_proxy.py (923b), scripts/us_ads_searchrec_ad_create.py (234b), scripts/us_ads_searchrec_ad_detail_query.py (258b), scripts/us_ads_searchrec_ad_goods_create_query.py (285b), scripts/us_ads_searchrec_ad_log_query.py (255b), scripts/us_ads_searchrec_ad_modify.py (234b), scripts/us_ads_searchrec_ad_reports_mall_query.py (282b), scripts/us_ads_searchrec_ad_roas_pred.py (249b), skill-card.md (3439b), SKILL.md (5689b), _meta.json (138b)\n\nFile v1.0.3:SKILL.md\n\n---\r\nname: linkfox-temu-ads-us\r\ndescription: Temu 美国站电商广告 Ads API，经 LinkFox 网关转发 Partner US Ads / 广告投放 相关 bg/temu 接口（广告计划、广告组、创意、报表、预算出价等，接口将按 Partner 文档逐条接入）。当用户提到 Temu US 广告、Ads、广告投放、广告计划、广告组、创意、出价、预算、广告报表、ad campaign、product-inventory 广告 时触发。商品管理用 linkfox-temu-manage-product-us；促销用 linkfox-temu-promotion-us；订单用 linkfox-temu-order-us。\r\n---\r\n\r\n# Temu 美国站 — 电商广告（Ads）\r\n\r\n本 skill（`linkfox-temu-ads-us`）覆盖 Partner Platform for US **Ads / 电商广告**（广告计划、投放、报表等；`menu_code` 与各 `sub_menu_code` 以 Partner 后台为准，见 [partner-us-catalog.md](./references/partner-us-catalog.md)）。\r\n\r\n已接入 **7** 条 Partner **Ads**（`temu.searchrec.ad.*`）接口，清单见 [partner-us-catalog.md](./references/partner-us-catalog.md)。\r\n\r\n**网关（本 skill 内置）**：\r\n\r\n| 能力 | 方法 | 路径 |\r\n|------|------|------|\r\n| 广告 OpenAPI（`us_ads_*`、`temu_us_proxy`） | POST | `https://tool-gateway.linkfox.com/temu/proxy` |\r\n| 加签文件下载 | POST | `https://tool-gateway.linkfox.com/temu/fileDownload` |\r\n\r\n## 相关 skill\r\n\r\n| 场景 | skill |\r\n|------|--------|\r\n| **广告 Ads**（本 skill） | **`linkfox-temu-ads-us`** |\r\n| 商品列表/详情/编辑/库存/上下架 | `linkfox-temu-manage-product-us` |\r\n| 促销/营销活动 | `linkfox-temu-promotion-us` |\r\n| 发品 | `linkfox-temu-add-product-us` |\r\n| 价格/供货价、定价单 | `linkfox-temu-price-us` |\r\n| 订单列表/详情 | `linkfox-temu-order-us` |\r\n| 退货与退款 | `linkfox-temu-returns-refunds-us` |\r\n| 网关与 Temu token | 本 skill `scripts/` |\r\n\r\n## 调用方式\r\n\r\n- **API 端点**：`POST /temu/proxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\r\n- **Python 脚本**：`python scripts/<脚本名>.py '<JSON 参数>' [--inline]`（可用脚本见上文脚本一览）\r\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\r\n\r\n**输出策略（脚本默认行为）**：\r\n- **始终**将完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-temu-ads-us-<timestamp>.json`（`<cwd>` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\r\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\r\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\r\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\r\n\r\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\r\n\r\n## 默认参数\r\n\r\n| 字段 | 默认 | 说明 |\r\n|------|------|------|\r\n| site | `us` | Partner US |\r\n| managementType | `semi-managed` | 半托管（具体接口以 Partner 文档为准） |\r\n| tokenPurpose | `product-inventory` | 卖家助手默认（若 Partner 某 Ads 接口要求其他 `tokenPurpose`，以该接口文档为准） |\r\n\r\n## 鉴权\r\n\r\n1. **LinkFox**：`LINKFOXAGENT_API_KEY` → Header `Authorization` + `Token`\r\n2. **Temu**：`accessToken` 或 `storeKey`（`storeKey` 时建议带 `tokenPurpose=product-inventory`）\r\n\r\n## Scripts\r\n\r\n| 脚本 | 说明 |\r\n|------|------|\r\n| `temu_us_proxy.py` | 任意 type |\r\n| `temu_us_file_download.py` | 加签下载 |\r\n| `us_ads_searchrec_ad_roas_pred.py` | `temu.searchrec.ad.roas.pred` |\r\n| `us_ads_searchrec_ad_reports_mall_query.py` | `temu.searchrec.ad.reports.mall.query` |\r\n| `us_ads_searchrec_ad_create.py` | `temu.searchrec.ad.create` |\r\n| `us_ads_searchrec_ad_detail_query.py` | `temu.searchrec.ad.detail.query` |\r\n| `us_ads_searchrec_ad_log_query.py` | `temu.searchrec.ad.log.query` |\r\n| `us_ads_searchrec_ad_goods_create_query.py` | `temu.searchrec.ad.goods.create.query` |\r\n| `us_ads_searchrec_ad_modify.py` | `temu.searchrec.ad.modify` |\r\n\r\n## 接入新接口（约定）\r\n\r\n你每提供一条 Partner 文档（`type` + `sub_menu_code` + URL + Request/Response 参数表），将：\r\n\r\n1. 新增 `references/apis/<type-slug>.md`（完整入参/出参层级）\r\n2. 新增 `scripts/us_ads_<slug>.py`（调用 `_us_ads_script.run_cli`）\r\n3. 更新 [partner-us-catalog.md](./references/partner-us-catalog.md)、[apis/README.md](./references/apis/README.md) 与本表\r\n\r\n## 示例（通用代理）\r\n\r\n```bash\r\nexport LINKFOXAGENT_API_KEY=\"<key>\"\r\n\r\npython scripts/temu_us_proxy.py '{\r\n  \"accessToken\": \"TOKEN\",\r\n  \"tokenPurpose\": \"product-inventory\",\r\n  \"type\": \"<TEMU_API_TYPE>\",\r\n  \"params\": {\r\n    \"request\": {}\r\n  }\r\n}'\r\n```\r\n\r\n**Feedback：** `skillName`：`linkfox-temu-ads-us`\r\n\r\n## 网关与授权脚本\r\n\r\n| 脚本 | 说明 |\r\n|------|------|\r\n| `check_linkfox_token.py` | 校验 LinkFox 用户 Token |\r\n| `temu_token_guide.py` | Temu accessToken 后台授权步骤 |\r\n| `save_temu_access_token.py` | 保存 accessToken 到本地 |\r\n| `list_temu_access_tokens.py` | 列出已保存 token |\r\n| `get_temu_access_token.py` | 读取已保存 token |\r\n| `temu_proxy.py` | 通用网关转发（多 site） |\r\n| `temu_file_download.py` | 加签文件下载（多 site） |\r\n\r\n授权说明：[references/access-token.md](./references/access-token.md)\n\nFile v1.0.3:references/apis/README.md\n\n# Ads — 接口文档索引\n\n网关见 [../api.md](../api.md)；目录见 [../partner-us-catalog.md](../partner-us-catalog.md)。\n\n## 查询 / 预测\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.roas.pred` | 广告 ROAS 预测 | [temu-searchrec-ad-roas-pred.md](./apis/temu-searchrec-ad-roas-pred.md) |\n| `temu.searchrec.ad.goods.create.query` | 广告可创建商品查询 | [temu-searchrec-ad-goods-create-query.md](./apis/temu-searchrec-ad-goods-create-query.md) |\n\n## 创建 / 修改\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.create` | 创建广告 | [temu-searchrec-ad-create.md](./apis/temu-searchrec-ad-create.md) |\n| `temu.searchrec.ad.modify` | 修改广告 | [temu-searchrec-ad-modify.md](./apis/temu-searchrec-ad-modify.md) |\n\n## 报表 / 日志\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.reports.mall.query` | 店铺广告报表查询 | [temu-searchrec-ad-reports-mall-query.md](./apis/temu-searchrec-ad-reports-mall-query.md) |\n| `temu.searchrec.ad.detail.query` | 广告详情查询 | [temu-searchrec-ad-detail-query.md](./apis/temu-searchrec-ad-detail-query.md) |\n| `temu.searchrec.ad.log.query` | 广告操作日志查询 | [temu-searchrec-ad-log-query.md](./apis/temu-searchrec-ad-log-query.md) |\n\nFile v1.0.3:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-temu-ads-us\",\n  \"version\": \"1.0.3\",\n  \"publishedAt\": 1783337898715\n}\n\nFile v1.0.3:references/access-token.md\n\n# Temu accessToken 授权与获取\n\nTemu **没有** LinkFox 侧自动 OAuth；`accessToken` 须在 Temu 卖家后台「服务市场 → 授权管理」**手动复制**。与 `LINKFOXAGENT_API_KEY`（LinkFox 用户鉴权）是两套令牌。\n\n## 两种鉴权（勿混淆）\n\n| 令牌 | 用途 | 获取方式 |\n|------|------|----------|\n| **LinkFox 用户 Token** | 调用 `/temu/proxy`、`/temu/fileDownload` **必填** | `LINKFOXAGENT_API_KEY` 或请求 JSON 的 `token`；Header `Authorization` + `Token`（同 amazon-store-auth） |\n| **Temu accessToken** | Temu 业务 API（经紫鸟转发） | Temu 卖家后台授权后复制 |\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<your-key>\"\npython scripts/check_linkfox_token.py\n```\n\n## tokenPurpose 与场景\n\n| tokenPurpose | 店铺类型 | 推荐 site | 授权应用 |\n|--------------|----------|-----------|----------|\n| `product-inventory` | 半托管 | `cn` / `partner` | 酷鸟卖家助手 |\n| `order-shipping` | 半托管 | `us` / `global` / `eu` | Cyber-ERP酷鸟助手 |\n| `full-managed` | 全托管 | `cn` / `partner` | 酷鸟卖家助手 |\n| `local-native` | 本土（美/欧主体） | `us` 等 | Cyber-ERP |\n\n## 1. 半托管 — 商品/库存 Token\n\n1. 登录 [seller.kuajingmaihuo.com](https://seller.kuajingmaihuo.com) 或 [agentseller.temu.com](https://agentseller.temu.com)\n2. **系统管理** → **服务市场** → **授权管理**\n3. **获取授权** → 选择 **「酷鸟卖家助手」**\n4. 全选常规和特殊授权 → 确认 → **复制 access_token**\n5. 调用 API：`site=cn` 或 `partner`，`managementType=semi-managed`\n\n## 2. 半托管 — 订单/发货 Token\n\n1. 登录 Temu 卖家后台\n2. 右上角 **Seller Central** → 切换到目标区域（美区 / 欧区 / 全球）\n3. **服务市场** → **授权管理**\n4. **获取授权** → 选择 **「Cyber-ERP酷鸟助手」**\n5. 全选授权 → 确认 → 复制 token\n6. 调用 API：`site=us` / `global` / `eu`，`managementType=semi-managed`\n\n## 3. 全托管店铺\n\n1. 登录 Temu 平台\n2. **系统管理** → **服务市场** → **授权管理**\n3. **获取授权** → **「酷鸟卖家助手」** → 全选 → 复制 token\n4. 调用 API：`managementType=full-managed`，`site` 通常 `cn` 或 `partner`\n\n## 4. 本土店铺（美区、欧区主体）\n\n1. 登录 Temu\n2. **Apps And Services** → **Manage Your Apps**\n3. **Authorize a new app** → 搜索 **「Cyber-ERP」**\n4. 一般权限与敏感权限全选 → 确认 → 复制 token\n\n## 站点与 OpenAPI 网关\n\n| site | 说明 | Temu 网关 |\n|------|------|-----------|\n| cn | 中国站 | openapi.kuajingmaihuo.com |\n| partner | Partner 网关 | openapi-b-partner.temu.com |\n| us | 美国站 | openapi-b-us.temu.com |\n| global | 全球区 | openapi-b-global.temu.com |\n| eu | 欧洲站 | openapi-b-eu.temu.com |\n\n## 本地保存 Token（推荐）\n\n默认存储：`~/.linkfox/temu-access-tokens.json`（可用 `TEMU_TOKEN_STORE_PATH` 覆盖）。\n\n```bash\n# 查看授权步骤\npython scripts/temu_token_guide.py '{\"shopType\":\"semi-managed\",\"tokenPurpose\":\"product-inventory\",\"site\":\"cn\"}'\n\n# 保存 token\npython scripts/save_temu_access_token.py '{\n  \"storeKey\": \"my-shop\",\n  \"label\": \"中国半托管\",\n  \"site\": \"cn\",\n  \"managementType\": \"semi-managed\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"accessToken\": \"PASTE_TOKEN\"\n}'\n\n# 列出已保存（脱敏）\npython scripts/list_temu_access_tokens.py\n\n# 用 storeKey 调 API（无需每次粘贴 token）\npython scripts/temu_proxy.py '{\n  \"storeKey\": \"my-shop\",\n  \"site\": \"cn\",\n  \"managementType\": \"semi-managed\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"type\": \"bg.goods.category.mapping\",\n  \"params\": {\"goodsName\": \"测试\", \"goodsNameEn\": \"Test\"}\n}'\n```\n\n## 注意事项\n\n1. **子账号**：可能无法进入服务市场，需主账号授权。\n2. **多站点**：美国站、英国站等需分别登录对应后台获取 Token。\n3. **有效期**：Token 会过期，过期后重新在后台复制并 `save_temu_access_token.py`。\n4. **IP 白名单**：需联系紫鸟开放平台配置调用 IP。\n5. **参数小写**：`site`、`managementType` 必须小写。\n\n## 脚本一览\n\n| 脚本 | 说明 |\n|------|------|\n| `temu_token_guide.py` | 按店铺类型/用途输出授权步骤 |\n| `save_temu_access_token.py` | 保存 accessToken 到本地 |\n| `list_temu_access_tokens.py` | 列出已保存 token（默认脱敏）|\n| `get_temu_access_token.py` | 读取指定 store 的 token |\n\nFile v1.0.3:references/api.md\n\n# linkfox-temu-ads-us — API 参考\r\n\r\nTemu **美国站电商广告（Ads）**，经本 skill `temu_us_proxy`（`POST /temu/proxy`） 转发。Temu 的 `type` 写在 Body，**不是** URL 路径。\r\n\r\n> 网关与鉴权：本 skill `scripts/`（`LINKFOXAGENT_API_KEY`、`accessToken` / `storeKey`）。授权见 `references/access-token.md`。\r\n\r\n---\r\n\r\n## 调用规范\r\n\r\n| 项 | 说明 |\r\n|----|------|\r\n| 网关根地址 | `${LINKFOX_TOOL_GATEWAY}`（可用 `LINKFOX_TOOL_GATEWAY` / `TEMU_API_BASE_URL` / `STORE_API_BASE_URL` 覆盖） |\r\n| 广告 OpenAPI | `POST /temu/proxy` |\r\n| 加签文件下载 | `POST /temu/fileDownload`（`temu_us_file_download.py`） |\r\n| LinkFox 鉴权 | Header **`Authorization`** 与 **`Token`**（同值）；或 `LINKFOX_AGENT_API_KEY` / `LINKFOXAGENT_API_KEY`；或 JSON `token` |\r\n| Temu 鉴权 | Body `accessToken`，或 `storeKey` + `site` + `managementType` + `tokenPurpose` |\r\n| 默认 | `site=us`，`managementType=semi-managed`，`tokenPurpose=product-inventory` |\r\n| 上游 OpenAPI（US） | `https://openapi-b-us.temu.com/openapi/router`（网关按 `site` 解析） |\r\n\r\n### 网关请求 Body（`/temu/proxy`）\r\n\r\n| 参数 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| site | string | 是 | `us`（本 skill 默认） |\r\n| managementType | string | 是 | `semi-managed` |\r\n| accessToken | string | 与 storeKey 二选一 | Temu 店铺令牌 |\r\n| storeKey | string | 与 accessToken 二选一 | `~/.linkfox/temu-access-tokens.json` 中的键 |\r\n| tokenPurpose | string | 否 | 建议 **`product-inventory`**（以各 Ads 接口 Partner 文档为准） |\r\n| type | string | 是 | Temu 接口名，如 Partner **Ads** 菜单下的 `bg.*` / `temu.*` |\r\n| params | object | 否 | 业务参数；多数接口业务块在 **`params.request`** |\r\n\r\n### 网关响应\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| body | string | Temu 原始 JSON 字符串；脚本解析为 `temuBody` |\r\n| code | integer | 网关错误码：`1002` 参数/Token，`1003` 转发失败 |\r\n\r\n解析顺序：**网关 `code`** → `JSON.parse(body)` → `success` / `errorCode` / `errorMsg` / `result`。\r\n\r\n### 脚本调用\r\n\r\n```bash\r\nexport LINKFOXAGENT_API_KEY=\"<key>\"\r\npython scripts/temu_us_proxy.py '{\"accessToken\":\"TOKEN\",\"tokenPurpose\":\"product-inventory\",\"type\":\"<API_TYPE>\",\"params\":{\"request\":{}}}'\r\n```\r\n\r\n业务字段可放在顶层或嵌套 `params`；含 `request` 时通常整体作为 `params` 转发。\r\n\r\n---\r\n\r\n## 接口一览\r\n\r\n完整 `sub_menu_code` 与 Partner 文档 URL 见 [partner-us-catalog.md](./partner-us-catalog.md)。\r\n\r\n**每个接口单独一份文档**：[apis/README.md](./apis/README.md)（随接入递增）。\r\n\r\n| type | 说明 | 文档 |\r\n|------|------|------|\r\n| `temu.searchrec.ad.roas.pred` | 广告 ROAS 预测 | [apis/temu-searchrec-ad-roas-pred.md](./apis/temu-searchrec-ad-roas-pred.md) |\r\n| `temu.searchrec.ad.reports.mall.query` | 店铺广告报表查询 | [apis/temu-searchrec-ad-reports-mall-query.md](./apis/temu-searchrec-ad-reports-mall-query.md) |\r\n| `temu.searchrec.ad.create` | 创建广告 | [apis/temu-searchrec-ad-create.md](./apis/temu-searchrec-ad-create.md) |\r\n| `temu.searchrec.ad.detail.query` | 广告详情查询 | [apis/temu-searchrec-ad-detail-query.md](./apis/temu-searchrec-ad-detail-query.md) |\r\n| `temu.searchrec.ad.log.query` | 广告操作日志查询 | [apis/temu-searchrec-ad-log-query.md](./apis/temu-searchrec-ad-log-query.md) |\r\n| `temu.searchrec.ad.goods.create.query` | 广告可创建商品查询 | [apis/temu-searchrec-ad-goods-create-query.md](./apis/temu-searchrec-ad-goods-create-query.md) |\r\n| `temu.searchrec.ad.modify` | 修改广告 | [apis/temu-searchrec-ad-modify.md](./apis/temu-searchrec-ad-modify.md) |\r\n\r\n---\r\n\r\n## 典型广告流程\r\n\r\n```text\r\n1. temu.searchrec.ad.goods.create.query     → 商品是否可创建广告\r\n2. temu.searchrec.ad.roas.pred              → ROAS 预测\r\n3. temu.searchrec.ad.create                 → 创建广告\r\n4. temu.searchrec.ad.detail.query           → 广告详情\r\n5. temu.searchrec.ad.modify                 → 暂停/改预算/改 ROAS/删除\r\n6. temu.searchrec.ad.reports.mall.query     → 店铺报表\r\n7. temu.searchrec.ad.log.query              → 操作日志\r\n```\r\n\r\n---\r\n\r\n## 与其他 Temu US skill 的区分\r\n\r\n| 能力 | skill |\r\n|------|--------|\r\n| **广告 Ads**（本 skill） | **`linkfox-temu-ads-us`** |\r\n| 促销/营销活动 | `linkfox-temu-promotion-us` |\r\n| 商品管理 | `linkfox-temu-manage-product-us` |\r\n| 价格/供货价 | `linkfox-temu-price-us` |\r\n| 订单 | `linkfox-temu-order-us` |\r\n\r\n---\r\n\r\n## 网关错误码\r\n\r\n| code | 说明 | 处理 |\r\n|------|------|------|\r\n| 1002 | 参数或 LinkFox Token 无效 | 修正参数与 `LINKFOXAGENT_API_KEY` |\r\n| 1003 | 转发失败 | 检查 Temu token、`tokenPurpose`、白名单、网络 |\r\n\r\n---\r\n\r\n## Feedback API\r\n\r\n- **POST** `https://skill-api.linkfox.com/api/v1/public/feedback`\r\n- `skillName`: **`linkfox-temu-ads-us`**\n\nFile v1.0.3:references/apis/temu-searchrec-ad-create.md\n\n# 创建广告 — `temu.searchrec.ad.create`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_create.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=7bc9231776304158a895e41a816b7805 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.create`，业务载荷放在 Body 的 `params` |\n\n**Description:** Create search recommendation ads.\n\n> **`createAdReqs`** 为必填；子字段在 Partner 表中为折叠行，按 **Request Example** 展开。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    └── createAdReqs[] (OBJECT[], 必填)\n        ├── goodsId (LONG, 必填)\n        ├── budget (LONG, 必填)\n        ├── roas (LONG, 必填)\n        └── roasType (INTEGER, 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| createAdReqs | OBJECT[] | **是** | CreateAd parameter |\n\n#### `createAdReqs[]`（Request Example 展开）\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsId | LONG | 是 | Goods id |\n| budget | LONG | 是 | Ad budget（广告预算） |\n| roas | LONG/INTEGER | 是 | Target ROAS（目标 ROAS） |\n| roasType | INTEGER | 是 | ROAS type（ROAS 类型；具体枚举以 Partner 文档为准） |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"createAdReqs\": [\n      {\n        \"goodsId\": 100001,\n        \"budget\": 5000,\n        \"roas\": 350,\n        \"roasType\": 1\n      }\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    ├── alreadyCreatedGoodsNum (INTEGER)\n    ├── successCreateProductNum (INTEGER)\n    ├── successGoodsIdLists[] (LONG)\n    ├── createGoodsFailMap (OBJECT)\n    └── createGoodsFailObjList[]\n        ├── goodsId, reason, success\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| alreadyCreatedGoodsNum | INTEGER | Number of goods that already had ads created |\n| successCreateProductNum | INTEGER | Number of successfully created ad products |\n| successGoodsIdLists | LONG[] | Successfully created goods id list |\n| createGoodsFailMap | OBJECT | Fail map（Example 键为 `$key`/`$value`，表示失败 goodsId → 原因） |\n| createGoodsFailObjList | OBJECT[] | Fail list with details |\n\n#### `createGoodsFailObjList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| reason | STRING | Failure reason |\n| success | BOOLEAN | Whether succeeded（Example 中存在，以实际返回为准） |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_create.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"createAdReqs\": [{\"goodsId\": 100001, \"budget\": 5000, \"roas\": 350, \"roasType\": 1}]}}'\n```\n\n**典型流程：** 可先 [goods.create.query](./temu-searchrec-ad-goods-create-query.md) 确认可投 → [roas.pred](./temu-searchrec-ad-roas-pred.md) 预估 → 本接口创建。\n\nFile v1.0.3:references/apis/temu-searchrec-ad-detail-query.md\n\n# 广告详情查询 — `temu.searchrec.ad.detail.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_detail_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=66db5438c37446f49c122829489ac6d4 |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.detail.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query ad detail by goods list.\n\n> **`goodsList`**（LONG[]）必填，单次传入 goodsId 列表。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    └── goodsList (LONG[], 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsList | LONG[] | **是** | Goods list |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsList\": [\n      100001,\n      100002\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    └── adsDetail[]\n        ├── goodsId, roas, budget, adShowStatus, adPhase\n        ├── summary (OBJECT)\n        ├── reportsSummaryDTO (OBJECT)\n        └── siteStatusInfoList[]\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| adsDetail | OBJECT[] | Ad detail per goods |\n\n#### `adsDetail[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| roas | LONG/NUMBER | Current ROAS setting |\n| budget | LONG/NUMBER | Ad budget |\n| adShowStatus | INTEGER | Ad show status |\n| adPhase | INTEGER | Ad phase |\n| summary | OBJECT | Metrics summary（结构同 [reports.mall.query](./temu-searchrec-ad-reports-mall-query.md) 之 `summary`） |\n| reportsSummaryDTO | OBJECT | Aggregated report metrics（全量汇总，字段均为 `*All.val`） |\n| siteStatusInfoList | OBJECT[] | Per-site ad status |\n\n#### `summary` 指标对象通用结构\n\n以下指标名在 **`summary`** 下各出现一次，每个指标均为 **OBJECT**，包含 **`total`**、**`ad`**、**`netTotal`**、**`netAd`** 四个子对象，每个子对象含 **`val`**（数值）：\n\n| 指标字段 | 说明 |\n|----------|------|\n| ctr | Click-through rate（点击率） |\n| cartCnt | Add-to-cart count（加购数） |\n| clkCnt | Click count（点击数） |\n| orderPayAmt | Order payment amount（订单支付金额） |\n| spend | Ad spend（广告花费） |\n| orderPayCnt | Order payment count（支付订单数） |\n| roas | Return on ad spend |\n| acos | Advertising cost of sales |\n| transactionCost | Transaction cost |\n| goodsNum | Goods number |\n| imprCnt | Impression count（曝光数） |\n| cvr | Conversion rate（转化率） |\n\n每个子路径示例：`summary.spend.ad.val`（广告归因花费）。\n\n#### `reportsSummaryDTO`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| clkCntAll | OBJECT | `val` — all clicks |\n| orderPayCntAll | OBJECT | `val` — all order pay count |\n| adSpendAll | OBJECT | `val` — all ad spend |\n| acosAll | OBJECT | `val` |\n| ctrAll | OBJECT | `val` |\n| imprCntAll | OBJECT | `val` |\n| orderPayAmtAll | OBJECT | `val` |\n| cartCntAll | OBJECT | `val` |\n| roasAll | OBJECT | `val` |\n\n#### `siteStatusInfoList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| adShowStatus | INTEGER | Ad show status for site |\n| forbidReason | STRING | Forbid reason if not shown |\n| siteNameList | STRING[] | Site names |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partner 文档；修正入参或权限后重试 |\n| 230013000 | business exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230014000 | system exception | 见 Partner 文档；修正入参或权限后重试 |\n| 230016701 | has no permission | 见 Partner 文档；修正入参或权限后重试 |\n| 230016103 | not signed because of not main account | 见 Partner 文档；修正入参或权限后重试 |\n\n---\n\n## 脚本\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<key>\"\npython scripts/us_ads_searchrec_ad_detail_query.py '{\"accessToken\": \"TOKEN\", \"tokenPurpose\": \"product-inventory\", \"request\": {\"goodsList\": [100001, 100002]}}'\n```\n\n**典型流程：** 按 **`goodsList`** 查投放状态、预算、ROAS 与报表摘要。\n\nFile v1.0.3:references/apis/temu-searchrec-ad-goods-create-query.md\n\n# 广告可创建商品查询 — `temu.searchrec.ad.goods.create.query`\n\n| 项 | 值 |\n|----|-----|\n| **脚本** | `scripts/us_ads_searchrec_ad_goods_create_query.py` |\n| **Partner 文档** | https://partner-us.temu.com/documentation?menu_code=1e72b5cceef545ec8f9652b9e56dd054&sub_menu_code=374d1f7fefdb4232b7b7a0239cb4465d |\n| **网关** | `POST /temu/proxy`，`type`=`temu.searchrec.ad.goods.create.query`，业务载荷放在 Body 的 `params` |\n\n**Description:** Query whether goods can create ads.\n\n> **`goodsIdList`** 必填。\n\n> **网关鉴权字段**由本 skill 网关脚本处理；业务参数见下方 **`request`**。建议使用 **`tokenPurpose=product-inventory`**，**`managementType=semi-managed`**。\n\n---\n\n## Request 结构（官方顶层）\n\n```text\nparams\n└── request (OBJECT, 选填)\n    └── goodsIdList (LONG[], 必填)\n```\n\n### `request` 内字段\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| goodsIdList | LONG[] | **是** | Goods id list |\n\n> 官方 Request 表将顶层 **`request`** 标为选填（False）；标 **必填** 的字段须在 **`params.request`** 中提供。\n\n### 网关 `params` 写法\n\n```json\n{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"goodsIdList\": [\n      100001,\n      100002\n    ]\n  }\n}\n```\n\n---\n\n## Response（Temu `body` 解析后）\n\nPartner **Response** 嵌套子行在导出 HTML 中多为折叠状态，下列层级按 **Response 表 + Response Example** 全部展开。\n\n```text\nresponse\n├── success / errorCode / errorMsg\n└── result\n    └── goodsInfoList[]\n        ├── goodsId (LONG)\n        └── grayReason[]\n            ├── type (INTEGER)\n            └── reason (STRING)\n```\n\n### 顶层字段\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| success | BOOLEAN | success |\n| errorCode | INTEGER | error code |\n| errorMsg | STRING | error message |\n| result | OBJECT 或 OBJECT[] | 业务结果（见下表） |\n\n### `result`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsInfoList | OBJECT[] | Goods create-ad eligibility info |\n\n#### `goodsInfoList[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| goodsId | LONG | Goods id |\n| grayReason | OBJECT[] | Reasons if not eligible for ad creation（不可创建原因列表） |\n\n#### `grayReason[]`\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| type | INTEGER | Reason type code |\n| reason | STRING | Reason description |\n\n---\n\n## Error Code（Partner 表）\n\n| errorCode | errorMsg | Error SOP / 处理建议 |\n|-----------|----------|----------------------|\n| 230012000 | bad query params | 见 Partner 文档；修正入参或权限后重试 |\n| 230012003 | unmatch mall and goods | 见 Partn\n\nArchive v1.0.2: 35 files, 44216 bytes\n\nFiles: references/access-token.md (4450b), references/api.md (5000b), references/apis/README.md (1301b), references/apis/temu-searchrec-ad-create.md (4617b), references/apis/temu-searchrec-ad-detail-query.md (5249b), references/apis/temu-searchrec-ad-goods-create-query.md (3518b), references/apis/temu-searchrec-ad-log-query.md (3811b), references/apis/temu-searchrec-ad-modify.md (4203b), references/apis/temu-searchrec-ad-reports-mall-query.md (6156b), references/apis/temu-searchrec-ad-roas-pred.md (3687b), references/authorization-flow.md (1186b), references/partner-us-catalog.md (3173b), scripts/_temu_auth_guide.py (6198b), scripts/_temu_common.py (12421b), scripts/_temu_token_store.py (4273b), scripts/_temu_us_common.py (3161b), scripts/_us_ads_script.py (510b), scripts/check_linkfox_token.py (1797b), scripts/get_temu_access_token.py (1843b), scripts/list_temu_access_tokens.py (652b), scripts/save_temu_access_token.py (1377b), scripts/temu_file_download.py (1681b), scripts/temu_proxy.py (2124b), scripts/temu_token_guide.py (1594b), scripts/temu_us_file_download.py (708b), scripts/temu_us_proxy.py (923b), scripts/us_ads_searchrec_ad_create.py (234b), scripts/us_ads_searchrec_ad_detail_query.py (258b), scripts/us_ads_searchrec_ad_goods_create_query.py (285b), scripts/us_ads_searchrec_ad_log_query.py (255b), scripts/us_ads_searchrec_ad_modify.py (234b), scripts/us_ads_searchrec_ad_reports_mall_query.py (282b), scripts/us_ads_searchrec_ad_roas_pred.py (249b), SKILL.md (5689b), _meta.json (138b)\n\nArchive v1.0.0: 36 files, 42911 bytes\n\nFiles: references/access-token.md (4450b), references/api.md (4849b), references/apis/README.md (1301b), references/apis/temu-searchrec-ad-create.md (4617b), references/apis/temu-searchrec-ad-detail-query.md (5249b), references/apis/temu-searchrec-ad-goods-create-query.md (3518b), references/apis/temu-searchrec-ad-log-query.md (3811b), references/apis/temu-searchrec-ad-modify.md (4203b), references/apis/temu-searchrec-ad-reports-mall-query.md (6156b), references/apis/temu-searchrec-ad-roas-pred.md (3687b), references/authorization-flow.md (1186b), references/partner-us-catalog.md (3173b), scripts/_temu_auth_guide.py (6198b), scripts/_temu_common.py (5593b), scripts/_temu_token_store.py (4237b), scripts/_temu_us_common.py (3044b), scripts/_us_ads_script.py (510b), scripts/check_linkfox_token.py (1797b), scripts/get_temu_access_token.py (1843b), scripts/list_temu_access_tokens.py (652b), scripts/save_temu_access_token.py (1377b), scripts/temu_file_download.py (1595b), scripts/temu_proxy.py (2027b), scripts/temu_token_guide.py (1594b), scripts/temu_us_file_download.py (639b), scripts/temu_us_proxy.py (844b), scripts/us_ads_searchrec_ad_create.py (234b), scripts/us_ads_searchrec_ad_detail_query.py (258b), scripts/us_ads_searchrec_ad_goods_create_query.py (285b), scripts/us_ads_searchrec_ad_log_query.py (255b), scripts/us_ads_searchrec_ad_modify.py (234b), scripts/us_ads_searchrec_ad_reports_mall_query.py (282b), scripts/us_ads_searchrec_ad_roas_pred.py (249b), skill-card.md (3283b), SKILL.md (4667b), _meta.json (138b)","readmeExcerpt":"Skill: Temu美国站-广告 Owner: linkfox-ai Summary: Temu 美国站电商广告 Ads API，经 LinkFox 网关转发 Partner US Ads / 广告投放 相关 bg/temu 接口（广告计划、广告组、创意、报表、预算出价等，接口将按 Partner 文档逐条接入）。当用户提到 Temu US 广告、Ads、广告投放、广告计划、广告组、创意、出价、预算、广告报表、ad campaign、product-inventory 广告 时触发。商品管理用 linkfox-temu-manage-product-us；促销用 linkfox-temu-promotion-us；订单用 linkfox-temu-order-us。 Tags: latest:1.0.6 Version history: v1.0.6 | 2026-08-14T15:12:02.359Z | user Upda","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"export LINKFOXAGENT_API_KEY=\"<key>\"\n\npython scripts/temu_us_proxy.py '{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"type\": \"<TEMU_API_TYPE>\",\n  \"params\": {\n    \"request\": {}\n  }\n}'"},{"language":"bash","snippet":"export LINKFOXAGENT_API_KEY=\"<your-key>\"\npython scripts/check_linkfox_token.py"},{"language":"bash","snippet":"# 查看授权步骤\npython scripts/temu_token_guide.py '{\"shopType\":\"semi-managed\",\"tokenPurpose\":\"product-inventory\",\"site\":\"cn\"}'\n\n# 保存 token\npython scripts/save_temu_access_token.py '{\n  \"storeKey\": \"my-shop\",\n  \"label\": \"中国半托管\",\n  \"site\": \"cn\",\n  \"managementType\": \"semi-managed\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"accessToken\": \"PASTE_TOKEN\"\n}'\n\n# 列出已保存（脱敏）\npython scripts/list_temu_access_tokens.py\n\n# 用 storeKey 调 API（无需每次粘贴 token）\npython scripts/temu_proxy.py '{\n  \"storeKey\": \"my-shop\",\n  \"site\": \"cn\",\n  \"managementType\": \"semi-managed\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"type\": \"bg.goods.category.mapping\",\n  \"params\": {\"goodsName\": \"测试\", \"goodsNameEn\": \"Test\"}\n}'"},{"language":"text","snippet":"params\n└── request (OBJECT, 选填)\n    └── createAdReqs[] (OBJECT[], 必填)\n        ├── goodsId (LONG, 必填)\n        ├── budget (LONG, 必填)\n        ├── roas (LONG, 必填)\n        └── roasType (INTEGER, 必填)"},{"language":"json","snippet":"{\n  \"accessToken\": \"TOKEN\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"request\": {\n    \"createAdReqs\": [\n      {\n        \"goodsId\": 100001,\n        \"budget\": 5000,\n        \"roas\": 350,\n        \"roasType\": 1\n      }\n    ]\n  }\n}"},{"language":"text","snippet":"response\n├── success / errorCode / errorMsg\n└── result\n    ├── alreadyCreatedGoodsNum (INTEGER)\n    ├── successCreateProductNum (INTEGER)\n    ├── successGoodsIdLists[] (LONG)\n    ├── createGoodsFailMap (OBJECT)\n    └── createGoodsFailObjList[]\n        ├── goodsId, reason, success"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: linkfox-temu-ads-us\ndescription: Temu 美国站电商广告 Ads API，经 LinkFox 网关转发 Partner US Ads / 广告投放 相关 bg/temu 接口（广告计划、广告组、创意、报表、预算出价等，接口将按 Partner 文档逐条接入）。当用户提到 Temu US 广告、Ads、广告投放、广告计划、广告组、创意、出价、预算、广告报表、ad campaign、product-inventory 广告 时触发。商品管理用 linkfox-temu-manage-product-us；促销用 linkfox-temu-promotion-us；订单用 linkfox-temu-order-us。\n---\n\n# Temu 美国站 — 电商广告（Ads）\n\n本 skill（`linkfox-temu-ads-us`）覆盖 Partner Platform for US **Ads / 电商广告**（广告计划、投放、报表等；`menu_code` 与各 `sub_menu_code` 以 Partner 后台为准，见 [partner-us-catalog.md](./references/partner-us-catalog.md)）。\n\n已接入 **7** 条 Partner **Ads**（`temu.searchrec.ad.*`）接口，清单见 [partner-us-catalog.md](./references/partner-us-catalog.md)。\n\n**网关（本 skill 内置）**：\n\n| 能力 | 方法 | 路径 |\n|------|------|------|\n| 广告 OpenAPI（`us_ads_*`、`temu_us_proxy`） | POST | `https://tool-gateway.linkfox.com/temu/proxy` |\n| 加签文件下载 | POST | `https://tool-gateway.linkfox.com/temu/fileDownload` |\n\n## 相关 skill\n\n| 场景 | skill |\n|------|--------|\n| **广告 Ads**（本 skill） | **`linkfox-temu-ads-us`** |\n| 商品列表/详情/编辑/库存/上下架 | `linkfox-temu-manage-product-us` |\n| 促销/营销活动 | `linkfox-temu-promotion-us` |\n| 发品 | `linkfox-temu-add-product-us` |\n| 价格/供货价、定价单 | `linkfox-temu-price-us` |\n| 订单列表/详情 | `linkfox-temu-order-us` |\n| 退货与退款 | `linkfox-temu-returns-refunds-us` |\n| 网关与 Temu token | 本 skill `scripts/` |\n\n## 调用方式\n\n- **API 端点**：`POST /temu/proxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '<JSON 参数>' [--inline]`（可用脚本见上文脚本一览）\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-temu-ads-us-<timestamp>.json`（`<cwd>` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n## 默认参数\n\n| 字段 | 默认 | 说明 |\n|------|------|------|\n| site | `us` | Partner US |\n| managementType | `semi-managed` | 半托管（具体接口以 Partner 文档为准） |\n| tokenPurpose | `product-inventory` | 卖家助手默认（若 Partner 某 Ads 接口要求其他 `tokenPurpose`，以该接口文档为准） |\n\n## 鉴权\n\n1. **LinkFox**：`LINKFOXAGENT_API_KEY` → Header `Authorization` + `Token`\n2. **Temu**：`accessToken` 或 `storeKey`（`storeKey` 时建议带 `tokenPurpose=product-inventory`）\n\n## Scripts\n\n| 脚本 | 说明 |\n|------|------|\n| `temu_us_proxy.py` | 任意 type |\n| `temu_us_file_download.py` | 加签下载 |\n| `us_ads_searchrec_ad_roas_pred.py` | `temu.searchrec.ad.roas.pred` |\n| `us_ads_searchrec_ad_reports_mall_query.py` | `temu.searchrec.ad.reports.mall.query` |\n| `us_ads_searchrec_ad_create.py` | `t"},{"path":"references/apis/README.md","content":"# Ads — 接口文档索引\n\n网关见 [../api.md](../api.md)；目录见 [../partner-us-catalog.md](../partner-us-catalog.md)。\n\n## 查询 / 预测\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.roas.pred` | 广告 ROAS 预测 | [temu-searchrec-ad-roas-pred.md](./apis/temu-searchrec-ad-roas-pred.md) |\n| `temu.searchrec.ad.goods.create.query` | 广告可创建商品查询 | [temu-searchrec-ad-goods-create-query.md](./apis/temu-searchrec-ad-goods-create-query.md) |\n\n## 创建 / 修改\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.create` | 创建广告 | [temu-searchrec-ad-create.md](./apis/temu-searchrec-ad-create.md) |\n| `temu.searchrec.ad.modify` | 修改广告 | [temu-searchrec-ad-modify.md](./apis/temu-searchrec-ad-modify.md) |\n\n## 报表 / 日志\n\n| type | 说明 | 文档 |\n|------|------|------|\n| `temu.searchrec.ad.reports.mall.query` | 店铺广告报表查询 | [temu-searchrec-ad-reports-mall-query.md](./apis/temu-searchrec-ad-reports-mall-query.md) |\n| `temu.searchrec.ad.detail.query` | 广告详情查询 | [temu-searchrec-ad-detail-query.md](./apis/temu-searchrec-ad-detail-query.md) |\n| `temu.searchrec.ad.log.query` | 广告操作日志查询 | [temu-searchrec-ad-log-query.md](./apis/temu-searchrec-ad-log-query.md) |"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-temu-ads-us\",\n  \"version\": \"1.0.6\",\n  \"publishedAt\": 1786720322359\n}"},{"path":"references/access-token.md","content":"# Temu accessToken 授权与获取\n\nTemu **没有** LinkFox 侧自动 OAuth；`accessToken` 须在 Temu 卖家后台「服务市场 → 授权管理」**手动复制**。与 `LINKFOXAGENT_API_KEY`（LinkFox 用户鉴权）是两套令牌。\n\n## 两种鉴权（勿混淆）\n\n| 令牌 | 用途 | 获取方式 |\n|------|------|----------|\n| **LinkFox 用户 Token** | 调用 `/temu/proxy`、`/temu/fileDownload` **必填** | `LINKFOXAGENT_API_KEY` 或请求 JSON 的 `token`；Header `Authorization` + `Token`（同 amazon-store-auth）（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理） |\n| **Temu accessToken** | Temu 业务 API（经紫鸟转发） | Temu 卖家后台授权后复制 |\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<your-key>\"\npython scripts/check_linkfox_token.py\n```\n\n## tokenPurpose 与场景\n\n| tokenPurpose | 店铺类型 | 推荐 site | 授权应用 |\n|--------------|----------|-----------|----------|\n| `product-inventory` | 半托管 | `cn` / `partner` | 酷鸟卖家助手 |\n| `order-shipping` | 半托管 | `us` / `global` / `eu` | Cyber-ERP酷鸟助手 |\n| `full-managed` | 全托管 | `cn` / `partner` | 酷鸟卖家助手 |\n| `local-native` | 本土（美/欧主体） | `us` 等 | Cyber-ERP |\n\n## 1. 半托管 — 商品/库存 Token\n\n1. 登录 [seller.kuajingmaihuo.com](https://seller.kuajingmaihuo.com) 或 [agentseller.temu.com](https://agentseller.temu.com)\n2. **系统管理** → **服务市场** → **授权管理**\n3. **获取授权** → 选择 **「酷鸟卖家助手」**\n4. 全选常规和特殊授权 → 确认 → **复制 access_token**\n5. 调用 API：`site=cn` 或 `partner`，`managementType=semi-managed`\n\n## 2. 半托管 — 订单/发货 Token\n\n1. 登录 Temu 卖家后台\n2. 右上角 **Seller Central** → 切换到目标区域（美区 / 欧区 / 全球）\n3. **服务市场** → **授权管理**\n4. **获取授权** → 选择 **「Cyber-ERP酷鸟助手」**\n5. 全选授权 → 确认 → 复制 token\n6. 调用 API：`site=us` / `global` / `eu`，`managementType=semi-managed`\n\n## 3. 全托管店铺\n\n1. 登录 Temu 平台\n2. **系统管理** → **服务市场** → **授权管理**\n3. **获取授权** → **「酷鸟卖家助手」** → 全选 → 复制 token\n4. 调用 API：`managementType=full-managed`，`site` 通常 `cn` 或 `partner`\n\n## 4. 本土店铺（美区、欧区主体）\n\n1. 登录 Temu\n2. **Apps And Services** → **Manage Your Apps**\n3. **Authorize a new app** → 搜索 **「Cyber-ERP」**\n4. 一般权限与敏感权限全选 → 确认 → 复制 token\n\n## 站点与 OpenAPI 网关\n\n| site | 说明 | Temu 网关 |\n|------|------|-----------|\n| cn | 中国站 | openapi.kuajingmaihuo.com |\n| partner | Partner 网关 | openapi-b-partner.temu.com |\n| us | 美国站 | openapi-b-us.temu.com |\n| global | 全球区 | openapi-b-global.temu.com |\n| eu | 欧洲站 | openapi-b-eu.temu.com |\n\n## 本地保存 Token（推荐）\n\n默认存储：`~/.linkfox/temu-access-tokens.json`（可用 `TEMU_TOKEN_STORE_PATH` 覆盖）。\n\n```bash\n# 查看授权步骤\npython scripts/temu_token_guide.py '{\"shopType\":\"semi-managed\",\"tokenPurpose\":\"product-inventory\",\"site\":\"cn\"}'\n\n# 保存 token\npython scripts/save_temu_access_token.py '{\n  \"storeKey\": \"my-shop\",\n  \"label\": \"中国半托管\",\n  \"site\": \"cn\",\n  \"managementType\": \"semi-managed\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"accessToken\": \"PASTE_TOKEN\"\n}'\n\n# 列出已保存（脱敏）\npython scripts/list_temu_access_tokens.py\n\n# 用 storeKey 调 API（无需每次粘贴 token）\npython scripts/temu_proxy.py '{\n  \"storeKey\": \"my-shop\",\n  \"site\": \"cn\",\n  \"managementType\": \"semi-managed\",\n  \"tokenPurpose\": \"product-inventory\",\n  \"type\": \"bg.goods.category.mapping\",\n  \"params\": {\"goodsName\": \"测试\", \"goodsNameEn\": \"Test\"}\n}'\n```\n\n## 注意事项\n\n1. **子账号**：可能无法进入服务市场，需主账号授权。\n2. **多站点**：美国站、英国站等需分别登录对应后台获取 Token。\n3. **有效期**：Token 会过期，过期后重新在后台复制并 `save_"},{"path":"references/api.md","content":"# linkfox-temu-ads-us — API 参考\r\n\r\nTemu **美国站电商广告（Ads）**，经本 skill `temu_us_proxy`（`POST /temu/proxy`） 转发。Temu 的 `type` 写在 Body，**不是** URL 路径。\r\n\r\n> 网关与鉴权：本 skill `scripts/`（`LINKFOXAGENT_API_KEY`、`accessToken` / `storeKey`）。授权见 `references/access-token.md`。\r\n\r\n---\r\n\r\n## 调用规范\r\n\r\n| 项 | 说明 |\r\n|----|------|\r\n| 网关根地址 | `${LINKFOX_TOOL_GATEWAY}`（可用 `LINKFOX_TOOL_GATEWAY` / `TEMU_API_BASE_URL` / `STORE_API_BASE_URL` 覆盖） |\r\n| 广告 OpenAPI | `POST /temu/proxy` |\r\n| 加签文件下载 | `POST /temu/fileDownload`（`temu_us_file_download.py`） |\r\n| LinkFox 鉴权 | Header **`Authorization`** 与 **`Token`**（同值）；或 `LINKFOX_AGENT_API_KEY` / `LINKFOXAGENT_API_KEY`；或 JSON `token`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理） |\r\n| Temu 鉴权 | Body `accessToken`，或 `storeKey` + `site` + `managementType` + `tokenPurpose` |\r\n| 默认 | `site=us`，`managementType=semi-managed`，`tokenPurpose=product-inventory` |\r\n| 上游 OpenAPI（US） | `https://openapi-b-us.temu.com/openapi/router`（网关按 `site` 解析） |\r\n\r\n### 网关请求 Body（`/temu/proxy`）\r\n\r\n| 参数 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| site | string | 是 | `us`（本 skill 默认） |\r\n| managementType | string | 是 | `semi-managed` |\r\n| accessToken | string | 与 storeKey 二选一 | Temu 店铺令牌 |\r\n| storeKey | string | 与 accessToken 二选一 | `~/.linkfox/temu-access-tokens.json` 中的键 |\r\n| tokenPurpose | string | 否 | 建议 **`product-inventory`**（以各 Ads 接口 Partner 文档为准） |\r\n| type | string | 是 | Temu 接口名，如 Partner **Ads** 菜单下的 `bg.*` / `temu.*` |\r\n| params | object | 否 | 业务参数；多数接口业务块在 **`params.request`** |\r\n\r\n### 网关响应\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| body | string | Temu 原始 JSON 字符串；脚本解析为 `temuBody` |\r\n| code | integer | 网关错误码：`1002` 参数/Token，`1003` 转发失败 |\r\n\r\n解析顺序：**网关 `code`** → `JSON.parse(body)` → `success` / `errorCode` / `errorMsg` / `result`。\r\n\r\n### 脚本调用\r\n\r\n```bash\r\nexport LINKFOXAGENT_API_KEY=\"<key>\"\r\npython scripts/temu_us_proxy.py '{\"accessToken\":\"TOKEN\",\"tokenPurpose\":\"product-inventory\",\"type\":\"<API_TYPE>\",\"params\":{\"request\":{}}}'\r\n```\r\n\r\n业务字段可放在顶层或嵌套 `params`；含 `request` 时通常整体作为 `params` 转发。\r\n\r\n---\r\n\r\n## 接口一览\r\n\r\n完整 `sub_menu_code` 与 Partner 文档 URL 见 [partner-us-catalog.md](./partner-us-catalog.md)。\r\n\r\n**每个接口单独一份文档**：[apis/README.md](./apis/README.md)（随接入递增）。\r\n\r\n| type | 说明 | 文档 |\r\n|------|------|------|\r\n| `temu.searchrec.ad.roas.pred` | 广告 ROAS 预测 | [apis/temu-searchrec-ad-roas-pred.md](./apis/temu-searchrec-ad-roas-pred.md) |\r\n| `temu.searchrec.ad.reports.mall.query` | 店铺广告报表查询 | [apis/temu-searchrec-ad-reports-mall-query.md](./apis/temu-searchrec-ad-reports-mall-query.md) |\r\n| `temu.searchrec.ad.create` | 创建广告 | [apis/temu-searchrec-ad-create.md](./apis/temu-searchrec-ad-create.md) |\r\n| `temu.searchrec.ad.detail.query` | 广告详情查询 | [apis/temu-searchrec-ad-detail-query.md](./apis/temu-searchrec-ad-detail-query.md) |\r\n| `temu.searchrec.ad.log.query` | 广告操作日志查询 | [apis/temu-searchrec-ad-log-query.md](./apis/temu-searchrec-ad-log-query.md) |\r\n| `temu.searchrec.ad.goods.create.query` | 广告可创建商品查询 | [apis/temu-searchrec-ad-goods-create-query.md](./apis/temu-searchre"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1159,"uniquenessScore":34,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T16:45:17.635Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T16:45:17.635Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:52:15.857Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}