法大大电子签 - 发起合同签署#

基于法大大 FASC API 5.0，提供一键式合同发起签署能力，将合同文件发送给签署方进行电子签署。

概述#

fadada-document-sign 提供合同签署的完整生命周期能力：

• 发起合同签署 - 上传合同文件，系统自动识别签署方，用户确认后发起签署
• 查询签署模板 - 查询签署模板列表和详情，基于模板快速发起
• 查询已有流程 - 查询当前账号下的签署任务列表，支持状态筛选和关键词搜索
• 撤回签署任务 - 撤回尚未完成的签署任务（待提交、签署中状态）
• 下载已签合同 - 获取并下载已完成签署的合同文件

职责边界#

属于本 skill不属于本 skill发起新的合同签署流程起草/生成合同正文或 PDF将文件发给签署方签署审查合同条款、识别风险上传合同后发起签署审批通过/驳回查询签署模板列表和详情作废已完成合同查询已有签署流程-撤回未完成签署任务-下载已签署合同-

执行入口约束#

• 发起签署：用户说"发合同"、"发个合同"、"把合同发出去"等时，判定为发起签署意图
• 查询已有流程：用户说"查合同"、"查流程"、"查任务"、"看看有哪些合同"、"我的签署任务"等时，判定为查询已有流程意图
• 撤回任务：用户说"撤回合同"、"撤回签署"、"撤销任务"、"取消合同"等时，判定为撤回任务意图
• 下载合同：用户说"下载合同"、"下载已签合同"、"下载签署文件"、"保存合同"等时，判定为下载合同意图
• 进入本 skill 后，禁止只给解释性文本、方案建议或下一步提示；必须推进到对应工作流
• 选择工作流后，必须严格按步骤推进；禁止跳过入口步骤直接调用中间脚本

工作流推进规则#

工作流 1：上传合同后直接发起签署#

进入条件：用户说"发合同"且当前会话有上传文件

1. 获取合同文件 → 2. 上传文件到法大大 → 3. 收集签署方信息 → 4. 发起签署 → 5. 发布结果卡片

工作流 2：查询签署模板后发起#

进入条件：用户说"用模板发起"、"查一下模板"等

1. 查询模板列表 → 2. 查询模板详情 → 3. 收集签署方信息 → 4. 发起签署 → 5. 发布结果卡片

工作流 3：查询已有签署流程#

进入条件：用户说"查合同"、"查流程"、"查任务"等

1. 查询流程列表 - 调用脚本查询签署任务列表
2. 展示列表卡片 - 显示任务列表，包含任务名称、状态、创建时间等
3. 用户选择任务 - 用户可选择某个任务查看详情或执行其他操作
4. 执行后续操作 - 根据用户选择执行查看详情/撤回/下载等

工作流 4：撤回签署任务#

进入条件：用户说"撤回合同"、"撤销任务"等

1. 获取任务ID - 用户需提供或从列表选择要撤回的任务
2. 验证撤回条件 - 检查任务状态是否为可撤回状态（待提交/签署中）
3. 执行撤回 - 调用撤回接口
4. 发布结果卡片 - 显示撤回结果

工作流 5：下载已签署合同#

进入条件：用户说"下载合同"、"保存合同"等

1. 获取任务ID - 用户需提供或从列表选择要下载的任务
2. 验证下载条件 - 检查任务状态是否为已完成
3. 获取下载链接 - 调用下载接口获取下载地址
4. 下载文件 - 可选：指定保存路径自动下载
5. 发布结果卡片 - 显示下载结果（链接或本地路径）

禁止事项#

