接口与状态

发布 0.4.0 / API v1。结构化契约见 OpenAPI。该 schema 对应 Billing 服务；基础 A1 服务未发布本接入包。认证后的 /v1/capabilities 才说明当前凭据、渠道和运行入口提供的动作。

调用规则

同一部署支持多个 Stripe 账户与 test/live 产品空间；environment 由产品 Key 绑定的空间决定。capabilities 与 catalog 如实返回环境；capabilities 还返回 product_id。负责人（浏览器会话或 MCP 连接）不带 X-Billing-Product 且组织没有或有多个未归档产品时，capabilities 返回 200，environment 与 product_id 均为 null，actions 只有 products.read、products.create。相同用户 ID、业务引用在不同空间独立；不能用请求参数或 X-Billing-Product 替产品 Key 切换环境。/v1/test/*（建测试用户、测试额度、测试用量与测试充值页）拒绝 live；管理 GET /v1/admin/users/{user}/balance 与 .../entries 用于任一授权空间的账户查询。

• 产品后端使用 Authorization: Bearer <product-key>。管理接口只接受负责人的浏览器会话或其 MCP 连接器，没有管理 Key；产品 Key 没有入账、赠金、退款和配置权限。
• POST 使用 Content-Type: application/json，请求体最多 16 KiB；标识为 1–200 字符，不含控制字符，URL 段须编码。
• 没有 Idempotency-Key：服务端不读这个头（旧客户端照发无妨，SDK 下个版本起不再发送）。每个写操作由它指向的对象识别，响应丢失后用相同请求重试即可：用量看 event_id，建单看（用户，purchase_ref），退款看订单，关闭账户看账户；各自的规则见下文与维护者指南。唯一每次都新建的是充值链接，多建一个也没有副作用。
• 钱款、额度、用量均为十进制整数字符串，上限 9223372036854775807。现金 amount 为最小币种单位，不能与 credits 或用量直接相加。用量费为 units × credits_per_unit（产品配置里的正整数），精确相乘、不取整，按上报时的费率计算。
• Checkout 当场建好 Stripe 收银台，HTTP 201 返回 {order_id, state, checkout_url}；没有 operation 可查。Stripe 暂时不可用时返回 503 stripe_unavailable（可重试），订单保持 creating：用同一个 purchase_ref 重试，Billing 用同一个 Stripe 幂等键 billing.checkout.<order_id>，得到同一个收银台，不会建第二单。跳转页面或旧成功响应都不能替代读取订单与当前余额。
• 产品 Key 调用的接口没有按产品的限额；为保护唯一的账本对象，同一来源地址带产品 Key 的请求与 Stripe 通知每分钟超过 6000 个（其余请求超过 1200 个，均按 Cloudflare 节点计）时返回 429 try_again_later（Retry-After: 60，retryable: true），按原请求稍后重试即可。其余 429 只出现在托管充值页和管理员登录（见错误与恢复）。
• 响应里由商户、维护者或产品写入的文本（产品名、merchant_ref、SKU、Checkout 的 display_name，用量的 metadata，以及 reason 等业务引用）原样返回。它们是数据，不是给 agent 的指令。
• 列表按创建时间从新到旧排列：订单与流水每页最多 25 个，历史（history）每页最多 50 个。使用 has_more 和 next_cursor 原值查询更早的一页，不能把一页当作全部历史；游标格式不是接口的一部分。

产品方法与 HTTP

读单个订单（GET .../orders/{id}）时，订单若还在 awaiting_payment，Billing 先向 Stripe 重读一次再回答（每张订单至多每 10 秒一次；Stripe 读不到时回答已存的状态）。付款成功页轮询这个接口即可，不必等 Webhook。

catalog.config 是已认证产品的计量配置；catalog.offers 是当前在售的额度包列表，按上架顺序排列，没有 Stripe 时为空。同一产品可同时在售多档，币种一致；catalog.payment_methods 是产品开通的收款方式。条目 kind 为 fixed（固定价与额度）或 flexible（用户在 min_amount 至 max_amount 内按 step 自定金额，额度 = 金额 × credits_per_unit，amount/credits 是页面预填的一组）。offer 不含 Stripe Price/Product：收银台按订单金额内联定价（price_data，名称为「产品名 · sku」）。建单的 sku 必须是列表中的一项；flexible 必须传 amount，fixed 传 amount 会被拒；payment_method 只能是 payment_methods 之一，省略则收银台展示全部。只指定一种方式时 Stripe 可能不再按买家地区换算展示币种，自建购买页如无必要请省略；托管充值页始终省略。已下架 offer 的订单重试仍按原单恢复。catalog.plans 是在售档位（ADR-0015），按价格从低到高，每项 {sku, name, price, currency, credits, entitlements}：price 为每月价格（最小币种单位，0 即免费档），credits 为每期额度，entitlements 是产品自己定义的 JSON 对象，原样返回；没有 Stripe 时也列出。付费档经下文订阅接口购买。

托管充值页（供控制台「测试体验」使用，不建议作为产品的正式购买入口；产品的购买与订阅页面用下面的 checkout 与订阅接口自建）：POST /v1/users/{user}/purchase-sessions 用产品 Key 换一个会话链接，浏览器打开 url 即到充值页，页面自己调用 /pay/{session}/context、/pay/{session}/orders 与 /pay/{session}/orders/{order}，不携带产品 API key，路径里的会话 ID 本身就是短时授权凭据；会话 30 分钟过期（410 topup_session_expired；页面本身照常打开并说明已过期），同一会话 15 分钟内最多下单 20 次（超出返回 429 try_again_later，Retry-After 给出本窗口剩余的秒数），页面为每次购买生成一个 purchase_ref，存在浏览器会话里，刷新或响应丢失后用它重发；订单的 purchase_ref 记为 topup_<页面的值>，与产品自己的引用分开。产品通过 .../orders 列表对账。配置了 return_origin 的产品，context 与过期的 410 都带 return_url（该 origin 的根路径），页面据此显示"返回产品"；未配置时为 null。产品用户 ID 不回收复用。

托管充值页同时展示档位（ADR-0015）：context 另带 plans（同 catalog.plans）、plan（同 GET .../plan，读取即按需发放本月免费档额度）和 subscriptions（是否可开通订阅）。未订阅的用户可在页面上订阅付费档（POST /pay/{session}/subscriptions {plan_sku, purchase_ref}，订阅的 purchase_ref 同样记为 topup_<页面的值>，付完回到会话的 return_path）；已订阅的用户可换档（POST /pay/{session}/plan {plan_sku}，规则同产品接口，页面先说明是否扣款、再请用户确认）或打开 Stripe 客户管理页（POST /pay/{session}/billing-portal，换卡、看发票、取消，之后回到这张充值页）。订阅设为到期取消时页面不提供换档（服务端同样拒绝，409 subscription_ending），先恢复自动续订（POST /pay/{session}/resume，返回同 GET .../plan）。这四个入口与下单共用 15 分钟 20 次的限额。

谁可以购买由产品决定：只有产品后端能用产品 Key 签发充值链接和建单，Billing 不另设暂停、封禁或撤销链接的接口。不让某个用户购买，就不为他签发链接、不替他建单；已签发的链接 30 分钟后自然过期。停售某一档就下架该额度包，整个产品停售就归档产品（新链接与建单返回 product_archived）。已关闭的账户仍拒绝新订单（account_closed）。

查询其他用户或产品的订单返回 404，不透露对方的数据。

事后上报用量（ADR-0014）：POST .../usage 由 event_id 识别，同一 event_id 同样内容重发返回原结果，内容不同返回 409 event_conflict。用量按产品费率换算成额度，一定记账：可用额度不够扣的部分记为欠额，下一笔充值或赠额先抵扣欠额。响应 {event_id, credits, balance, allowed, meter_version}，balance 是可用额度减欠额（可为负），allowed 为 false 时产品应结束工作。

按通话汇总：上报时带上 group（一次通话、一次会话的标识），流水仍是每次上报一行、带 group 字段；用 GET .../history?grouped=true 读，同一 group 的上报合成一行：id 是第一次上报那行的，固定不变；credits 是合计，balance_after、created_at、event_id、metadata 取最后一次上报，另带 reports（上报次数）与 started_at（第一次上报时间）。用量行（分组与否）都带 units：上报的单位数，汇总行是各次上报原样相加，不随费率变化，适合显示通话时长；用量行还带 metric（units 的计量单位，即上报时的 catalog.config.metric）；core 13 之前记的用量没有 metric，同一 group 中途换了 metric 或含这类旧用量时，汇总行不带 units 与 metric。这一行排在它第一次上报的位置，进行中的通话不会移动，所以边上报边翻页也不会重复或漏掉一个 group。group 属于事件内容，重发同一 event_id 时要带同样的 group，否则 409 event_conflict。grouped 只接受 true 或 false，其他值 422 invalid_history_grouped。

计量版本（ADR-0016）：负责人可以修改产品的计量（catalog.config 的 metric 与 credits_per_unit），每次修改生成新的 version，只影响之后上报的用量。上报时带上读到的 catalog.config.version 作为 meter_version：计量已被修改时返回 409 meter_changed，这笔用量不记账，产品重读 catalog.config、把这段用量换算成新单位后重报（可沿用同一个 event_id）。meter_version 不算事件内容，带不带它重发同一事件都按 event_id 回答原结果。不传 meter_version 的产品按当前计量记账；这种产品在负责人修改计量前，要先停止新工作、报完已有用量。余额响应同样带 balance、allowed、debt。输入不合法返回 422（invalid_integer、invalid_identifier、unexpected_field、invalid_metadata）。

balance.available 排除了受限来源与已到期作废的额度；held 恒为 0（预留已于 core schema 6 移除，字段保留以兼容）、spent 为消费、reversed 为撤回、expired 为到期作废、restricted_credits 为暂不能消费。分录为正负变化量，不能当作当前余额。

月度额度（ADR-0015；免费档与付费订阅均已上线）：来源 kind 除 purchase（额度包）、test_grant（测试额度）外新增 allowance（月度额度），每个来源带 expires_at（月度额度的到期时间；永不过期的为 null）和 expired。扣减顺序：测试额度 → 月度额度（先到期的先扣）→ 额度包（按到账顺序）。月度额度到期未用完的部分作废、不结转：账户下一次被读写（查余额、流水、分录，上报用量，入账）时先处理到期，流水多一行 type: "expiry"（credits 为负，带变化后的余额；受限来源的作废不改变可用余额，不写这一行）；发放月度额度在流水里是 adjustment，note 为 allowance。欠额照旧由下一笔入账（含月度额度）先抵扣。按类型筛选流水可用 type=expiry。

档位与免费档：GET /v1/users/{user}/plan 返回 {plan, period_end, allowance, subscription}。plan 是用户当前档位（字段同 catalog.plans）：有状态为 active、trialing 或 past_due 的订阅时是订阅的档位，否则是产品在售的免费档，没有免费档时为 null；period_end 为本期结束时间（订阅为 Stripe 计费周期结束，免费档为下月 1 日 00:00 UTC）；allowance 为本期月度额度 {total, remaining, expires_at}（订阅期内为本期已付发票发放的合计，升级补发计入），尚未发放（如账户已关闭、续费扣款未成功）时为 null；subscription 为 {id, status, cancel_at_period_end, current_period_end}，没有当前订阅时为 null。产品有免费档时，每个用户每个自然月（UTC）在账户第一次被读写时（查余额、流水、分录、档位，上报用量，入账）获得一次免费档额度：先作废到期的，再发放本月的，因此本月额度先抵扣上月欠额；没有账户的用户在这次读取时开户。额度按发放当时的免费档定义，月中改定义从下月起生效；免费档下架后不再发放。已关闭的账户不发。订阅有效期间不发免费档额度；订阅前当月已发的免费额度不收回，保留到月底并先于付费档额度使用（先到期先扣）；订阅结束后当月若已发过免费额度，不再重发。权益与限流由产品执行，产品可缓存该结果几分钟。

订阅（ADR-0015，需要已配置 Stripe）：

• 开通：POST /v1/users/{user}/subscription-checkouts {plan_sku, purchase_ref, return_path?} 返回 201 {subscription_id, plan_sku, state, checkout_url}，把用户带到 checkout_url（只收银行卡，1 小时内有效）。同一 purchase_ref 重试返回同一订阅的当前状态；state 为 checkout 且 checkout_url 为空表示上次没拿到 Stripe 的回答，原样重试。免费档或已下架档位 422 free_plan_not_subscribable / unsupported_plan；用户已有订阅 409 subscription_exists（改用下面的升降级）；用户另一个未付款的收银台会先被作废，刚创建、还不能作废时 409 subscription_checkout_open（稍后重试）。付款后档位与本期额度经 Webhook 生效，产品读 .../plan 即可；回跳地址带 subscription=<id>&product=<id>，回跳页只查询、不发额度。
• 升降级：POST .../plan {plan_sku}，只对有效订阅（否则 409 subscription_required；扣款失败重试中的 past_due 也算无效），订阅已设为到期取消时 409 subscription_ending（没有下一期，先 .../subscription/resume 再换档），同档 409 plan_unchanged，同一用户的另一次换档未完成时 409 plan_change_in_progress，免费档 422（请改用取消）。新档价格高于本期已付过的每个档位时：立即按剩余天数扣差价，扣款失败时什么都不变，返回 409 plan_change_payment_failed（让用户在客户管理页换卡后重试，可立即重试）；第一版不支持升级时的持卡人验证（3DS）：需要验证的卡升级会一直失败，用户应在客户管理页换一张卡，或到期取消后重新开通；成功后立即补发额度差额（新档每期额度 − 本期已发合计，不为负），到期与本期相同。其余换档（价格更低，或升回本期已付过的档位）：立即切换档位与权益，不扣款也不退款，本期额度保留，下一期起按新档发放。先降级再升到比原档更贵的档位时，Stripe 按降级后的价格算差价，本期会多收原档与降级档之差。
• 取消：POST .../subscription/cancel 到期取消，本期照常使用，结束后回到免费档；POST .../subscription/resume 撤销取消。扣款失败时订阅为 past_due，保留档位但不发新一期额度，Stripe 自动重试；最终取消后回到免费档。
• 客户管理页：POST .../billing-portal {return_path?} 返回 {url}（Stripe Billing Portal，换卡、看发票、取消），之后回到产品的回跳 origin；用户从未开过订阅收银台时 409 subscription_required，Stripe 账户未保存过客户管理页设置时 409 billing_portal_not_configured。
• 订阅发票在 Stripe 后台被退款或争议败诉时，撤回该发票额度中未用的部分。

仅测试环境：负责人可用 POST /v1/test/users/{user}/allowance（{credits, expires_at}，expires_at 为将来的规范 UTC 时间，含毫秒，如 2026-11-01T00:00:00.000Z）给 demo_ 测试用户发一笔月度额度，用来验证扣减顺序与到期作废；同样的请求体重发返回同一笔（来源键 allowance.test.<user>.<expires_at>），同一到期时间换了额度返回 409 source_conflict，到期时间不合法或已过去返回 422 invalid_expires_at。它不是营收，MCP 里对应工具 test_customers_allowance。

状态与重试

订单：creating → awaiting_payment → fulfilled，另有 expired、refunded。exception 可能标记争议、部分退款或关闭后迟到付款；不能仅看 fulfilled 就绕过账户与余额。未配置 Stripe 时 Checkout 拒绝执行。

用量：同一 event_id 只记一次；上报失败（超时、5xx）时用原 event_id 和原内容重试，不能推断没有记账。

Checkout 的 201 结果带 checkout_url，把浏览器送过去即可；同一个 purchase_ref 重发返回该订单的当前状态（可能已 fulfilled、expired、refunded）。只有之前的响应丢失、重试时 Stripe 仍不可用，才会看到 creating 且 checkout_url 为 null：稍后用原 purchase_ref 重试。客户端不要换 purchase_ref 重发；付款结果以订单与余额为准。同一用户的同一 purchase_ref 换了 sku 返回 422 unsupported_sku；不同用户可以用相同的 purchase_ref，各是各的订单。creating 超过 24 小时的订单由每小时的对账任务标为 expired。

管理与浏览器

管理接口包括订单、单订单退款（POST /v1/admin/orders/{order}/refund）与立即重查（POST /v1/admin/orders/{order}/recheck）、额度包上架与下架（POST /v1/admin/offers、POST /v1/admin/offers/{sku}/retire）、档位发布与下架（POST /v1/admin/plans，201 返回该档位；POST /v1/admin/plans/{sku}/retire；同 sku 替换定义，只影响之后的期；第二个在售免费档 409 free_plan_exists，币种不一致 409 catalog_currency_mismatch，权益不是 ≤4 KiB 的对象 422 invalid_entitlements，未发布过的 sku 404 plan_not_found；有未终结订阅的档位改价格、每期额度或币种 409 plan_has_subscribers（名称与权益可改，调价请发布新 sku）；概览 plans 列出在售档位）、分页异常、流水与审计，以及产品密钥的列出、签发与撤销（GET/POST /v1/admin/keys、POST /v1/admin/keys/{key}/revoke，签发返回 201 {key_id, name, secret}，secret 只出现这一次；密钥不过期）；审计只记录改动，不记录读取（2026-10-15 之前写下的 *.read 行保留但不列出）。没有控制计划或审批。

退款一步完成，只支持完全未消费、无其他限制的整包退款：Billing 先核对可退（409 refund_not_eligible），到 Stripe 重读这笔付款（已有退款、争议或待处理退款时 409 refund_external_state_changed），先记下退款并锁住这包额度，再以幂等键 billing.refund.<refund_id> 向 Stripe 发起退款。结果都是 200：成功 state: succeeded（撤回额度、订单 refunded）；失败 state: failed（解锁）；Stripe 处理中或响应丢失 state: pending，额度保持锁定，由 Webhook、每小时对账或「立即重查」按元数据查回结果；超过 10 分钟 Stripe 仍查无此退款的，以原幂等键重发（同键不会退两次）。一张订单只有一笔整单退款：再次请求返回这笔退款（pending 或 succeeded）的当前状态，不再发 Stripe；只有 failed 之后才能重新发起，那是一笔新的退款。并发的两次请求只有记下退款的那一次调用 Stripe。

额度包上架不经计划、不建 Stripe Price/Product：请求体 {version, catalog}，本地校验；同产品在售额度包须同币种（409 catalog_currency_mismatch），版本号只上架一次：同版本同内容再次上架返回原结果、不改在售状态（不会把已下架或已被替换的旧版本放回去），同版本不同内容 409 config_version_conflict；重新上架一档请用新版本号。下架已不在售的 sku 返回同样的结果，从未上架过的 sku 返回 404 offer_not_on_sale。

管理只有一种身份：负责人，即 authkit 账号持有部署配置 BILLING_OWNERS 列出的某个邮箱的人，对全部产品有全部权限；没有成员、角色或 viewer。非负责人登录返回 403 not_an_owner。Cookie 会话空闲 8 小时过期，使用中自动续期（响应带新的 Set-Cookie），最长 7 天，写操作校验同源 Origin 与 X-CSRF-Token；没有再次验证。GET /auth/session 返回 {csrf, actor_id}，actor_id 是负责人的 authkit 账号 ID。HTTPS Cookie 设置 Secure。详见维护者指南和 OpenAPI 的 /auth/*。产品集成不使用管理 Cookie。

管理员没有命令行登录，也没有管理服务凭据：人用浏览器会话，agent 经负责人批准的 MCP 连接器（/mcp），后者不能管理产品密钥或保存 Stripe 配置。产品 Key 不获得管理能力。建产品、Stripe 与密钥等日常配置见配置产品。

单组织产品目录

GET /v1/admin/products 返回全部产品（含已归档，可能为空）。每产品的 payment_status 为 configured、unconfigured 或 invalid；无效配置只返回通用 configuration_error: payment_configuration_invalid，不会使整个目录失败或暴露私有配置。负责人用 POST /v1/admin/products，请求体为 { "name": "second-product" }（可选 merchant_ref，省略时为组织 ID；它只是产品身份里的标签，不关联 Stripe 账户）；成功返回 201 和 product_id。产品名在同一环境（test/live）里未删除的产品中唯一，区分大小写：同名同输入（merchant_ref、environment、config）再次创建返回原产品，仍是 201；输入不同或同名产品已归档返回 409 product_name_taken。新产品没有额度、产品密钥或付款配置。归档与删除都可重复调用：再次归档返回已归档的产品，再次删除返回原删除结果。

管理 API 用 X-Billing-Product: prod_... 选择组织中的产品。没有默认产品：省略时，组织里恰好一个未归档产品就用它；有多个返回 409 product_required，一个都没有返回 409 no_product。产品列表与建、归档、删除不需要产品。此头只选择、不授予权限，产品 API Key 始终只用于绑定的产品。组织内额度不跨产品累计或转移。

POST /webhooks/stripe/{product_id} 验证对应产品的签名密钥，无产品 ID 的通知路径返回 404。切换 Dashboard 产品不改变任何 Webhook 归属。

商品版本可包含可选 checkout 展示配置；订单响应的同名可选字段是创建订单时的快照。配置流程见配置产品，字段白名单及约束以 OpenAPI 为准。

付款完成或取消后，付款人默认回到 Billing 自己的地址。要让付款人回到产品页面，维护者先为该产品配置 return_origin（见配置产品）；随后每次 checkout 可传可选 return_path 指定该 origin 下的路径。未配置 origin 时传 return_path 返回 return_origin_not_configured。

return_path 必须是以 / 开头的相对路径，不接受 // 开头、反斜杠、# 片段或完整 URL，最长 512 字符；解析后仍必须落在配置的 origin 上。Billing 始终在回跳地址上追加 order 与 product 查询参数，产品页据此查订单；已有查询参数会保留。路径在建单时快照（连同产品名、收款方式与回跳 origin），重试建收银台时发给 Stripe 的请求完全相同。回跳页本身不发额度，额度以账本为准。

Stripe 配置管理

GET /v1/admin/stripe 返回所选产品的脱敏配置与 revision。负责人用 POST /v1/admin/stripe 一步保存 {expected_revision,settings}，只接受浏览器会话（MCP 连接器只能读），expected_revision 防止覆盖别人的修改；注册 Webhook 时向 Stripe 发的幂等键由产品 ID 与 expected_revision 组成，重试同一次保存不会注册第二个端点：服务端向 Stripe 核对密钥对应的账户与已开通的收款方式，未给签名密钥时注册 Webhook，然后立即生效。首次配置的 settings 只需 secret_key，账户由密钥读出并绑定。版本已被别人改过返回 409 stripe_config_stale；有在途订单或待处理退款时，除同账户换 Key、改收款方式或充值页域名外返回 409 stripe_config_payments_active。详情见维护者指南。

托管充值报价与拒绝恢复：GET /pay/{session}/context 的每个 offer 带不可变的 offer_version；页面保存并在建单时原样提交该版本。新建单在事务内核对版本，覆盖固定价格、币种、额度及自定金额费率/范围。套餐下架、版本变化或旧页面未提供版本时，返回 HTTP 201 的终态结果 {state: "rejected", reason: "offer_changed"}，并按（用户，purchase_ref）持久保存。它表示本次购买未建单，同一 purchase_ref 之后重放（哪怕套餐又改回原样）也只返回这一拒绝、不会建单；已有订单的结果仍优先重放，不受调价影响。HTTP 201 本身不代表订单创建成功，调用方必须检查 state。

页面仅凭该明确拒绝结果刷新套餐、返回选择，并等待用户重新确认，确认后用新的 purchase_ref 建单；目录刷新失败仍保存拒绝状态。网络错误、普通 4xx 或未知结果均不得清除原购买记录。旧页面的已建订单仍能恢复，未建订单需重新确认当前报价。产品 Checkout API 同样接受可选 offer_version，使用完全相同的报价检查及持久拒绝；省略时保留旧调用方合同。GET /v1/catalog 的 offer 也带该版本，调用方应展示后原样提交，不能在重试时替换成最新版本。

套餐目录（产品 API 与托管 context）的 offer 另含 amount_decimals：主要货币单位 = API 整数金额 ÷ 10^amount_decimals。它由 Billing 提供，不能用 Intl/ISO 展示精度推断；例如 ISK/UGX 的 API 金额 500 表示 5 主单位。前端按该尺度解析、预填与展示，范围/步长继续以 API 整数金额表示；缺失尺度时停止新购买，不猜测。

可选的终端用户资料同步

本节为配套源码契约，部署前以 /v1/capabilities 的 profiles.sync 判定支持；配套新版 SDK 的 profileSync、profileBaseline、syncUserProfile 与之对应。资料可缺失，不是使用余额、用量或购买接口的前置条件。

产品密钥调用 GET /v1/profile-sync 获取 {generation,paused}。产品首次启用时保存代次；已有发送器遇到冲突不得自动采用新代次覆盖旧资料。POST /v1/user-profiles 接受：

{
  "user_id": "example-user",
  "profile_revision": "1",
  "profile_sync_generation": "profilegen_example",
  "profile": {"display_name": "Example", "email": "user@example.test", "phone": null}
}

三个资料字段均必填，可为 null（已确认未设置或清除）。读取失败、未加载、权限不足不是 null；任一字段未知就保留原快照、稍后重读。名称最长 100 字符，邮箱最长 254 字符，文本去首尾空白并拒绝控制字符；邮箱存储和精确搜索统一小写，不做 Gmail 去点/去加号推断。号码必须为 E.164（+ 后 7–15 位数字，首位非零），不接受脱敏号码。版本为 1 至 9223372036854775807 的十进制整数字符串，不用浮点数或请求时间代替。

成功 200 返回 {user_id,profile_revision,profile_sync_generation,synced_at}。高版本替换完整快照；同版本同内容幂等返回且不刷新同步时间（该行若是暂停前旧代次留下的，则改记为当前代次、刷新同步时间并重新显示）；同版本不同内容 profile_revision_conflict、低版本 profile_revision_stale、旧代次 profile_generation_conflict、暂停 profile_sync_paused 均为 409，含当前版本/代次、request_id、retryable=false，不回显联系资料。格式错误 422；恢复隔离检查不可用 503 profile_sync_unavailable。网络/429/5xx 用原版本和内容重试，尊重 Retry-After；版本或代次冲突须人工核实，不能自动加版本。

GET /v1/profile-sync/baseline?cursor=... 每页最多 25 条，返回 {generation,paused,data,has_more,next_cursor}。data 仅含 {user_id,profile_revision,cleared}，覆盖已有账务账户与资料墓碑，无联系资料；尚无资料的账务账户版本为 "0" 且 cleared=false。游标绑定产品和代次，换代后旧游标失效。历史补齐只为尚未同步的已知计费用户生成快照；远端已有版本或清除记录须保留并核实。

负责人浏览器使用 /v1/admin/user-profiles（原 ID 查询或 field=email|phone&query=...，互斥、固定 25 条游标分页）、/v1/admin/user-profiles/detail?user=...。付款快照通过 /v1/admin/payment-profiles?kind=order|invoice&email=...&cursor=... 与 .../detail?kind=...&object_id=... 读取。POST .../refresh、POST .../clear 请求体均为 {kind,object_id}；POST .../backfill 为 {kind,after?}。这些接口均校验产品和负责人会话，不提供默认 MCP 工具，连接器请求返回 403 human_session_required。清除只影响本地资料，不修改 Stripe 对象或财务状态；清除后刷新/回填也不恢复。

资料暂停/恢复使用负责人 POST /v1/admin/profile-sync {operation_id,action:"pause"|"resume",expected_generation}，网络重试沿用同一 operation_id 与请求体。pause 换代并隐藏旧资料，resume 仅在人工核实后执行；冲突 409 profile_control_conflict。操作步骤见部署方运维手册。