stigg-contracts

Stigg Contracts — 权益与开票

合同是销售驱动型交易的事实来源：客户可以做什么，以及你向客户收取什么费用。它会为同一位客户归组订阅，这些订阅会授予相应权益——合同是订阅所属的协议，并非第二种权益授予机制。合同也可以附带一个计费合同，用于生成发票。这两部分相互独立——没有计费合同的合同仍然可以配置访问权限。

合同本身不包含商业条款。 没有价格、数量或承诺字段——只有名称、PO 编号、启用时间范围和订阅关联。协商价格和承诺用量属于自定义订阅（priceOverrides、charges、unitQuantity、minimumSpend — stigg-subscriptions）。有价明细仅存在于下方的计费部分。

开始之前

根据总纲 stigg 技能：先搜索。 根据文档确认结构和字段名称。

没有 SDK 接口。 @stigg/node-server-sdk 或 @stigg/js-client-sdk 中都不包含合同功能。请使用 REST（此处为规范接口，https://api.stigg.io/api/v1，请求头为 X-API-KEY）或 GraphQL。

可用性。 并非所有账户都已启用此功能。如果端点返回 404，表示该功能尚未启用——请联系 Stigg，不要尝试绕过限制。

想从哪里开始？

控制面板会原样询问这个问题，并提供两个相互独立的复选框——配置访问权限和设置账单——因此有三种开始方式。先确定选择哪一种；这会决定以下每一步。

选择	合同的作用	发送
仅配置访问权限	归组自定义订阅并授予相应权益。不生成发票。	setupBilling: false + subscriptions
仅设置账单	有价明细和发票，不附加订阅。	setupBilling: true，不传 subscriptions
两者都做	在同一份协议中同时包含权益和开票——已签署订单表单的常见形式。	setupBilling: true + subscriptions

setupBilling 默认为 true，因此必须明确指定仅配置访问权限。

术语——识别所有名称，但只说一种。 UI：“配置访问权限” / “设置账单”。 文档：“权益配置” / “计费合同” / “两者都做”。API：setupBilling。

绝不要向用户展示字段名称——包括 setupBilling。 只说“仅配置访问权限”“仅设置账单”或“两者都做”。以下所有字段均适用这一点：用户应使用订单表单中的措辞确认交易，而不是使用 JSON。

操作一览

操作	用途	参考
创建、附加、分离、修改、归档、读取	合同及其成员关系	以下内容
设置账单	条款、设置、有价明细、总计、发布	以下内容 + references/billing-and-invoices.md
选择定价模式	交易形式 → 模式 + 行项目，以及不适用任何模式的形式	references/pricing-models.md
发票	列出、筛选、查看单张发票、获取 PDF、标记为已付款	references/billing-and-invoices.md
贷项通知单	合同无法再编辑后结清变更	references/billing-and-invoices.md

配置访问权限

归组自定义订阅并授予相应权益。除非同时设置账单，否则不生成发票。

前提条件

只有自定义方案符合条件——包括自定义方案及其附加项，不包括自助服务方案。每个订阅都必须采用自定义定价：使用 CUSTOM 方案，或以 paymentCollectionMethod: "NONE" 配置的 PAID 方案。（stigg-pricing-modeling）

先配置客户账户——仅当客户已存在时，才能创建合同。

服务端有三项规则：每个产品只能有一个订阅、只能使用一种货币，且每个订阅都必须属于合同对应的客户。

两种方式：执行顺序

根据订单表单，先创建合同，再由它配置订阅——单独配置订阅会留下一个已生效但未关联的订阅，直到第二次写入才会关联。两种先创建合同的方式都是单个事务：使用 POST /contracts 和 newSubscription 条目，或稍后在 POST /contracts/:id/subscriptions 中添加相同的条目。

因此：收集需求 → 创建包含其订阅的合同 → 验证权益 → 为各项定价。

创建合同

区别在于 setupBilling: false——默认值是 true，因此请显式传入。

curl -X POST "https://api.stigg.io/api/v1/contracts" \
  -H "X-API-KEY: <YOUR_API_KEY>" -H "content-type: application/json" \
  -d '{
    "customerId": "customer-acme",
    "contractId": "contract-acme-po-4821",
    "name": "Acme 2026",
    "poNumber": "PO-4821",
    "setupBilling": false,
    "subscriptions": [ { "existingSubscriptionId": "subscription-acme-platform" } ]
  }'

每个条目必须且只能是 existingSubscriptionId 或 newSubscription 其中之一——完整的订阅配置请求体，其中包含各自的 customerId 和 planId（stigg-subscriptions）。只有 customerId 是必填项；若要创建空合同，请省略 subscriptions。创建操作是原子的——失败时不会留下任何内容。

始终传入你自己的 contractId——这是根据交易（PO 或订单号）生成的幂等键。再次传入相同的 ID 会返回现有合同；不传入时，重试会悄无声息地创建重复合同，而且合同无法删除。

关联和解除关联订阅

C=https://api.stigg.io/api/v1/contracts/contract-acme-2026

# Attach existing ones; `subscriptions` with create's own entries provisions new ones instead
curl -X POST "$C/subscriptions" -H "X-API-KEY: <KEY>" -H "content-type: application/json" \
  -d '{ "subscriptionIds": ["subscription-acme-analytics"] }'

# Detach — unlink only; the subscription stays active
curl -X DELETE "$C/subscriptions/subscription-acme-analytics" -H "X-API-KEY: <KEY>"

幂等：重复关联，或解除并未关联的订阅，都不会产生任何变化。已关联到其他合同的订阅会被拒绝，而不会转移。