• 禁止进入本 skill 后仅回复"请上传文件"、"请选择模板"等普通文本，而不发布对应卡片
• 禁止未执行工作流 1 的步骤 1 就直接调用发起签署脚本
• 禁止未执行工作流 2 的步骤 1 和步骤 2 就直接调用发起签署脚本
• 禁止在需要用户选择、上传、填写、确认时，用普通文本替代卡片交互
• 禁止在步骤 3 未收到用户提交结果前调用发起签署脚本
• 禁止发起失败或未拿到 taskId 时继续调用查询结果脚本
• 禁止撤回非可撤回状态的任务（已完成/已作废/已过期）
• 禁止下载非已完成状态的任务

典型工作流#

工作流 1：上传合同后直接发起签署#

适用场景: 用户上传合同文件，说"发合同给对方签" 执行流程:

1. 获取合同文件 - 先获取当前会话中用户上传的文件列表

   • 无文件：发布上传卡片， 等待用户上传；用户上传后，重新执行步骤 1
   • 仅 1 个文件：直接使用该文件进入步骤 2，不再额外弹选择卡片
   • 多个文件：发布文件选择卡片， 等待用户选择；用户选择后，使用其所选文件进入步骤 2

2. 上传文件到法大大 - 调用 scripts/upload_file.py 将合同文件上传到法大大平台

   • 支持 PDF 格式文件
   • 脚本返回 fileId，用于创建签署任务

3. 收集签署方信息 - 发布签署方信息填写卡片

   • 签署方类型：个人 / 企业
   • 签署方信息：姓名/企业名称、手机号/邮箱
   • 企业签署时还需填写经办人信息
   • 等待用户填写并提交

4. 发起签署 - 用户提交信息后，调用 scripts/initiate_sign.py 发起签署

   • 必须传入步骤 2 返回的 fileId
   • 必须传入用户填写的签署方信息
   • 脚本返回 taskId（签署任务ID）和 signUrl（签署链接）

5. 发布结果卡片 - 展示签署发起结果

   • 成功：显示 taskId、signUrl、签署方信息
   • 失败：显示错误原因

关键要点:

• 步骤 1、3、5 必须发布卡片
• 用户提交信息补全表单后直接发起，无需额外确认
• 禁止跳过步骤

工作流 2：查询签署模板后发起#

适用场景: 用户说"查一下有哪些模板"，然后选择一个发起 执行流程:

1. 查询模板列表 - 调用 scripts/list_templates.py 查询签署模板

   • 发布模板列表卡片， 等待用户选择

2. 查询模板详情 - 用户选择模板后，调用 scripts/get_template_detail.py

   • 提取模板中的文件作为签署文件（无需用户再上传）
   • 提取模板中的签署方角色信息

3. 收集签署方信息 - 发布签署方信息填写卡片

   • 预填充模板中的签署方角色
   • 等待用户填写并提交

4. 发起签署 - 用户提交后，调用 scripts/initiate_sign.py 发起签署

   • 必须传入 --template-id 参数
   • 签署方必须包含模板中的 participantId

5. 发布结果卡片 - 展示签署发起结果

关键要点:

• 与普通发起的核心区别：文件来自模板，签署方角色固定
• 禁止跳过步骤

技术实现#

脚本清单#

脚本路径用途关键参数scripts/upload_file.py上传合同文件到法大大平台--file-path: 文件路径, --file-name: 文件名scripts/initiate_sign.py调用法大大API发起签署--task-name: 任务名称, --file-ids: 文件ID列表, --signers: 签署方JSONscripts/list_templates.py查询签署模板列表--template-name: 模板名称(可选)scripts/get_template_detail.py查询模板详情--template-id: 模板IDscripts/list_sign_tasks.py查询已有签署流程列表--status: 状态筛选, --keyword: 关键词, --page: 页码scripts/query_sign_status.py查询签署任务详情/状态--task-id: 任务IDscripts/cancel_sign_task.py撤回签署任务--task-id: 任务ID, --reason: 撤回原因scripts/download_signed_contract.py下载已签署合同--task-id: 任务ID, --save-path: 保存路径scripts/utils.py公共工具函数-

脚本使用说明#

bash

