Waafir
このページは機械翻訳であり、人による確認を待っています。誤りが含まれている可能性があります。

waafir-esign リファレンス

waafir-esign サーバーは、Waafir 独自の電子署名サービスを接続された AI クライアントに提供します。組織内のファイルに対してエンベロープを作成し、署名者に署名(または辞退)してもらい、状況を追跡し、署名済み PDF をダウンロードできます。署名は Waafir 独自の署名エンジンが生成する eIDAS AES(PAdES) です。すべての署名で署名者の同意(IP アドレス、ユーザーエージェント、タイムスタンプ)が改ざん検知可能な監査証跡に記録され、署名済み PDF はソースファイルの最新バージョンとして保存されます。

接続:https://app.waafir.io/api/mcp/waafir、または領域サーバー https://app.waafir.io/api/mcp/waafir-esign。セットアップを参照してください。ツール名はどちらでも同じです。読み取りツールには、サインインで作成した接続または PAT で read スコープが必要です。作成、送信、辞退、署名者の修正、無効化には write スコープが必要です。署名には write とドキュメントに署名する権限が必要です。この権限は、接続の場合は同意画面で承認し、トークンの場合は作成時にオンにします(トークンにドキュメントへの署名を許可するを参照)。この権限がない場合、esign_sign はツール一覧に表示されず、呼び出しても拒否されます。特定のデータルームに制限された接続やトークンは、それらのデータルーム内のファイルに対するエンベロープのみを扱えます。これはデータルームツールが適用するのと同じ境界です。

月間エンベロープクォータ

電子署名はエンベロープ単位で計量されます。1 つの文書 / 署名ジョブは、署名者が何人いても 1 回とカウントされます。この MCP サーバーとアプリ内の署名画面は、どちらも共有の 1 つの月間プールから消費します。

  • アクセスにはE-Signatures アドオン、または有効な Waafir サブスクリプションが必要です。どちらもない場合、waafir-esign へのすべてのリクエストは、ツールが実行される前に入口で HTTP 402 により拒否されます。これは第 1 層の拒否です。ADDON_NOT_PURCHASED はそのレスポンスの message テキストに含まれますが、機械可読な独立したフィールドではないため、コードではなく 402 ステータスで分岐してください。waafir では、esign_ ツールは代わりにツール一覧から非表示になり、そのいずれかを呼び出すと第 2 層で QUOTA_EXCEEDED として拒否され、そのツールを名指しするメッセージが返されます。このメッセージには ADDON_NOT_PURCHASED も含まれます。
  • プランには月間エンベロープバンドルが含まれます:Starter 10、Premium 50、Enterprise はアクティブシート 1 つにつき 50(暦月単位)。
  • E-Signatures アドオンを 1 ユニット購入するごとに、プランのバンドルに加えて月 100 エンベロープが追加されます。ユニットはどのプランでも積み増しできます。
  • クォータは厳格な上限です。上限に達した状態でエンベロープを送信すると、送信はワイヤーコード QUOTA_EXCEEDED で拒否され、ユニットの追加購入またはアップグレードを促されます。エンベロープごとに自動的に課金されることは決してありません。メッセージテキストには内部トークン ESIGN_QUOTA_EXCEEDED も記載されますが、これは説明文なので、QUOTA_EXCEEDED である error.code で分岐してください。上限に達した send: true の作成呼び出しでも下書きは残ります。作り直すのではなく、余裕ができたらその下書きを送信してください。

クォータが消費されるのは、エンベロープが送信された(署名受付が開始された)ときであり、署名ごとではありません。そのため、署名や辞退でクォータが消費されることはありません。読み取りやダウンロードでも消費されません。余裕はいつでも esign_quota_status で確認できます。

自社の NDA を電子的に署名する

組織が自社の NDA をアップロードすると(投資家 → NDA → 自社の NDA をアップロード、カスタマイズ性を参照)、各投資家は Waafir の署名画面でそれに署名します。サインイン済みの投資家が NDAに署名 を選択すると、文書が新しいタブで開きます。共有リンクからの訪問者は、入力したアドレスに署名リンクがメールで届きます。これらの NDA エンベロープは月間クォータにカウントされず、NDA テンプレート自体を通常のエンベロープのように送信することはできません。

