sumsub-create-poa-preset

Sumsub — POA プリセットの作成

簡潔な仕様から POA プリセットの JSON ペイロードを作成し、Sumsub API に POST して、1 つ以上のレベルに level.requiredIdDocs.docSets[].poaStepSettingsId で設定できるよう、作成されたプリセットの id を返します。

前提条件 — レベルに PROOF_OF_RESIDENCE ステップが必要です。 少なくとも 1 つのレベルの PROOF_OF_RESIDENCE（または PROOF_OF_RESIDENCE2／3／4）ドキュメントセットに設定しない限り、POA プリセットは効果がありません。ユーザーが POA ステップを含むレベルをまだ作成していない（または説明していない）場合は、プリセットを作成する前にその旨を伝えてください。単独で作成しても意味はありません。

エンドポイント

メソッド	パス	使用する場面
POST	/resources/api/agent/poaStepSettings	新しいプリセットを作成します。リクエストボディに id を含めてはいけません。id はサーバーが割り当てます。
PATCH	/resources/api/agent/poaStepSettings	既存のプリセットを更新します。リクエストボディに id を含める必要があります（URL ではなくフィールドとして指定します）。
GET	/resources/api/agent/poaStepSettings/{id}	プリセットを読み戻します。作成結果の確認や、既知の id から name を解決する際に使用します。

いずれも manageClientSettings 権限が必要です。リクエストボディの形式は POA プリセットのスキーマに従います。指定できるのはクライアントが設定可能なフィールドのみです（clientId、createdAt、createdBy、modifiedAt、監査証跡はサーバーが管理し、レスポンスに含めて返します）。

作成後は、レベルを編集して、任意の PROOF_OF_RESIDENCE ドキュメントセットの requiredIdDocs.docSets[].poaStepSettingsId = "<the new id>" に設定します。

認証 — App Token とシークレット（サンドボックスのみ）

このスキルは Sumsub の公開 API を使用し、 認証リファレンスに従って各リクエストに署名します。仕組みの詳細は sumsub-api-auth スキルに記載されています。401 Invalid signature が発生した場合は、そちらを確認してください。

⚠️ サンドボックスのトークンのみ使用できます。 ここでは本番環境の App Token を受け取ったり使用したりしないでください。ユーザーが本番環境のトークンを提示した場合は使用を断り、https://cockpit.sumsub.com/checkus/home?sbx=true でサンドボックス用のペアを生成するよう依頼してください（Connect Sumsub to your AI agent → Build & configure → Generate token）。トークンとシークレットは一度しか表示されないため、ダイアログを閉じる前に両方をコピーしてください。ヘルパースクリプトではこの条件が強制されており、sbx: で始まらないトークンは拒否されます。

変数	例
SUMSUB_APP_TOKEN	sbx:... — ダッシュボードで生成したサンドボックスの App Token。
SUMSUB_SECRET_KEY	トークン作成時に一度だけ表示される、対応するシークレット。
SUMSUB_BASE	任意。デフォルトは https://api.sumsub.com です。

ユーザーが会話ですでに認証情報を提示している場合は、それを再利用してください。そうでない場合は、実行前に一度だけ確認してください。シークレットをユーザーに返してはいけません。

テナントのエンタイトルメント

POA プリセットの作成には、従来 POA エンタイトルメントが必要でした。しかし、実際には、多くのテナントでエンタイトルメントの有無にかかわらず API が書き込みを受け付けます。エンタイトルメントは基本プランに含まれている場合や、ほかのキーでカバーされている場合、または単に allowedChecks に表示されない場合があります。存在しないことを理由に処理を中断しないでください。

1. sumsub-check-permissions を呼び出し、allowedChecks を確認します。これは診断のための参考情報です。
2. POA がある場合 — 続行します。
3. POA がない場合 — 続行し、ドキュメントに記載されたエンタイトルメントが一覧にないことを、ユーザーに一文で伝えます（POST が失敗した場合にサポートへ伝えられるようにするためです）。確認のために処理を止めてはいけません。テナントに本当に権限がない場合は Sumsub が書き込みを拒否します。その際の 4xx エラーの方が、事前に処理を止めるより多くの情報を得られます。
4. POST がエンタイトルメントに関する 4xx を返した場合 — エラーボディをそのまま提示し、CSM または Sumsub サポートへの問い合わせを提案します。

