stigg-contracts

Stigg Contracts — エンタイトルメントと請求

契約は、営業主導の取引における信頼できる唯一の情報源です。つまり、顧客が利用できる内容と、その対価として請求する金額を定めます。契約は、1 人の顧客のサブスクリプションをまとめ、それらのサブスクリプションがエンタイトルメントを付与します。契約はサブスクリプションが属する合意であり、別個のエンタイトルメント付与の仕組みではありません。また、請求書を作成する請求契約を含めることもできます。この 2 つは独立しているため、請求契約のない契約でもアクセス権はプロビジョニングされます。

契約自体は商取引条件を保持しません。 価格、数量、コミットメントのフィールドはなく、名前、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 に問い合わせてください。

どのように始めますか？

ダッシュボードでは、独立した 2 つのチェックボックス（アクセスをプロビジョニング、請求を設定）とともに、まさにこの質問が表示されます。そのため、始め方は3 通りあります。まずどれにするか決めてください。それによって、以下のすべての手順が決まります。

選択肢	契約の内容	送信する内容
プロビジョニングのみ	カスタムサブスクリプションをまとめ、そのエンタイトルメントを付与します。請求書は作成されません。	setupBilling: false + subscriptions
請求のみ	価格付きの明細項目と請求書を作成します。サブスクリプションは関連付けません。	setupBilling: true、subscriptions なし
両方	1 つの契約でエンタイトルメントと請求処理を行います。署名済み注文書で一般的な形式です。	setupBilling: true + subscriptions

setupBilling はデフォルトで true のため、プロビジョニングのみの場合は明示的に指定する必要があります。

用語 — すべての名称を理解し、口頭では 1 つだけ伝えてください。 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 プランが該当します。FREE プランのサブスクリプションは契約に追加できません（stigg-pricing-modeling）。

先に顧客のアカウントをプロビジョニングしてください。 顧客が存在してから契約を作成します。

サーバー側には 3 つのルールがあります。製品ごとにサブスクリプションは 1 つ、通貨は 1 種類、そしてすべてのサブスクリプションは契約の顧客に属していることです。

両方の場合：実行する順序

注文書から作成する場合は、まず契約を作成し、サブスクリプションをプロビジョニングさせます。単独でプロビジョニングすると、2 回目の書き込みで関連付けるまで、サブスクリプションが有効なまま未関連付けの状態になります。契約を先に作成する方法はどちらも 1 回のトランザクションです。newSubscription エントリを指定して POST /contracts を呼び出す方法、または後から同じエントリを指定して 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 のどちらか一方だけを指定します。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 だけでなく、全体を置き換えます。リストから ID を省くと、その 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。 まず、次の5点を確認してください。

1. 最初の書き込みの前に、内容全体を読み合わせて確認します。 注文書は仕様書ではありません。価格モデルと行を含むすべての明細、条件、法人、顧客を一つずつ読み上げ、書き込み呼び出しを行う前に合意を得てください。公開前の確認では遅すぎます。明細はすでに作成されています。矛盾は解消せず、明らかにしてください。注文書では明細が予測可能な形で抜け落ちます。使用量ベースの明細には金額が表示されず、Included の明細は価格0で登録し、期間ごとの表は1つの契約であり、「purchase order reference」は多くの場合 N/A で、注文番号ではありません。それぞれについてはリファレンスで説明しています。
2. 明細の価格設定には既存の価格モデルを使います。独自の表は作成しないでください。 GET /contracts/pricing-models で isPayAsYouGo と editableInputs を含む一覧を取得できます。モデルが公開している入力のみを、rows が受け付ける名前で指定してください。請求タイプは前払い（IN_ADVANCE）または後払い（IN_ARREARS）です。エンジンの DURING_USE／AFTER_USE は拒否されます。従量課金は従量制の明細にのみ適用され、数量を指定しません（使用量から提供されます）。また、常に後払いです。モデルは名前ではなく、isPayAsYouGo と形状で特定してください。同じ名前を持つ反対カテゴリのモデルが10個中5組あり、どちらも同じ行を受け付けて200を返すためです。references/pricing-models.md では、取引の形状に合うモデルと、それぞれに最も近い誤った候補を対応付けています。
3. 法人には支払いアカウントが必要です。 GET /contracts/legal-entities で各法人のアカウントを一覧表示できます。paymentAccounts が空なのは、よくある設定漏れの状態です。これを作成する API はありません。契約を作成する前に対応してください。そうしないと、契約が完成したように見えても公開時に拒否されます。期間、通貨、支払い条件とあわせて、PATCH .../billing/settings と .../billing/terms で設定します。これらは契約全体に適用されるため、明細ごとの例外を設定する前に適用してください。
4. 公開前に、ドラフトでも実行できる2つのチェックを行います。 注文書の数値と照合する 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が返ると期待する — インラインのbase64形式で返され、永続的なリンクはありません。GET .../pdfの応答を待つか、生成／ステータスのエンドポイントをポーリングしてください。