ツール

このサーバーの引数と結果のキーは snake_case です。これは他のすべての Waafir MCP サーバーと同じ規則です。file_id, envelope_id, signing_mode, field_layout, consent_affirmed, confirm_send, download_url, has_more.

破壊的変更:waafir-esign は以前 camelCase の引数を受け付けていました。 fileId、envelopeId、signingMode、fieldLayout、consentAffirmed は受け付けられなくなりました。それぞれに snake_case の表記があり、下の表に記載しています。confirm_send はもともと snake_case だったため変更はありません。

廃止された表記が必須の引数だった場合、それは黙って受け入れられるのではなく拒否されます。esign_create_envelope に依然として fileId を送信する呼び出しは引数の検証で失敗し、不足しているキーとして file_id が示されます。任意の引数だった場合は、他の認識されないキーと同様に黙って破棄されます。下記の 2 つの失敗パターンを参照してください。呼び出しをこのページの表記に更新してください。

キーのスペルミスは 2 通りの方法で失敗し、そのうち 1 つは気づかれません。 認識されない引数は拒否されることなく破棄されるため、その後どうなるかは、意図したキーが必須だったかどうかだけで決まります。

  • 必須キー → 呼び出しが拒否される。その引数が単に欠落した状態になります。これは明示的で安全なケースであり、esign_create_envelope(file_id)、esign_get_envelope、esign_sign(envelope_id と consent_affirmed)、esign_decline、esign_void_envelope、esign_revise_signers(envelope_id と signatories)、esign_download_signed が該当します。これらのキーの廃止された camelCase 表記もすべて含まれます。

    error.code は含まれません。引数はツールが実行される前に、ツールが公開しているスキーマに対して検証されるため、必須キーの欠落(または型の誤り)はサーバー自体が生成するエラー結果として返されます。レスポンスはエラーとしてフラグが立てられ、テキストには問題の引数が示されますが、ツールは実行されていないため、第 2 層の error.code フィールドには何も設定されません。引数の形式に関する失敗では INVALID_ARGUMENT で分岐せず、メッセージを読んでください。形式が不正な confirm_token のように、ツールの実行開始後に発生する拒否では、引き続き INVALID_ARGUMENT が返されます。

  • 任意キー → 呼び出しは成功するが、別の処理が行われる。200 と整った形式の結果が返りますが、それは別の問いに対する答えです。

    • esign_list_envelopes のフィルターは任意のため、紛れ込んだ fileId は破棄され、トークンが参照できるすべてのエンベロープのフィルターされていない一覧が返されます。フィルター済みの回答であるかのように上位集合が返されるのです。
    • esign_create_envelope で signingMode: "sequential" が破棄されると、エンベロープはデフォルトの parallel モードのままになります。その後送信すると、法的拘束力のある署名リクエストのメールがすべての署名者に同時に送られます。これはまさに sequential を指定して防ごうとしたことです。fieldLayout も同様に破棄されます。

破棄された任意キーは自らそのことを知らせられないため、結果が要求した内容を反映しているかを確認してください。作成されたエンベロープは自身の signing_mode を報告し、esign_list_envelopes はフィルターのスペルが正しい場合にのみフィルターされます。

esign_create_envelope(書き込み)

組織内のファイルに対してエンベロープを作成し、署名者を指定します。どのメールアドレスでも受け付けられ、署名者が Waafir アカウントを持っている必要はありません。 各署名者への連絡方法は、エンベロープが送信されるときに、そのアドレスにすでに Waafir アカウントがあるかどうかで決まります。アカウント保有者はセッション内で署名し(アプリ内通知と、署名画面へのリンクを含むメール)、それ以外の人にはゲスト署名リンクがメールで送られます。判定基準はアカウントの有無であり、組織への所属ではないため、別の組織に所属する署名者もセッション内で署名します。保留中の各署名者は、必ずどちらか一方だけを受け取ります。両方を受け取ることも、どちらも受け取らないこともありません。