# ==================== 发起签署 ====================
# 上传文件
python scripts/upload_file.py --file-path "/path/to/contract.pdf" --file-name "合同.pdf"

# 发起签署
python scripts/initiate_sign.py \
  --task-name "劳动合同签署" \
  --file-ids '["file_id_from_upload"]' \
  --signers '[{"name":"张三","phone":"13800138000","actorType":"person"}]'

# 基于模板发起
python scripts/initiate_sign.py \
  --task-name "劳动合同签署" \
  --template-id "template_id" \
  --signers '[{"name":"张三","phone":"13800138000","actorType":"person","participantId":"xxx"}]'

# ==================== 查询已有流程 ====================
# 查询所有签署任务
python scripts/list_sign_tasks.py

# 按状态筛选（signing=签署中, finished=已完成, cancelled=已撤销）
python scripts/list_sign_tasks.py --status signing

# 关键词搜索
python scripts/list_sign_tasks.py --keyword "劳动合同"

# 分页查询
python scripts/list_sign_tasks.py --page 1 --page-size 20

# 查询单个任务详情
python scripts/query_sign_status.py --task-id "task_id_here"

# ==================== 撤回任务 ====================
# 撤回签署任务
python scripts/cancel_sign_task.py --task-id "task_id_here"

# 撤回并填写原因
python scripts/cancel_sign_task.py --task-id "task_id_here" --reason "合同内容有误"

# ==================== 下载合同 ====================
# 获取下载链接
python scripts/download_signed_contract.py --task-id "task_id_here"

# 下载并保存到本地
python scripts/download_signed_contract.py \
  --task-id "task_id_here" \
  --save-path "./signed_contract.pdf"

签署方传参说明#

--signers 参数为 JSON 数组，每个元素表示一个签署方。

个人签署方#

字段必填说明name是个人姓名phone条件手机号， phone 和 email 至少传一个email条件邮箱， phone 和 email 至少传一个actorType是固定传 person

示例：

json

[
  {
    "name": "张三",
    "phone": "13800138000",
    "actorType": "person"
  }
]

企业签署方#

字段必填说明name是企业全称contactName是经办人姓名phone条件经办人手机号， phone 和 email 至少传一个email条件经办人邮箱， phone 和 email 至少传一个actorType是固定传 corp``openCorpId否企业ID（已授权企业）

企业示例：

json

[
  {
    "name": "杭州未来科技有限公司",
    "contactName": "李经理",
    "phone": "13800138000",
    "actorType": "corp"
  }
]

混合场景示例（个人 + 企业）#

bash

python scripts/initiate_sign.py \
  --task-name "采购合同签署" \
  --file-ids '["file_id"]' \
  --signers '[{"name":"杭州未来科技有限公司","contactName":"李经理","phone":"13800138000","actorType":"corp"},{"name":"王五","phone":"13900139000","actorType":"person"}]'

错误处理#

场景处理方式文件格式不支持提示用户仅支持 PDF 格式，请上传 PDF 文件上传失败展示错误信息，建议重新上传签署方信息不完整停在信息填写步骤，等待用户补全发起签署失败展示错误原因，提供重试选项未配置凭证提示配置法大大 API 凭证任务状态不可撤回提示当前任务状态不支持撤回（如已完成/已作废）任务状态不可下载提示当前任务状态不支持下载（如签署中/未完成）任务不存在提示任务ID无效或无权访问下载失败展示错误信息，建议检查网络后重试

关键注意事项#

1. 静默前置检查 - 凭证配置检查自动完成
2. 状态校验 - 撤回仅支持待提交/签署中状态，下载仅支持已完成状态
3. 必须等待用户提交 - 展示信息填写卡片后，必须等待用户提交表单
4. 禁止跳过卡片渲染 - 所有展示节点必须通过卡片形式展示
5. 签署任务ID保存 - 发起签署后应保存 taskId，供后续查询/撤回/下载使用

法大大API对接说明#

