メインコンテンツまでスキップ

「パートナーシップの一時停止と再開」

Audience

このAPIサーフェスは、Roktネットワーク上で構築する統合パートナー向けです。Roktのeコマースパートナーで独自のチェックアウトに配置を統合する場合は、代わりにRokt Ecommerce開発者ドキュメントを使用してください。

ステータスPUTは、アカウント上のすべての非アーカイブページバリアントに対してアクティブ/一時停止をカスケードする単一の粗いスイッチです。アーカイブされたバリアントは影響を受けません。パートナーシップAPIを介したページごとまたはバリアントごとの一時停止はありません。それはRokt内部の操作です。

これを使用するのは、マーチャントからの一時的な一時停止の要求、詐欺の保留、紛争解決、計画されたプラットフォームメンテナンスです。

  1. Pause the partnership

    PUT /v1/partnership/accounts/{account_id}/status with { "status": "paused" }。すべての非アーカイブバリアントが1つのトランザクションで無効になります。

    curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
      -H "Authorization: Bearer $TOKEN" \
      -H "X-Platform-Parent-Account-Id: $PARENT" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{ "status": "paused" }'

    レスポンスは、GETから取得したStatusCascadeResponseをラップする同じエンベロープです：dataの下に集約とバリアントごとの詳細があります。

  2. Verify the pause

    ステータスGETをラウンドトリップします。集約statusは"paused"であるべきで、variantsのすべてのエントリは"paused"を示すべきです。

    curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
      -H "Authorization: Bearer $TOKEN" \
      -H "X-Platform-Parent-Account-Id: $PARENT"
    {
      "status": 200,
      "error": null,
      "message": "ok",
      "request_id": "0e3a1b9c-...",
      "data": {
        "account_id": "<your-account-id>",
        "status": "paused",
        "variants": [
          { "page_id": "...", "name": "Confirmation - Default", "status": "paused" },
          { "page_id": "...", "name": "Confirmation - Mobile",  "status": "paused" }
        ]
      }
    }
  3. Resume the partnership

    再度有効化する準備ができたら、PUT status: "active"を実行します。同じカスケードが逆方向に行われます。

    curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
      -H "Authorization: Bearer $TOKEN" \
      -H "X-Platform-Parent-Account-Id: $PARENT" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{ "status": "active" }'
  4. Verify the resume

    ステータスをGETします。集約は"active"であり、すべての非アーカイブバリアントは"active"を示すべきです。

    curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
      -H "Authorization: Bearer $TOKEN" \
      -H "X-Platform-Parent-Account-Id: $PARENT"

ラウンドトリップアイデンティティラウンドトリップアイデンティティ への直接リンク

成功したPUT status=pausedの後、GET statusは"paused"を返さなければなりません。PUT status=activeの後、GET statusは"active"を返さなければなりません。

警告

"mixed"の解釈は、PUTレスポンスから来たかGETから来たかによって異なります。

  • PUT自体によって返された"mixed"（またはPUTの直後に発行されたGET status、他のアクターがアカウントに触れる前）は、バグ状態です：カスケードが一部のバリアントの更新に失敗しました。サポートチケットをIdempotency-KeyとPUTレスポンスエンベロープのrequest_idと共に提出してください。GETからのバリアントごとの内訳を含めて、サポートが特定のスタックバリアントをターゲットにできるようにしてください。
  • 定常状態の"mixed"によって返されたGET status（つまり、PUTを発行していない、または他のアクターが変更を加える可能性があるほどの時間が経過している）は、必ずしもバグではありません。正当な原因については次のセクションを参照してください。

GETにおける"mixed"の意味GETにおける"mixed"の意味 への直接リンク

PUT直後のウィンドウの外では、"mixed"は正当な定常状態の値です。それは失敗したカスケードの後にのみ表示されるわけではありません。GET statusで次のような場合に表示されます：

  • パートナーが一部のページバリアントをアーカイブし、他をアーカイブしなかった場合、非アーカイブセットが分割されている。
  • RoktサポートがパートナーシップAPIの外で個々のバリアントを手動で切り替えた（例：インシデント中）。
  • 前のステータスカスケードが部分的に失敗し、再試行されなかった。

集約statusは、非アーカイブバリアントのみを対象に計算されます。variants配列は、どのバリアントがどの状態にあるかを正確に示します。これを使用して、"mixed"が予想されるもの（パートナー主導のアーカイブ、Rokt側の切り替え）か、問題（カスケードバグの場合、上記の警告に記載されたようにエスカレート）かを判断してください。

冪等性冪等性 への直接リンク

ステータスPUTは、Idempotency-Keyに対して完全に冪等です。

  • 同じ{ "status": "paused" }を24時間の重複排除ウィンドウ内で同じキーと共に再送信すると、キャッシュされた結果が返されます。
  • 24時間のウィンドウが経過するとキーは期限切れとなり、再利用すると新しい実行がトリガーされます。論理的な再試行グループごとに新しいUUIDを使用してください。
  • 新しいキーで同じペイロードを再送信すると、操作なしの書き込みとなります：すでに一時停止されたバリアントはそのまま停止され、サーバーはdataで現在のカスケード応答を返します。

再試行は無料です。5xxエラーが発生した場合は指数バックオフを使用してください。

なぜ粗粒度なのか？なぜ粗粒度なのか？ への直接リンク

Partnerships APIは意図的にアカウントレベルの一時停止のみを公開しています。ページごとやバリアントごとの制御はRokt One PlatformのUIに属し、Roktの運用とパートナー自身の内部ツールが調整できます。パートナー向けのインターフェースを粗く保つことで、次の2つの失敗モードを回避します：

  1. パートナーがRokt側のバリアント変更と同期しなくなるUIを構築すること。
  2. 収益が静かに半減する、デバッグが難しい部分的な一時停止状態。

バリアントごとの制御が必要な場合は、Partnershipsエンジニアリングリクエストを提出してください。APIに含めるべきか、サポートされたバックチャネルに含めるべきかを評価します。

この記事は役に立ちましたか？
Last updated Aug 4, 2026