フィールド型必須説明
file_idstring (UUID)はい署名対象のファイル。組織に属している必要があります。
signatoriesarrayはい{ "email": string, "name"?: string } を 1~50 件。どのメールアドレスでも受け付けられ、署名者が Waafir ユーザーである必要はありません。外部のアドレスにはゲスト署名リンクが送られます。
transaction_idstring (UUID)いいえ非推奨で、無視されます。 既存の統合が動作し続けるよう受け付けていますが、送信をやめてください。
sendbooleanいいえtrue の場合、エンベロープの署名受付を直ちに開始します。処理は 2 段階です(下記参照)。組織外のユーザーに送信 がオンになったトークンが必要です。
confirm_tokenstringいいえsend: true の場合のみ:プレビュー呼び出しで得たトークン。
confirm_sendbooleanいいえ非推奨で、無視されます。send: true では現在 confirm_token を使用します。
signing_mode"parallel" | "sequential"いいえ署名の順序。"parallel" がデフォルトです。署名者は任意の順序で署名でき、送信時には全員に同時にメールが送られます。"sequential" は最初の署名者にのみメールを送り、それより前の全員が署名するたびに次の署名者を解放します。順番を守らない署名は CONFLICT で拒否されます。省略した場合(または signingMode とスペルミスした場合)は "parallel" になります。
field_layoutarrayいいえフィールド配置レイアウトの上書き。デフォルトのレイアウトを使う場合は省略します。
observersarrayいいえ{ "email": string, "name"?: string } 形式のオブザーバー(CC)を最大 20 人。オブザーバーには、署名リクエストと各リマインダーのコピーが、状況を確認できる読み取り専用リンクとともにメールで送られます。オブザーバーは署名せず、署名済みのコピーも送られません。

send: true は 2 段階で処理されます。送信が成功した瞬間に、一覧のすべてのアドレスに実際の法的拘束力のある署名リクエストのメールが送られるためです。最初の呼び出しでは何も作成も送信もされず、プレビュー(署名者、オブザーバーの数、クォータ)と confirm_token が返されます。同一の引数とそのトークンでもう一度呼び出すと、作成と送信が行われます。トークンは 1 回しか使えず、数分後に期限切れになります。権限付与がない場合、send: true は FORBIDDEN(GRANT_REQUIRED)で拒否されます。その場合は send なしでエンベロープを作成し、Waafir で送信してください。

esign_revise_signers も、誰かにメールを送ることになる場合(送信済みエンベロープへの新しい署名者やオブザーバーの追加)は、同じ 2 段階の処理と同じ権限付与が必要です。

エンベロープを返します。そのフィールドは正確に id、file_id、status、signing_mode、created_by、signed_output_name、signed_output_version_count、field_layout、packet_page_count、expires_at です。結果は手作業でマッピングされた許可リストであるため、それ以外のものは送信されません。タイムスタンプは ISO-8601 文字列です。

下書きのエンベロープは、誰かが署名する前に送信する必要があります。送信すると月間クォータからエンベロープが 1 つ消費されます。上限に達している場合、send は QUOTA_EXCEEDED を返し、エンベロープは後で送信できる下書きのまま残ります。誤って送信したエンベロープは esign_void_envelope で撤回できます。

まだチェック中のファイル。 ファイルが、Waafir のチェックがまだ完了していない新しいアップロードまたは新しいバージョンである場合、呼び出しは error.reason: "ACTIVATION_PENDING" とメッセージ This file is still being checked. Try again shortly. を伴う UNAVAILABLE を返します。何も作成されません。少し待ってからもう一度呼び出してください。

esign_list_envelopes(読み取り)

組織のエンベロープを新しい順に、各エンベロープの署名者と状態とともに一覧表示します。任意のフィルター:file_id。(transaction_id は非推奨で、無視されます。)フィルターは任意であるため、廃止された camelCase 表記は黙って破棄され、呼び出しはエラーではなくフィルターされていない一覧を返します。上記のキーに関する注記を参照してください。

ページネーション:limit(任意、1~100、デフォルト 25)と offset(任意、デフォルト 0)は数値でなければなりません。他の型の値は、他の型の不一致と同様に引数の検証で失敗します。範囲外の数値は拒否されるのではなく範囲内に丸められます。limit: 10000 は 100 に、offset: -2 は 0 になります。戻り値:

{ envelopes: [...],
  pagination: { limit, offset, count, has_more, next_offset, total },
  filtered_by_pat_scope: boolean }

