Campaign服务API：149美元＋1%

现行新合同按账户约定IANA时区自然月后结：149美元基础费按有效服务日折算，加登记Campaign有效日期实际媒体消耗的1%。一个App、一个广告平台、USD、一个约定时区，多Campaign基础费只收一次，不扣用户结果额度。旧额度合同继续原条款，迁移须明确未来生效日、客户接受凭据和预付款余额处理。

1. 创建应用与确认服务范围

负责人创建应用时设置billing_mode="campaign"；权威MMP是billing_provider="af"或"adjust"，与Google Ads等广告平台字段分开。先确认授权来源、字段、历史范围、处理容量、成本定义、可用验证模型和合同。管理接口为POST /api/v2/apps/APP/ACTION，负责人使用授权会话并带tenant_id；客户管理操作使用拥有configure权限的会话。写请求使用application/json并遵守同源会话保护，/v2为等价别名。机器Token与登录密码分开。

2. 登记并核验Campaign

campaign-scope请求示例如下，所有账户和Campaign ID保持字符串。客户确认完整Campaign采用，负责人通过campaign-approve核验账户归属后才生效；待审批不产生交付权、费用或缺报义务。名称仅展示。observation范围只用于客户自报实际指标，不开放预测，不产生比例费。修订不可覆盖，未来effective_date到达后才应用信号或结果窗口。

{
  "id": "scope-a",
  "revision": 1,
  "platform": "google_ads",
  "ad_account_id": "90071992547409931234",
  "campaign_id": "campaign-a",
  "campaign_name": "Value test",
  "kind": "delivery",
  "signal_definition_id": "net-d90",
  "signal_version": "1",
  "optimization_setup": "Customer-managed value optimization",
  "adoption_confirmed": true,
  "result_data_from": "2026-10-01T00:00:00.000Z"
}

新开通与恢复在下一当地00:00或更晚约定日生效。登记数据、兼容模型及服务就绪后，由负责人启动公司一次30×24小时试用，应付始终为0。试用结束不自动付费；客户明确接受并由负责人开通，才进入自然月后结。

3. 全量授权上报、内部处理与结果拉取

下方raw-v2章节继续用于数据运输。需匹配Campaign的权威买量安装记录还需包含下面三个字段，精确匹配登记对象；不得按Campaign名称猜账户。未知归因保留内部，不能强行交付。授权范围内未登记数据可内部分析，不能把接入缩为只收登记Campaign。

"ad_platform": "google_ads",
"ad_account_id": "90071992547409931234",
"campaign_id": "campaign-a"

负责人执行load/daily处理。内部生成预测不等于已交付；users、单用户、results、insights、export、sync只开放符合范围且有独立具体版本回执的数据。按next_cursor完成分页，再保存sync_token拉增量，410时重建快照。读取成功不等于客户已回传或平台已接收，也不作为1%费用乘数。

4. API或CSV提交每日实际消耗

机器使用绑定App的batches:write Token，通过POST /api/v2/apps/APP/campaign-spend提交，带Authorization: Bearer YOUR_WRITE_TOKEN；不要求results:read。它不能审批、核对、确认账单、定稿或核款。结果读取另用results:read Token。请求可为JSON rows或JSON内的csv字符串；每批1—5000日明细，整批原子接收，不部分写入。

{
  "rows": [
    {
      "platform": "google_ads",
      "ad_account_id": "90071992547409931234",
      "campaign_id": "campaign-a",
      "spend_date": "2026-10-19",
      "currency": "USD",
      "spend_cents": 10000,
      "revision": 1,
      "data_cutoff_at": "2026-10-20T12:00:00.000Z",
      "source_reference": "platform-export-2026-10-20"
    }
  ]
}

platform,ad_account_id,campaign_id,spend_date,currency,spend_cents,revision,data_cutoff_at,source_reference

