waafir-esign 参考
waafir-esign 服务器向已连接的 AI 客户端提供 Waafir 自有的电子签名服务:基于您组织中的文件创建信封,让其签署人签署(或拒绝),跟踪状态,并下载已签署的 PDF。签名为 eIDAS AES(PAdES),由 Waafir 自己的签名引擎生成;每个签名都会在防篡改的审计记录中捕获签署人的同意信息(IP 地址、用户代理、时间戳),已签署的 PDF 会作为源文件的最新版本存储。
连接:https://app.waafir.io/api/mcp/waafir,或领域服务器 https://app.waafir.io/api/mcp/waafir-esign,请参阅设置。两者上的工具名称相同。读取工具需要 read 权限范围,可以是通过登录建立的连接,也可以是 PAT;创建、发送、拒绝、修改签署人和作废需要 write 权限范围。签署需要 write 以及签署文档的权限:对于连接,在授权同意页面上批准;对于令牌,在创建时开启(请参阅允许令牌签署文档);没有该权限时,esign_sign 会从工具列表中隐藏,被调用时也会被拒绝。限定于特定数据室的连接或令牌只能处理基于这些数据室中文件的信封,这与数据室工具所执行的边界相同。
每月信封配额
电子签名按信封计量:一个文档 / 签署作业只计一次,无论它有多少签署人。此 MCP 服务器和应用内签署界面都从同一个共享的每月额度池中扣除:
- 访问需要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 每个活跃席位 50 个(按日历月计)。
- 每购买一个单位的 E-Signatures 附加功能,就会在套餐额度之上每月增加 100 个信封;在任何套餐上,单位都可以叠加。
- 配额是硬性上限:当您在达到上限时发送信封,发送会以线路代码
QUOTA_EXCEEDED被拒绝,提示您购买更多单位或升级套餐;系统永远不会自动按信封收费。消息文本中还会提到一个内部标记ESIGN_QUOTA_EXCEEDED;那只是说明文字,因此请根据error.code(即QUOTA_EXCEEDED)进行分支。触及上限的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。如果它原本是可选参数,则会像其他任何无法识别的键一样被静默丢弃,请参阅下面的两种失败模式。请将您的调用更新为本页上的拼写。
拼错的键会以两种方式之一失败,其中一种是静默的。 无法识别的参数会被丢弃,而不会被拒绝,因此接下来会发生什么只取决于您本想使用的键是否为必需:
-
必需键 → 调用被拒绝。该参数只是缺失了。这是显式的、安全的情况,涵盖
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。参数会在工具运行之前根据工具发布的 schema 进行校验,因此缺少必需键(或类型错误的键)会以服务器自身生成的错误结果返回:响应被标记为错误,其文本会指出有问题的参数,但没有工具运行,因此不会填充第 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_id | string (UUID) | 是 | 要签署的文件。必须属于您的组织。 |
signatories | array | 是 | 1–50 个 { "email": string, "name"?: string }。任何电子邮件都会被接受:签署人不需要是 Waafir 用户;外部地址会收到访客签署链接。 |
transaction_id | string (UUID) | 否 | 已弃用并被忽略。 仍被接受是为了让现有集成继续工作;请停止发送它。 |
send | boolean | 否 | 为 true 时,立即开放信封供签署,分两步进行(见下文)。需要开启了 发送给组织外的人员 的令牌。 |
confirm_token | string | 否 | 仅与 send: true 一起使用:来自预览调用的令牌。 |
confirm_send | boolean | 否 | 已弃用并被忽略:send: true 现在使用 confirm_token。 |
signing_mode | "parallel" | "sequential" | 否 | 签署顺序。"parallel" 是默认值:签署人可以按任意顺序签署,发送时会同时向所有人发送电子邮件。"sequential" 只向第一位发送电子邮件,并在之前的每一位都签署后才放行下一位签署人;不按顺序签署会以 CONFLICT 被拒绝。省略(或拼错为 signingMode)即表示 "parallel"。 |
field_layout | array | 否 | 字段位置布局覆盖;省略则使用默认布局。 |
observers | array | 否 | 最多 20 位观察者(抄送),格式为 { "email": string, "name"?: string }。观察者会通过电子邮件收到签名请求和每次提醒的副本,以及一个用于跟踪其状态的只读链接。观察者从不签署,也不会收到已签署的副本。 |
send: true 分两步进行,因为发送一旦成功,就会向列出的每个地址发出真实的、具有法律约束力的签名请求电子邮件。第一次调用不会创建或发送任何内容:它返回一个预览(签署人、观察者数量和您的配额)以及一个 confirm_token。使用相同的参数和该令牌再次调用,即可创建并发送。该令牌只能使用一次,并在几分钟后过期。没有此授权时,send: true 会以 FORBIDDEN(GRANT_REQUIRED)被拒绝;请在不带 send 的情况下创建信封,然后改为在 Waafir 中发送。
当 esign_revise_signers 会向某人发送电子邮件时(即已发送信封上的新签署人或观察者),它也采用同样的两步流程,并需要同样的授权。
返回该信封。其字段恰好是 id、file_id、status、signing_mode、created_by、signed_output_name、signed_output_version_count、field_layout、packet_page_count 和 expires_at:结果是一个手工映射的允许列表,因此线路上不会有其他任何内容。时间戳为 ISO-8601 字符串。
草稿信封必须先发送,才能有人签署。发送会消耗您每月配额中的一个信封:达到上限时,send 会返回 QUOTA_EXCEEDED,信封则保持为草稿,您可以稍后发送。误发的信封可以使用 esign_void_envelope 撤回。
仍在检查中的文件。 如果该文件是 Waafir 尚未检查完毕的新上传文件或新版本,调用会返回 UNAVAILABLE,附带 error.reason: "ACTIVATION_PENDING" 和消息 This file is still being checked. Try again shortly. 不会创建任何内容;请稍等片刻后再次调用。
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(读取)
获取一个信封及其签署人和各自的状态(pending / signed / declined)。输入:envelope_id。除上述创建工具的字段外,该信封还带有 created_at、updated_at 和 signatories(每项为 { id, email, name, status, signed_at })。
esign_sign(写入)
签署您自己的待签署位置,即电子邮件与令牌所有者相匹配的位置。签署不会消耗配额(信封在发送时已经计量)。需要开启了 签署文件 的令牌。
签署需要两次调用,以便您的助手在签署任何内容之前先向您展示即将签署的内容:
- 预览。不带
confirm_token调用。不会签署任何内容。结果为dry_run: true,并包含信封、按顺序排列的documents、一个涵盖所有文档的document_hash、signer、您提供的fields、同意声明、一个confirm_token及其expires_at。 - 确认。待本人同意后,使用完全相同的参数加上该
confirm_token再次调用。此调用会执行签署。
confirm_token 只能使用一次,仅适用于此令牌和这些参数,并在五分钟后过期。如果在此期间信封、其文档、您在签署顺序中的位置或您的字段发生了变化,确认会被拒绝,您需要重新预览。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
envelope_id | string (UUID) | 是 | 要签署的信封。 |
consent_affirmed | boolean | 是 | 必须字面上为 true,即对同意声明的明确确认。没有默认值;省略它或传入 false 都会使调用在协议边界处失败。 |
fields | object | 否 | 以字段标签为键的填写值;省略时,姓名和日期使用默认值。 |
confirm_token | string | 否 | 省略则进行预览。传入预览返回的令牌即可签署。 |
确认调用返回 { envelope },即与 esign_create_envelope 返回的相同允许列表形态的信封。
您可能会看到的错误:如果您不是该信封的待签署人,则为 FORBIDDEN;如果信封未开放签署,或者在 sequential 信封上之前的签署人尚未签署,则为 CONFLICT。这些是载荷中的 error.code 值,而不是 HTTP 状态,请参阅设置。
两步确认还会增加以下拒绝,每种拒绝都会在消息中带有其 (code: …):
error.code | code: | 处理方法 |
|---|---|---|
FORBIDDEN | GRANT_REQUIRED | 该令牌无法签署。请创建一个开启了 签署文件 的新令牌。 |
INVALID_ARGUMENT | CONFIRM_TOKEN_MALFORMED | 不带 confirm_token 再次调用以获取一个。 |
CONFLICT | CONFIRM_TOKEN_INVALID | 该令牌已过期、已被使用,或属于另一个令牌。请重新预览。 |
CONFLICT | CONFIRM_ARGS_MISMATCH | 参数与预览时的不同。请重新预览。 |
CONFLICT | CONFIRM_STATE_CHANGED | 自预览以来信封已发生变化。请重新预览并展示给本人。 |
CONFLICT | DOCUMENT_NOT_PINNED | 该信封在文档固定功能推出之前发送。请通过签署邮件在 Waafir 中签署。 |
UNAVAILABLE | CONFIRM_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(写入,破坏性)
修正要求签署的人员,而无需作废信封并从配额中再花费一个信封:例如电子邮件输错、漏掉了交易对方、签署顺序错误。信封保留其 id、审计记录和配额单位。不消耗配额。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
envelope_id | string (UUID) | 是 | 要修改的信封。 |
signatories | array | 是 | 信封最终应有的完整签署人列表,按签署顺序排列:1–50 个 { "email": string, "name"?: string }。它会替换当前列表。 |
signing_mode | "parallel" | "sequential" | 否 | 更改签署顺序。省略表示保留当前模式;它不会重置为 "parallel"。 |
observers | array | 否 | 完整的观察者(抄送)列表,最多 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 }。信封必须至少有一个已记录的签名;已签署的 PDF 也会作为源文件的最新版本在产品中提供。需要开启了 读取文档内容 的令牌;没有它时,调用会以 GRANT_REQUIRED 被拒绝。
esign_quota_status(读取)
无输入。返回当前日历月的 { quota, used, remaining }:信封配额总数(套餐额度 + 购买的单位)、已发送的信封数,以及距上限的余量。
esign_remind(写入)
输入 envelope_id。再次向正在等待签署的信封的每位待签署人发送电子邮件,并向每位观察者发送副本,每个信封每小时最多一次。需要 发送给组织外的人员,并分两步进行:第一次调用不发送任何内容,返回将收到电子邮件的人员(观察者按姓名列出)以及一个 confirm_token;然后带上它再次调用。如果在此期间添加了观察者,确认会失败。仅限交易团队成员。
esign_resend_signatory(写入)
输入 envelope_id、signatory_id。清除被退信或被抑制的地址,并再次向该签署人发送电子邮件。授权和两步流程与 esign_remind 相同。
esign_send_draft(写入)
输入 envelope_id。发送已保存的草稿:每位签署人都会通过电子邮件收到具有法律约束力的签名请求,每位观察者收到一份副本,并使用一个信封配额。授权和两步流程相同;预览会列出签署人、观察者和您的配额,最终发送的正是您预览过的签署人名单和观察者。结果会列出任何未发送电子邮件的 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 和欧盟 eIDAS,对 NDA 和合同有效。签署人的同意信息(IP、用户代理、时间戳)会在签署时记录在 Waafir 只可追加、哈希链式的审计记录中。通过此 MCP 服务器创建或发送的信封会在该记录中被记为令牌发起的操作,因此由智能体发起的发送始终可以与由人在应用中执行的发送区分开来。合格电子签名(QES)不包含在本版本中。