途中で切れた結果と完全な結果を区別するには has_more を使用し、next_offset が null になるまでたどってください。count === limit から次のページの有無を推測しないでください。total はこのトークンが参照できるエンベロープの数です。

filtered_by_pat_scope は、トークンが特定のデータルームに制限されていて、その許可リストによって結果が絞り込まれた場合に true になります。ページの範囲はフィルターの後に適用されるため、ページは常に正確です。これは意図的に、非表示になったエンベロープの数ではなくブール値にしています。いくつ非表示にしたかを報告すると、トークンが参照を制限されているエンベロープの存在と量が漏れてしまうためです。

esign_get_envelope(読み取り)

1 つのエンベロープを、その署名者と状態(pending / signed / declined)とともに取得します。入力:envelope_id。上記の作成ツールのフィールドに加えて、エンベロープには created_at、updated_at、signatories(各要素は { id, email, name, status, signed_at })が含まれます。

esign_sign(書き込み)

あなた自身の保留中の署名枠、つまりトークンを所有するユーザーとメールアドレスが一致する枠に署名します。署名でクォータは消費されません(エンベロープは送信時にすでに計量されています)。ドキュメントに署名 がオンになったトークンが必要です。

署名には 2 回の呼び出しが必要です。これにより、何かに署名する前に、アシスタントがこれから署名する内容を表示します。

  1. プレビュー。confirm_token なしで呼び出します。何も署名されません。結果は dry_run: true で、エンベロープ、順序どおりの documents、それらすべてを対象とする 1 つの document_hash、signer、指定した fields、同意文、confirm_token とその expires_at が含まれます。
  2. 確定。本人が同意したら、同一の引数にその confirm_token を加えてもう一度呼び出します。この呼び出しで署名されます。

confirm_token は 1 回だけ、このトークンとこれらの引数に対してのみ有効で、5 分後に期限切れになります。その間にエンベロープ、その文書、署名順序におけるあなたの位置、またはフィールドが変わった場合、確定は拒否され、再度プレビューすることになります。

フィールド型必須説明
envelope_idstring (UUID)はい署名するエンベロープ。
consent_affirmedbooleanはい文字どおり true でなければなりません。同意文への明示的な確認です。デフォルト値はなく、省略したり false を渡したりすると、呼び出しはプロトコルの境界で失敗します。
fieldsobjectいいえフィールドラベルをキーとする入力値。省略した場合、名前と日付はデフォルト値になります。
confirm_tokenstringいいえ省略するとプレビューになります。署名するには、プレビューが返したトークンを渡します。

確定の呼び出しは { envelope } を返します。これは esign_create_envelope が返すのと同じ許可リスト形式のエンベロープです。

発生しうるエラー:エンベロープの保留中の署名者でない場合は FORBIDDEN、エンベロープの署名受付が開始されていない場合、または sequential のエンベロープでそれより前の署名者がまだ署名していない場合は CONFLICT。これらは HTTP ステータスではなく、ペイロード内の error.code の値です。セットアップを参照してください。

2 段階の確定では、次の拒否が追加されます。それぞれメッセージに (code: …) が含まれます。

error.codecode:対処方法
FORBIDDENGRANT_REQUIREDこのトークンでは署名できません。ドキュメントに署名 をオンにした新しいトークンを作成してください。
INVALID_ARGUMENTCONFIRM_TOKEN_MALFORMEDconfirm_token なしでもう一度呼び出して取得してください。
CONFLICTCONFIRM_TOKEN_INVALIDトークンが期限切れ、使用済み、または別のトークンのものです。再度プレビューしてください。
CONFLICTCONFIRM_ARGS_MISMATCH引数がプレビュー時と異なります。再度プレビューしてください。
CONFLICTCONFIRM_STATE_CHANGEDプレビュー以降にエンベロープが変更されました。再度プレビューして本人に提示してください。
CONFLICTDOCUMENT_NOT_PINNEDこのエンベロープは文書の固定機能の導入前に送信されました。署名メールから Waafir で署名してください。
UNAVAILABLECONFIRM_UNAVAILABLE確定機能が一時的に利用できません。しばらくしてから再試行してください。