USD整数美分，已知0必须明确填写0，空白不能当0。仅接收已经结束的账户当地日；data_cutoff_at不得早于当天结束、不得在未来。同对象/日期/版本同内容幂等，异内容或低版409，高版替换有效快照并保留历史。缺报保持未知；周消耗不除7。负责人核对来源后仍标为customer_reported，不冒充platform_verified。

5. 每周营收观察独立上报

campaign-weeks仍是UTC周一00:00起的完整周，明确using_solution或not_using_solution。新Campaign合同额外要求platform、ad_account_id，完整示例如下。对照Campaign可单独授予observation权限，只展示自报实际指标，不开放未登记预测。周观察不直接计费，曲线差异不代表因果增效。

{
  "records": [
    {
      "platform": "google_ads",
      "ad_account_id": "90071992547409931234",
      "campaign_id": "campaign-a",
      "campaign_name": "Value test",
      "group": "using_solution",
      "week_start": "2026-10-19T00:00:00.000Z",
      "currency": "USD",
      "revenue_cents": 10000,
      "data_cutoff": "2026-10-26T00:00:00.000Z",
      "revision": 1
    }
  ]
}

6. 对账、确认与定稿

GET /api/v2/campaign-service?app_id=APP返回contract、scopes、active/pause_reason、spend、invoices、ledger；contracts、campaign-scopes、campaign-spend-days、invoices为同投影的资源别名。GET /api/v2/campaign-quote?app_id=APP&month=2026-11返回重算的input_hash、days、effective_spend_cents、base_cents、variable_cents、total_cents、missing、unreviewed。

负责人为已结束月份创建账单，客户确认当前input_hash，负责人再定稿。缺报或未核对不能确认/定稿；输入变化须重新生成并确认，并发变更会拒绝过时提交。同合同月份一份定稿主单，之后用独立确认的累计差额调整，不覆盖原单。整月有效消耗20,000美元收费349美元；30天月15有效日加5,000美元有效消耗收费124.50美元。基础费和整期比例费分别取整到美分再相加。

7. 暂停、关闭、恢复与资金

暂停/取消立即停新交付，次日当地00:00停计费。已交付具体版本按原权限及留存可读，内部新版本不能通过历史/导出/快照泄露。恢复也须等下一当地00:00，并执行明确的安装/队列水位，未确认缺口不自动首次交付。永久关闭不能恢复，需重新登记未来范围；撤权优先于历史回执。

次月5日前补齐、7日前核对，8日起未齐停新增；定稿7天到期再给7天宽限。固定截止不因没有访问而推迟。补齐资料/付款不会自动重开，负责人明确水位和缺口决定后恢复。收款/退款仅记录外部实际完成事项，支持部分付款与超付；唯一reference防重，退款不超净已收，不自动扣卡或转账。

动作Schema与错误处理

400/422：字段、金额、日期、确认或准备门槛错误；401：凭证无效；403：租户/App/角色/Token权限错误、撤权或新增生产暂停；409：修订冲突、输入过时、区间重叠或公司试用重复；410：同步快照过期/变更；413：请求过大；503：临时依赖失败。暂时故障使用原ID/reference重试，失败不能当接收成功。示例日期需换为真实已结束日期，不填造当前/未来最终消耗。本地合成验收不能代替平台核验、生产云、真实收付款或D90效果。

原始批次v2数据运输

当前公开套餐每月149美元起，含5,000名买量用户价值结果。每档均有30天免费试用，使用所选套餐额度；首次交付新增买量用户有效结果扣额度，重复查询及更新不重复扣。用完暂停新增交付，不自动超额收费。查看全部价格。套餐经接入确认后开通，已有账号在明确迁移前仍沿用已约定计费合同。

通过绑定应用的上报Token（batches:write）调用 POST /v2/ingestion/batches?app_id=APP；accepted只表示已持久接收，入仓与评分分别可查。用独立results:read Token查询 GET /v2/results?app_id=APP。自然量接收保存但不计费。真实历史及独立验证不足时只展示等待原因，不使用模拟评分替代预测。