手順

0. テナントのエンタイトルメントを取得する — 上のセクションを参照してください。

1. ユーザーの意図を簡潔な仕様に変換する（以下を参照）。多くのユーザーは、「何を受け付けるか」（銀行取引明細書、公共料金の請求書など）と「どのくらいの期間有効か」（有効期間の月数）でプリセットを説明します。それを providers キー、subTypes、validMonths に対応付けてください。

2. 検証する：name が空でないこと、includedCountries と excludedCountries が同時に設定されていないこと、各プロバイダーキーが PoaCompanyContactType であること、すべての subTypes エントリーが PoaSubType であること、各国コードが ISO-3166-1 alpha-3 の大文字表記であること、crossValidator.fuzzyThreshold が [0, 1] の範囲内であることを確認してください。

3. ${CLAUDE_SKILL_DIR}/scripts/build_poa_preset.py を使ってペイロードを生成する（標準入力に簡潔な仕様を渡すと、標準出力に完全なペイロードが出力されます）。

4. 新規作成か更新かを判断する：

   • 新しいプリセット — ${CLAUDE_SKILL_DIR}/scripts/post_poa_preset.sh を使って POST します。ペイロードに id を含めてはいけません。
   • 既存のプリセットを更新 — まず ${CLAUDE_SKILL_DIR}/scripts/get_poa_preset.sh で現在の状態を GET して、ユーザーに差分を確認してもらってから、${CLAUDE_SKILL_DIR}/scripts/patch_poa_preset.sh を使って PATCH します。ペイロードにはプリセットの id を含める必要があります。

5. ダッシュボードのリンクを作成する。 レスポンス本文から id と clientId を読み取り、次の形式にします：

   https://cockpit.sumsub.com/checkus/sdkIntegrations/globalSettings/userVerification/proofOfAddress/<id>?clientId=<clientId>&sbx=true
   

   sbx=true クエリパラメーターはSandboxワークスペースを指定します。これは、すべてのスキルで共通の標準的なサンドボックスリンク用パラメーターです。

6. 結果を報告する — 人が読める名前を最初に示し、id は最後に、次の API 呼び出しに渡す値として記載します：

   • 名前と国の範囲（含む／除外）、および国別オーバーライドの対象国。
   • 受け付ける内容の簡単な概要（対象となるプロバイダーの種類、デフォルトの有効期間）。
   • ダッシュボードのリンクをクリック可能な Markdown リンクとして記載します。
   • 最終行：Preset ID for level wiring: <id>。

簡潔な仕様の形式（標準入力に JSON または YAML を指定）

name: "Standard POA (6 months)"
desc: "Default Proof of Address rules with 6-month validity"

# Country scope — choose AT MOST ONE
# includedCountries: [GBR, DEU, FRA]    # allow-list
excludedCountries: [PRK, IRN]            # block-list

# Global defaults
settings:
  acceptMultiplePages: true
  acceptDocScreenshot: true
  requireCountryMatch: false             # require POI country == POA country
  useIssueDateForExpiry: false           # use only issueDate (ignore expiry) for "fresh enough" check
  validMonths: 6                         # shortcut: applied to every provider that omits its own validMonths
  addressTypes: [dwelling, poBox]        # allowed PoA address types
  acceptableLanguages: [en, de, fr]

  # Document providers and the doc sub-types each may produce
  # Keys (PoaCompanyContactType): bank | utilityProvider | governmentOrganization | mobileOperator | other
  providers:
    bank:
      validMonths: 6
      acceptUnconventional: true         # accept non-mainstream banks (with allowedOrgNames below)
      subTypes: [bankStatement, bankLetter, other]
      allowedOrgs:                       # only used when acceptUnconventional=true
        names:    ["Some Local Co-op Bank"]
        websites: ["coopbank.example"]
      forbiddenDocumentNames: []
      forbiddenOrgNames:    []
      forbiddenOrgWebsites: []
    utilityProvider:
      subTypes: [telecom, utilityBill, other]
    governmentOrganization:
      subTypes: [statement, voterRegistration, taxBill, other]
    mobileOperator: {}                   # accept defaults
    other:
      subTypes: [lease, other, universityLetter]

  # Accept identity document as proof of address
  poiAsPoa:
    enabled: true                        # acceptPoiAsPoa
    sameDoc:  true                       # acceptSamePoiAsPoa (same doc for POI + POA)
    validMonths: 3
    allowedTypes: [PASSPORT, ID_CARD, RESIDENCE_PERMIT, DRIVERS]

  # Name/address comparison between POI and POA
  crossValidator:
    nameMode:    weakContainment         # strict | weakContainment | def | ai | fuzzy | containment | fuzzyContainment
    addressMode: fuzzy                   # strict | fuzzy
    fuzzyThreshold: 0.75
    ignoreMiddleName: false
    ignoreFixedInfo: false