エンベロープのレイアウトに必須フィールドがあり、fields でそれが指定されていない場合、呼び出しは INVALID_ARGUMENT で拒否され、メッセージには (code: MISSING_REQUIRED_FIELDS) が含まれます。メッセージには不足しているラベルは示されませんが、アプリ内の署名画面には表示されます。入力してからもう一度呼び出してください。

esign_decline(書き込み)

あなた自身の保留中の署名枠を辞退します(終了状態で、エンベロープは declined になります)。入力:envelope_id。{ id, status: "declined" } を返します。クォータは消費されません。

esign_void_envelope(書き込み)

誤って送信したエンベロープを撤回します。 送るべきではない署名リクエストが送られてしまった場合の対処手段です。エンベロープは署名の受け付けを停止し、未完了のゲスト署名リンクはすべて直ちに無効化され、保留中の署名者は操作できなくなります。

入力:envelope_id。無効化されたエンベロープを、esign_create_envelope が返すのと同じ許可リスト形式で返します。

  • 終了状態。無効化されたエンベロープは再送信できません。代わりに新しいエンベロープを作成してください。
  • すでに記録された署名と監査証跡全体は保持されます。無効化しても、すでに署名されたものは消去されません。
  • 実行できるのは、エンベロープが draft、sent、partially_signed のいずれかの状態にある間だけです。それ以外の状態では CONFLICT が返され、期限切れのエンベロープは古い状態ではなく期限切れであることを報告します。
  • 無効化できる人:署名リクエストを作成した本人、または組織のオーナーや管理者のみです。それ以外の人は FORBIDDEN を受け取ります。エンベロープの当事者ではまったくない呼び出し元は NOT_FOUND を受け取るため、知るべきでない人にエンベロープの存在がツールによって確認されることはありません。
  • 無効化でクォータは消費されず、返還もされません。クォータはエンベロープの送信時に課金されます。

esign_revise_signers(書き込み、破壊的)

エンベロープを無効化してクォータからもう 1 つエンベロープを消費することなく、署名を求める相手を修正します。メールアドレスの入力ミス、相手方の漏れ、署名順序の誤りなどに対応します。エンベロープの id、監査証跡、クォータのユニットはそのまま保持されます。クォータは消費されません。

フィールド型必須説明
envelope_idstring (UUID)はい修正するエンベロープ。
signatoriesarrayはいエンベロープの最終的な署名者の完全な一覧を署名順に:{ "email": string, "name"?: string } を 1~50 件。現在の一覧を置き換えます。
signing_mode"parallel" | "sequential"いいえ署名の順序を変更します。省略すると現在のモードが維持されます。"parallel" にリセットされることはありません。
observersarrayいいえオブザーバー(CC)の完全な一覧、最大 20 人。省略すると現在のオブザーバーが維持されます。一覧から外したオブザーバーは削除され、その読み取り専用リンクは機能しなくなります。

これは破壊的な操作です。 signatories から外した署名者は削除されます。その人への招待は取り下げられ、署名リンクは直ちに機能しなくなり、本人には通知されません。その人のために配置されたフィールドはすべて削除されます。すでにエンベロープに含まれている署名者はリンクを保持し、再度メールが送られることはありません。エンベロープがすでに送信されている場合、新しい署名者には直ちに招待が送られます。このツールには destructiveHint: true が設定されているため、破壊的な呼び出しを確認するクライアントは実行前に確認を求めます。

  • 最初の署名までに限ります。誰かが署名すると、署名者一覧と署名モードは固定されます。呼び出しは CONFLICT (code: ESIGN_SIGNERS_FROZEN) で拒否され、対処方法は無効化して新しいエンベロープを作成することです。期限切れのエンベロープも CONFLICT で拒否されます。
  • オブザーバーだけを変更する場合。変更していない署名者一覧(とモード)を、新しい observers 一覧とともに渡します。オブザーバーの削除は、署名後や完了後を含めていつでも可能です。追加できるのは、エンベロープが下書きまたは署名待ちの間だけです。
  • 送信済みエンベロープを修正できる人:署名リクエストを作成した本人、または組織のオーナーや管理者のみです。それ以外の人は FORBIDDEN を受け取ります。下書きは、それを参照できる人なら誰でも修正できます。
  • その他の拒否では、メッセージに理由が示されます。重複したアドレス(ESIGN_DUPLICATE_SIGNATORY)や空の一覧(ESIGN_EMPTY_ROSTER)は INVALID_ARGUMENT です。送信済みエンベロープが対象とするすべての文書を読み取れない場合に、そのエンベロープに新しい署名者やオブザーバーを追加しようとすると FORBIDDEN になります。