{"app_id":"APP","batch_id":"batch-001","source_system":"af","schema_version":"raw-v2","mode":"increment","records":[{"kind":"install","event_id":"source-record-001","provider_user_id":"原始MMP用户ID","source_type":"paid","platform_install_time":"2026-10-30T00:00:00Z","occurred_at":"2026-10-30T00:00:00Z","currency":"USD","channel":"google","acquisition_cost_cents":100}]}

以AF/Adjust的非自然新增安装及原ID、安装时间为准，不自行跨ID合并。S24仅含安装后前24小时；每日处理满24小时的用户，迟到补算保留版本。原始流水从事件发生起最长180天；接入前确认字段与用途，各客户数据隔离。客户自行完成广告平台回传，在同渠道比较实际经济结果；本服务不保存广告密钥或代投。

进入已授权工作台。完整本地操作说明位于项目文档 docs/local-pilot.md。

以下为旧版 v1 参考

下方快照接口、399美元/5000人额度及模拟演示属于上一版实现，不是当前报价，也不是原始v2接口。既有v1调用保持原义，迁移需逐客核对。

{
  "app_id": "app",
  "batch_id": "documented-batch-001",
  "source_system": "af",
  "schema_version": "raw-v2",
  "mode": "increment",
  "records": [
    {
      "kind": "install",
      "event_id": "documented-install-001",
      "provider_user_id": "documented-user",
      "attribution_provider": "af",
      "source_type": "paid",
      "platform_install_time": "2026-10-01T00:00:00.000Z",
      "occurred_at": "2026-10-01T00:00:00.000Z",
      "currency": "USD",
      "channel": "google",
      "acquisition_cost_cents": 100,
      "source_revision": 1
    },
    {
      "kind": "event",
      "event_id": "documented-core-001",
      "provider_user_id": "documented-user",
      "attribution_provider": "af",
      "source_type": "paid",
      "platform_install_time": "2026-10-01T00:00:00.000Z",
      "occurred_at": "2026-10-01T01:00:00.000Z",
      "currency": "USD",
      "channel": "google",
      "event_name": "core",
      "source_revision": 1
    }
  ]
}

HTTP 202
{"batch_id":"documented-batch-001","status":"accepted","records":2,"prediction_status":"pending","request_id":"…"}

GET /api/v2/ingestion/batches/documented-batch-001?app_id=app
Authorization: Bearer YOUR_RECEIPT_TOKEN

GET /api/v2/users/documented-user?app_id=app&provider=af
GET /api/v2/users?app_id=app&limit=100
GET /api/v2/users?app_id=app&limit=100&after=NEXT_CURSOR
GET /api/v2/results/sync?app_id=app&limit=100
GET /api/v2/results/sync?app_id=app&limit=100&cursor=NEXT_CURSOR
GET /api/v2/results/sync?app_id=app&since=SYNC_TOKEN
GET /api/v2/results/export?app_id=app
Authorization: Bearer YOUR_RESULT_TOKEN

旧额度合同与套餐

每套餐适用于一个已确认应用。免费期结束且确认付费开通后，首个付费周期开始；按开通日逐月、UTC结算。更高套餐仅在完整当前试用或付费周期结束后，经负责人冻结账单与核实外部到账后开通下周期；当前额度不增加。未用额度不结转。额度耗尽时尚未交付的用户，不自动跨期扣除；续期或升级后，只有仍在保留期、符合评分条件且经确认纳入新服务范围的用户才继续处理，续期不能恢复已到期数据。

冻结行为组与统一价值档

新格式 valuesignal_tree_value_groups_v1，协议 tree-value-groups-s24-d90-v1。结果包含 behavior_group_id、value_tier_id、tier_value、raw_prediction、protocol、grouping_version 及模型/参考版本。predicted_value 等于统一 tier_value，raw_prediction 仅用于诊断。边界并列整档同一信号资格，渠道覆盖为参考目标。旧v3金额与首次结果保留，新价值档未知。真实客户仍需真实独立验证及负责人手动发布，模拟包不得用于生产。