linkfox-shopee-store-ads
管理已授权 Shopee(虾皮)店铺的站内广告,支持广告账户余额与开关查询、推广商品及关键词推荐、手动商品广告和 GMS 活动创建与编辑,以及 CPC、商品活动和 GMS 效果分析。适用于店铺推广维护、预算与 ROI 参考、广告表现查询;广告授权独立于 ERP 授权,不适用于商品刊登、联盟营销 AMS、自动商品广告或其他平台广告。
SKILL.mdskills/linkfox-shopee-store-ads/SKILL.md
GitHubShopee 店铺站内广告管理
适用范围
适用
查看和维护已授权 Shopee 店铺的站内广告。用户希望了解广告余额、商品推广、关键词、广告活动、CPC 效果或 ROI 时使用,无需明确提及 Ads。
场景速查
| 用户表达 | 查询场景 |
|---|---|
| 查广告余额和自动充值开关 | 账户状态:展示广告余额与开关。 |
| 哪些商品和关键词适合推广 | 推广准备:展示推荐商品、关键词、预算和 ROI 参考。 |
| 创建或调整手动商品广告 | 广告维护:创建活动或修改设置、关键词。 |
| 看广告每天或每小时的表现 | 效果报表:区分全部 CPC 与指定商品活动。 |
| 检查并维护 GMS 广告 | GMS:查询资格、创建或编辑活动、查看活动及商品效果。 |
边界
店铺授权由 linkfox-shopee-store-auth 处理,商品刊登使用 linkfox-shopee-store-product,联盟营销 AMS(module=127)使用 linkfox-shopee-store-ams;Amazon 广告使用相应 Amazon 广告技能。本站内广告范围不包含自动商品广告。
接口清单
| 接口 | 端点 | 接口文档 | 对应脚本 | 说明 |
|---|---|---|---|---|
检查 GMS 商品广告活动创建资格(check_create_gms_product_campaign_eligibility) |
POST /shopee/developerProxy -> GET path:api/v2/ads/check_create_gms_product_campaign_eligibility |
references/apis/check-create-gms-product-campaign-eligibility.md | scripts/check_create_gms_product_campaign_eligibility.py |
检查 GMS 商品广告活动创建资格。 |
创建 GMS 商品广告活动(create_gms_product_campaign) |
POST /shopee/developerProxy -> POST path:api/v2/ads/create_gms_product_campaign |
references/apis/create-gms-product-campaign.md | scripts/create_gms_product_campaign.py |
创建 GMS 商品广告活动。 |
创建手动选品商品广告(create_manual_product_ads) |
POST /shopee/developerProxy -> POST path:api/v2/ads/create_manual_product_ads |
references/apis/create-manual-product-ads.md | scripts/create_manual_product_ads.py |
创建手动选品商品广告。 |
编辑 GMS 商品活动(edit_gms_item_product_campaign) |
POST /shopee/developerProxy -> POST path:api/v2/ads/edit_gms_item_product_campaign |
references/apis/edit-gms-item-product-campaign.md | scripts/edit_gms_item_product_campaign.py |
编辑 GMS 商品活动。 |
编辑 GMS 商品广告活动(edit_gms_product_campaign) |
POST /shopee/developerProxy -> POST path:api/v2/ads/edit_gms_product_campaign |
references/apis/edit-gms-product-campaign.md | scripts/edit_gms_product_campaign.py |
编辑 GMS 商品广告活动。 |
编辑手动商品广告关键词(edit_manual_product_ad_keywords) |
POST /shopee/developerProxy -> POST path:api/v2/ads/edit_manual_product_ad_keywords |
references/apis/edit-manual-product-ad-keywords.md | scripts/edit_manual_product_ad_keywords.py |
编辑手动商品广告关键词。 |
编辑手动商品广告(edit_manual_product_ads) |
POST /shopee/developerProxy -> POST path:api/v2/ads/edit_manual_product_ads |
references/apis/edit-manual-product-ads.md | scripts/edit_manual_product_ads.py |
编辑手动商品广告。 |
查询 Ads Facil 计划店铺费率(get_ads_facil_shop_rate) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_ads_facil_shop_rate |
references/apis/get-ads-facil-shop-rate.md | scripts/get_ads_facil_shop_rate.py |
查询 Ads Facil 计划店铺费率。 |
查询全部 CPC 广告每日效果(get_all_cpc_ads_daily_performance) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_all_cpc_ads_daily_performance |
references/apis/get-all-cpc-ads-daily-performance.md | scripts/get_all_cpc_ads_daily_performance.py |
查询全部 CPC 广告每日效果。 |
查询全部 CPC 广告小时效果(get_all_cpc_ads_hourly_performance) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_all_cpc_ads_hourly_performance |
references/apis/get-all-cpc-ads-hourly-performance.md | scripts/get_all_cpc_ads_hourly_performance.py |
查询全部 CPC 广告小时效果。 |
查询新建商品广告预算建议(get_create_product_ad_budget_suggestion) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_create_product_ad_budget_suggestion |
references/apis/get-create-product-ad-budget-suggestion.md | scripts/get_create_product_ad_budget_suggestion.py |
查询新建商品广告预算建议。 |
查询 GMS 广告活动效果(get_gms_campaign_performance) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_gms_campaign_performance |
references/apis/get-gms-campaign-performance.md | scripts/get_gms_campaign_performance.py |
查询 GMS 广告活动效果。 |
查询 GMS 商品效果(get_gms_item_performance) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_gms_item_performance |
references/apis/get-gms-item-performance.md | scripts/get_gms_item_performance.py |
查询 GMS 商品效果。 |
查询商品广告活动每日效果(get_product_campaign_daily_performance) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_product_campaign_daily_performance |
references/apis/get-product-campaign-daily-performance.md | scripts/get_product_campaign_daily_performance.py |
查询商品广告活动每日效果。 |
查询商品广告活动小时效果(get_product_campaign_hourly_performance) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_product_campaign_hourly_performance |
references/apis/get-product-campaign-hourly-performance.md | scripts/get_product_campaign_hourly_performance.py |
查询商品广告活动小时效果。 |
查询商品级广告活动 ID 列表(get_product_level_campaign_id_list) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_product_level_campaign_id_list |
references/apis/get-product-level-campaign-id-list.md | scripts/get_product_level_campaign_id_list.py |
查询商品级广告活动 ID 列表。 |
查询商品广告活动设置(get_product_level_campaign_setting_info) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_product_level_campaign_setting_info |
references/apis/get-product-level-campaign-setting-info.md | scripts/get_product_level_campaign_setting_info.py |
查询商品广告活动设置。 |
查询推荐 ROI 目标(get_product_recommended_roi_target) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_product_recommended_roi_target |
references/apis/get-product-recommended-roi-target.md | scripts/get_product_recommended_roi_target.py |
查询推荐 ROI 目标。 |
查询推荐推广商品(get_recommended_item_list) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_recommended_item_list |
references/apis/get-recommended-item-list.md | scripts/get_recommended_item_list.py |
查询推荐推广商品。 |
查询推荐广告关键词(get_recommended_keyword_list) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_recommended_keyword_list |
references/apis/get-recommended-keyword-list.md | scripts/get_recommended_keyword_list.py |
查询推荐广告关键词。 |
查询自动充值与 Campaign Surge 开关(get_shop_toggle_info) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_shop_toggle_info |
references/apis/get-shop-toggle-info.md | scripts/get_shop_toggle_info.py |
查询自动充值与 Campaign Surge 开关。 |
查询广告账户实时余额(get_total_balance) |
POST /shopee/developerProxy -> GET path:api/v2/ads/get_total_balance |
references/apis/get-total-balance.md | scripts/get_total_balance.py |
查询广告账户实时余额。 |
查询 GMS 用户删除商品列表(list_gms_user_deleted_item) |
POST /shopee/developerProxy -> GET path:api/v2/ads/list_gms_user_deleted_item |
references/apis/list-gms-user-deleted-item.md | scripts/list_gms_user_deleted_item.py |
查询 GMS 用户删除商品列表。 |
前置条件
先完成广告授权并确定目标店铺:依赖 linkfox-shopee-store-auth;先运行 python scripts/check_auth_dependency.py 检查依赖。不要在本技能内实现授权或令牌逻辑。店铺还须在 Shopee 侧开通广告能力,并非所有站点、店铺均可用。依赖检查、授权识别和接口要求见 references/api.md。
业务执行流程
- 每次任务开头,通过认证技能的
authorized_stores.py检查目标店铺的广告授权。仅有 ERP 记录或历史空值不能视为广告已授权;缺失时使用该技能的authorize_url.py发起广告授权,完成后再执行本技能。用户只需广告时,无需先开通 ERP;授权链接有效期见 接口参考。 - 查余额与推荐:先查询账户余额,再按任务查询推荐商品或关键词。
- 创建手动商品广告:先查询预算建议,准备完整广告资料并创建,再按用户要求查询商品活动每日效果;维护现有活动时查询活动 ID 与设置后,编辑广告或关键词。
- GMS:先检查创建资格,再按任务创建或编辑活动、调整商品活动,查询用户删除的商品或活动及商品效果。
- 效果分析:按用户目标选择全部 CPC、商品活动或 GMS 的报表,明确每日与小时粒度。依据 各接口定义 判断网关、上游与业务结果后展示数据。
执行方式
- 直接调用接口:接口端点、完整参数、响应和错误码见
references/api.md。 - 脚本调用(推荐):
python <脚本路径> '<JSON 参数>' [--inline] [--no-cache]。 - 成本与调用约束:本工具不消耗算力 (限时)。同一会话、同一参数组合默认只调用一次,23 个业务脚本不读取或写入响应缓存。失败或空结果时,不得自动变更参数、翻页或连续试探;需要继续查询时,先说明查询范围与目的。
输出策略
- 始终保存完整响应,目标路径为
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-shopee-store-ads-<接口标识>-<timestamp>.json。<cwd>为脚本运行时的工作目录,<session>优先取环境变量SESSION_ID,用于聚合同一任务的数据。禁止写入/tmp,当前目录不可写时应报错。 - 响应体不超过 8 KB:保存后,将完整 JSON 打印到标准输出。
- 响应体超过 8 KB:保存后,标准输出仅展示摘要,包括顶层字段、响应中的顶层常见计数(如
total、costToken)、最大列表字段的长度和前 3 条样本。 - 添加
--inline可强制全量打印到标准输出,同时仍保存文件。
先通过摘要判断数据是否足够。需要具体字段时,优先使用 jq 或 ConvertFrom-Json 从保存的 JSON 文件按需提取,避免将整份响应载入上下文。
执行规则
算力消耗预估
不消耗算力 (限时)。
声明:算力消耗以实际扣除为准;如因需要调整算力消耗标准,恕不另行通知。最终解释权归 LinkFox 官方所有。
解决认证和算力问题
出现以下情况时,按 references/onboarding.md 的指引处理:
- 未配置接口密钥:
LINKFOX_AGENT_API_KEY和LINKFOXAGENT_API_KEY均为空。 - HTTP 状态码为
401或402。 - 响应提示算力或余额不足、计费不足、配额超限、套餐到期或需要充值。英文错误消息也按其含义判断。
约束与建议
- 本技能的缓存行为:23 个业务脚本始终禁用响应缓存;公共调用器仍可能创建空的
.cache目录。同一会话应避免重复请求。运行约定见 references/api.md。 - AD 与 ERP 分离:广告 Token 与 ERP Token 独立,店铺出现在授权列表中不等于已经取得广告授权。凭证和转发约定见 references/api.md。
- 识别产品范围:手动商品广告支持创建、编辑广告和关键词;GMS 支持活动、商品与效果查询。自动商品广告
create_auto_product_ads、edit_auto_product_ads因官方标注即将下线而未纳入。 - 清晰展示结果:注明目标店铺、时间范围与报表粒度,用表格呈现响应实际包含的余额、推荐或效果数据;币种、单位及空值按返回内容说明,不补造缺失指标。
- 区分查询和维护:创建与编辑会改变广告投放;依据用户已明确的目标准备内容,说明实际返回的操作结果。写入防重、错误处理及脚本兼容行为见 references/api.md。
- 核对字段定义:各操作的官方字段说明链接见对应接口文档及脚本,未定义的业务字段须核对后再使用。
使用示例
查看广告账户与推荐
用户:查这家店的广告余额,再看看推荐推广的商品。
检查广告授权后查询余额与推荐商品,展示目标店铺、余额和推荐结果。
创建或维护手动商品广告
用户:按这些推广资料创建广告,之后查看效果。
查询预算建议,按用户资料准备完整广告内容,提交创建并解释返回结果,再按用户指定范围查看商品活动效果。
查看 GMS 与 CPC 效果
用户:查看指定时间内 GMS 和 CPC 广告的表现。
根据用户需要分别查询 GMS 活动或商品效果、全部 CPC 或指定商品活动报表,区分时间粒度及统计范围。
使用反馈
当技能有BUG,或技能描述有错误/疏漏/歧义/表述模糊,或技能结果与用户预期不符,或用户表达不满/赞扬,或发现其他可改进之处时,按 references/api.md#Feedback 的指引反馈,不要打断用户当前流程。
更多优质、专业的跨境电商技能,请访问 LinkFox Skill。