esign_get_envelope と同じ形式のエンベロープに加えて、変更内容の revision 要約(オブザーバーを渡した場合は observer_revision も)を返します。

esign_list_my_pending_signatures(読み取り)

この組織であなた自身の署名を待っているエンベロープを一覧表示します。トークンの所有者のメールアドレスと一致する保留中の署名枠を持つ、すべての受付中のエンベロープです。esign_sign の前に行う読み取りとして最も役立ちます。

入力はありません。{ envelopes: [{ id, file_id, document_name, status, created_at }] } を返します。

範囲はこのトークンの組織、およびトークンが制限されている場合はそのデータルーム許可リストに限定されます。他の組織での保留中の署名は、たとえあなたがそこで署名者であっても表示されません。

esign_download_signed(読み取り)

署名済み PDF の短時間だけ有効な署名付きダウンロード URL を取得します。入力:envelope_id。{ download_url, expires_in_seconds } を返します。エンベロープには少なくとも 1 つの署名が記録されている必要があります。署名済み PDF は、ソースファイルの最新バージョンとして製品内でも利用できます。ドキュメントコンテンツを読む がオンになったトークンが必要で、これがない場合は GRANT_REQUIRED で拒否されます。

esign_quota_status(読み取り)

入力はありません。当暦月の { quota, used, remaining }、つまりエンベロープクォータの合計(プランのバンドル + 購入したユニット)、送信済みのエンベロープ数、上限までの残りを返します。

esign_remind(書き込み)

入力は envelope_id。署名待ちのエンベロープの保留中の署名者全員に再度メールを送り、各オブザーバーにはそのコピーを送ります。エンベロープごとに 1 時間に 1 回までです。組織外のユーザーに送信 が必要で、2 段階で処理されます。最初の呼び出しでは何も送信されず、メールを受け取る人(オブザーバーは名前付き)と confirm_token が返されるので、それを付けてもう一度呼び出します。その間にオブザーバーが追加されると、確定は失敗します。ディールチームメンバーのみが使用できます。

esign_resend_signatory(書き込み)

入力は envelope_id、signatory_id。バウンスまたは抑止されたアドレスをクリアし、その署名者に再度メールを送ります。権限付与と 2 段階の処理は esign_remind と同じです。

esign_send_draft(書き込み)

入力は envelope_id。保存された下書きを送信します。すべての署名者に法的拘束力のある署名リクエストがメールで送られ、すべてのオブザーバーにコピーが送られ、クォータからエンベロープが 1 つ消費されます。権限付与と 2 段階の処理は同じです。プレビューには署名者、オブザーバー、クォータが示され、プレビューした署名者一覧とオブザーバーがそのまま送信されます。結果には、メールが送られなかった suppressed のアドレスが一覧表示されます。

esign_preview(読み取り)

入力は envelope_id。署名パネルに表示されるとおりにエンベロープを返します:{ envelope_id, status, file_id, document_name, is_creator, signers, placed, fields, shows_signed_output, shows_live_source }。文書を読み取る権限がない場合、document_name は null です。文書の内容は返されません。ディールチームメンバーのみが使用できます。

esign_verify(読み取り)

入力は envelope_id。Waafir の検証ページに表示される証明書と完全性の要約を返します。ディールチームメンバーのみが使用できます。

法的有効性

署名は eIDAS の高度電子署名(PAdES)であり、米国の ESIGN/UETA および EU の eIDAS のもとで NDA や契約に有効です。署名者の同意(IP、ユーザーエージェント、タイムスタンプ)は、署名時に Waafir の追記専用でハッシュチェーン化された監査証跡に記録されます。この MCP サーバーを通じて作成または送信されたエンベロープは、その証跡にトークン起点の操作として記録されるため、エージェントが開始した送信は、人がアプリで行った送信と常に区別できます。適格電子署名(QES)は本リリースには含まれていません。