# Per-country overrides — same shape as `settings`. Only the keys you set are overridden;
# others fall through to the global `settings`.
byCountry:
  BRA:
    validMonths: 3                       # tighter validity for Brazil
    providers:
      bank:
        validMonths: 3

プロバイダーの種類の値（providers.<key>）

bank、utilityProvider、governmentOrganization、mobileOperator、other。

サブタイプ（providers.<key>.subTypes[]）

statement、voterRegistration、taxBill、telecom、utilityBill、bankStatement、bankLetter、lease、universityLetter、employmentLetter、other。

住所の種類（addressTypes[]）

dwelling、poBox、poBoxSpecialCountries。

POI-as-POA の allowedTypes[]

標準の IdDocType 値：PASSPORT、ID_CARD、RESIDENCE_PERMIT、DRIVERS（その他はまれです）。

氏名比較モード（crossValidator.nameMode）

strict、weakContainment、def、ai、fuzzy、containment、fuzzyContainment。

住所比較モード（crossValidator.addressMode）

strict、fuzzy。

出力

成功した場合は、人が読める情報を最初に示します：

• name、国の範囲、国別オーバーライドの対象国の一覧。
• 簡単な概要（対象となるプロバイダーの種類、デフォルトの有効期間）。
• ダッシュボードのリンク：https://cockpit.sumsub.com/checkus/sdkIntegrations/globalSettings/userVerification/proofOfAddress/<id>?clientId=<clientId>&sbx=true。クリック可能な Markdown リンクとして表示します。id と clientId はどちらも POST レスポンス本文から取得します。sbx=true は Sandbox ワークスペースを指定します。
• 最後に、独立した行に次を記載します：Preset ID (for level wiring / future PATCH): <id>。

失敗した場合：HTTP ステータスと Sumsub の description／errorName を示します。ビルダーは、無効な列挙値や不可能な組み合わせを事前に、具体的なメッセージとともに拒否します。

ユーザー向けメッセージでは ID ではなく名前を使う

これはプリセットに関するすべてのメッセージに適用されます。POST 前の概要、中間の進捗状況の更新、引き継ぎの文も対象であり、最終レポートだけではありません。

• 本文では、プリセットを id ではなく name（「POA — 60 days」）で示してください。
• id を記載するのは、最後の専用行（Preset ID for level wiring: <id>）だけにしてください。ユーザーがレベルの poaPresetId にコピーする必要があるため、この行に限り生の ID が正しい形式です。
• 呼び出し元がこのプリセットを PROOF_OF_RESIDENCE ステップに連携するレベルスキルの場合、レベルスキルも POST 前の概要でこのプリセットを名前で示してください。詳しくは sumsub-create-level を参照してください。

sumsub-create-level への引き継ぎ

返された id は、レベルの PROOF_OF_RESIDENCE ドキュメントセットに渡す値です。レベルスキルでは、わかりやすいショートカット poaPresetId（または正規の poaStepSettingsId）として公開されます。

{
  "type": "PROOF_OF_RESIDENCE",
  "docTypes": ["UTILITY_BILL", "BANK_STATEMENT"],
  "poaPresetId": "<id from this skill>"
}

sumsub-create-level/examples/with-presets.json を参照してください。

使用例

• examples/minimal.json — 銀行・公共料金・政府機関の書類に対する6か月のデフォルト設定を備えた最小限のプリセット。POI を POA として扱う設定はオフです。
• examples/eu-bank-friendly.json — EU のみを対象としたプリセット。銀行取引明細書の有効期間は長めで、POI を POA として3か月間使用できます。
• examples/per-country-tight.json — グローバルなデフォルト設定と、より厳しいブラジルの上書き設定を備えています。

関連項目

• references/poa-preset-schema.md — PoaStepSettings の完全なスキーマ、すべての列挙型、および注意点。