API凭证获取指引#

正式环境上线流程

步骤内容详细说明1个人注册&认证企业管理员完成个人实名认证2企业创建&认证创建企业并完成企业实名认证3创建应用并启用创建应用并提交审核启用4获取凭证****获取 AppID、AppSecret、openCorpId5配置正式环境替换为正式环境信息

详细操作指引： https://dev.fadada.com/api-guide/YYNLQW2Z2W/9QMQ2MU4FGK3AOXA

获取 AppID 和 AppSecret

获取步骤：

步骤操作1进入 企业设置 → 集成管理 → 应用集成，选择已启用的应用2点击 AppSecret 的【查看】按钮3获取短信验证码并填写验证4验证通过后，点击【复制图标】复制 AppID 和 AppSecret

凭证配置

环境变量说明来源FADADA_APP_ID应用ID（AppID）应用详情页FADADA_APP_SECRET应用密钥（AppSecret）应用详情页（需验证）FADADA_OPEN_CORP_ID企业ID（openCorpId）应用详情页 / 自动获取FADADA_ENV环境 (production/uat)默认 production

⚠️ 注意：openCorpId 可不配置，系统会自动通过 /app/get-openId-list 接口获取应用归属企业的 openCorpId

API基础信息#

• API版本: FASC API 5.0
• 正式环境: https://api.fadada.com/api/v5
• UAT测试环境: https://uat-api.fadada.com/api/v5

环境配置#

设置 FADADA_ENV 环境变量：

• production - 正式环境（默认）
• uat - UAT测试环境

OpenCorpId 自动获取#

重要特性：如果未配置 FADADA_OPEN_CORP_ID，系统会自动通过 /app/get-openId-list 接口获取应用归属企业的 openCorpId。

配置优先级：

1. 显式传入 open_corp_id 参数
2. 环境变量 FADADA_OPEN_CORP_ID
3. 自动获取（调用 API 获取应用归属企业信息）

适用场景：

• 用户未提供 openCorpId 时，自动获取应用归属企业
• 企业管理员不确定企业 ID 时，自动解析
• 多企业切换时，验证归属企业信息

认证方式#

使用 HMAC-SHA256 签名算法进行接口认证：

1. 获取 AccessToken（凭证管理接口）
2. 组装请求参数并计算签名
3. 携带签名和 Token 调用业务接口

核心接口#

接口地址说明状态获取服务访问凭证/service/get-access-token获取访问令牌✅ 可用上传本地文件/file/get-upload-url获取上传URL✅ 可用文件处理/file/process转换为PDF✅ 可用创建签署任务/sign-task/create发起签署✅ 可用添加签署参与方/sign-task/actor/add添加签署方✅ 可用获取签署链接/sign-task/actor/get-url获取签署URL✅ 可用查询签署任务详情/sign-task/app/get-detail查询单个任务状态✅ 可用查询签署模板列表/sign-template/get-list模板列表✅ 可用查询签署模板详情/sign-template/get-detail模板详情✅ 可用查询签署任务列表/sign-task/owner/get-list批量查询任务✅ 可用撤回签署任务/sign-task/cancel撤回任务✅ 可用获取合同下载链接/sign-task/owner/get-download-url下载合同✅ 可用查询授权用户列表/app/get-openId-list获取归属企业openCorpId✅ 可用

API 已知限制#

以下接口已验证可用：

• 批量查询签署任务列表（ /sign-task/owner/get-list）
• 撤回签署任务（ /sign-task/cancel）
• 获取合同下载链接（ /sign-task/owner/get-download-url）

如遇 404 错误，请确认账户是否具备相应权限。

签署任务状态说明#

状态说明draft草稿waiting待提交signing签署中finished已完成cancelled已撤销abolished已作废expired已过期

API返回码说明#

返回码说明100000请求成功100001系统错误100002访问凭证失效200001参数错误200002签名验证失败300001业务处理失败400001权限不足