不要使用 PATCH /contracts/:id 来添加订阅。 其中的 subscriptionIds 会替换整个集合，未列出的 ID 都会解除关联。仅在声明完整成员关系时使用。

修改、归档和读取

PATCH /contracts/:id（名称、PO 编号、启用日期）、GET /contracts/:id、 GET /customers/:customerId/contracts、GET /contracts?state=ACTIVE、POST /contracts/:id/archive。

归档不等于解除关联。 归档会取消合同及其上的所有订阅——客户将失去访问权限。若要在订阅继续运行的同时将其移除，请解除关联。

仅配置订阅不会带来的内容

不会创建计费合同：billingId 和 nextInvoice 会保持为 null，不会生成发票，取消计费请求也会被拒绝。这是预期行为，并非配置错误。之后添加计费是单向操作（references/billing-and-invoices.md）。

合同状态

存储状态在取消前一直是 DRAFT；读取到的状态是派生状态——只要合同上的任一订阅处于活动状态，状态就是 ACTIVE。因此，仅配置订阅的合同会自行变为 ACTIVE，无需发布步骤。字段表、状态机、错误代码和 contract.* 事件：references/contract-model.md。

---

设置账单

协商确定的条款、定价明细项、发票。需要账单合同——创建时设置 setupBilling: true，或稍后在仅配置的合同上启用（单向操作；账单永远不会被移除）。

完整演练：references/billing-and-invoices.md。 先了解以下五点：

1. 首次写入前，先确认完整的阅读内容。 订单表单不是规格说明。逐项复述每个明细项及其定价模型和行、条款、法律实体和客户信息——并在任何写入调用前取得确认——发布前审查已经太晚，明细项届时已存在。发现矛盾时应明确指出，而不是自行解决。订单表单中的明细项容易遗漏，且遗漏规律固定——基于用量的明细项不会显示金额，Included 明细项的价格应为 0，按周期列出的表格属于同一份合同，“purchase order reference” 通常是 N/A，不是订单号。参考文档逐一介绍了这些情况。
2. 明细项必须采用现有定价模型定价——绝不能自行创建表格。 GET /contracts/pricing-models 会列出定价模型及其 isPayAsYouGo 和 editableInputs；只需提供模型公开的输入，并按 rows 接受的名称填写。收费类型为预付（IN_ADVANCE）或后付（IN_ARREARS）——引擎的 DURING_USE/AFTER_USE 不受支持。按量付费仅适用于计量项，不接受数量（由用量提供数量），且始终为后付。应通过 isPayAsYouGo + 结构确定模型，绝不能按名称判断——十个模型中有五个与其相反类别的对应模型同名，两者接受相同的行且都会返回 200。references/pricing-models.md 将交易结构映射到定价模型，并列出每种结构最接近但不正确的模型。
3. 法律实体必须关联付款账户。 GET /contracts/legal-entities 会列出每个实体的账户；paymentAccounts 为空是常见的未完整配置状态，而且没有任何 API 可以创建付款账户——应在构建前提出，否则合同看似完整，却无法发布。使用 PATCH .../billing/settings 和 .../billing/terms 同时设置这两项，以及周期、币种和付款条款——这些设置适用于整份合同，因此应在任何单项例外之前设置。
4. 发布前要进行两项检查，草稿合同也能实际执行。 使用 GET .../billing/summary 对照订单表单中的数字，并使用 GET .../billing/invoice-schedule（?count=N）对照其账单安排。总额可能完全正确，但发票却有误——金额相同、开票时间不同的明细项会拆分成额外发票，只有账单安排能显示这一点。没有账单周期、付款条款和法律实体时，系统会拒绝发布。
5. 已生效的合同应修改，而不是重写。 POST .../billing/edit-active 会原地修改合同——合同仍保持生效状态，且只会重新生成受影响的发票。请求正文不能为空；如果没有要选择的内容，请传入 {}。明细项和条款端点则会将已生效的合同重置为草稿，并删除尚未发送的发票。拒绝响应为 BillingContractOperationRejected，消息中包含处理办法；应先阅读消息，而不是重试。BillingContractEditBlocked 为终止错误，只能使用贷项通知单或新建合同。

发票和贷项通知单：请参阅同一份文档。

何时不应使用此技能

• 自助式目录建模——计划、附加项、收费项、优惠券 → stigg-pricing-modeling。
• 未关联合同的订阅生命周期 → stigg-subscriptions。
• 额度币种、授予额度、账本 → stigg-credits。
• 按实体设置预算和用量限制 → stigg-governance。

常见错误

每种错误及其修复方法：

• 仅用于配置时省略 setupBilling — 默认值为 true；请发送 false。
• 附加自助订阅 — 自助套餐无法加入。请使用自定义套餐。
• 使用 PATCH subscriptionIds 添加订阅 — 这会替换整个集合。请使用 POST /contracts/:id/subscriptions。
• 通过归档移除订阅 — 这会取消合同 以及 每个订阅。请改为解除关联。
• 认为合同才是授予权益的对象 — 实际上是订阅。空合同不会授予任何权益，也不包含价格或数量。
• 产品重复时重试 409 — 这是建模冲突，并非暂时性错误。请先解除关联该产品的订阅。
• 自行编制定价表 — 定价取自现有模型，并通过 ID 选择。只填写该模型提供的输入项。
• 未阅读摘要就发布 — 发布后，客户发票将采用摘要中的这些数字。
• 重试 BillingContractEditBlocked — 这是终止性错误：请使用贷项通知单或新合同。
• 期望获得发票 PDF 的 URL — PDF 以行内 Base64 形式返回，没有持久链接。GET .../pdf 会等待，或者轮询生成和状态接口。