法大大电子签 Skill（FASC API 5.0）
基于法大大 FASC API 5.0，提供一键式合同创建、发送、签署全流程解决方案。
✨ 核心特性
- 一键发送 - 只需一行代码即可完成文件上传、任务创建、获取签署链接
- 正确签名 - 严格按照官方文档实现 HMAC-SHA256 两步签名算法
- 智能配置 - 支持环境变量、配置文件、代码传入多种配置方式
- 命令行工具 - 提供
fadada CLI 工具，无需编写代码即可发送合同
- 完整功能 - 支持发送、查询、下载全流程
🚀 快速开始
1. 安装
# 安装依赖
pip install requests
2. 配置凭证
方式一：环境变量
export FADADA_APP_ID="your_app_id"
export FADADA_APP_SECRET="your_app_secret"
export FADADA_OPEN_CORP_ID="your_open_corp_id"
方式二：配置文件
# 创建配置文件
mkdir -p ~/.fadada
cat > ~/.fadada/config.json << EOF
{
"app_id": "your_app_id",
"app_secret": "your_app_secret",
"open_corp_id": "your_open_corp_id"
}
EOF
方式三：代码中直接传入
from fadada_esign import FaDaDaClient, Signer
client = FaDaDaClient(
app_id="your_app_id",
app_secret="your_app_secret",
open_corp_id="your_open_corp_id"
)
3. 发送合同（最简单的方式）
from fadada_esign import FaDaDaClient, Signer
# 创建客户端
client = FaDaDaClient(
app_id="your_app_id",
app_secret="your_app_secret",
open_corp_id="your_open_corp_id"
)
# 一键发送合同
result = client.send_to_single_signer(
file_path="/path/to/contract.pdf",
signer_name="张三",
signer_mobile="13800138000",
task_subject="劳动合同签署"
)
print(f"签署链接: {result['sign_url']}")
4. 命令行发送
# 发送给单个签署人
fadada send contract.pdf --signer "张三:13800138000"
# 发送给多个签署人
fadada send contract.pdf --signer "张三:13800138000" --signer "李四:13900139000"
# 指定任务主题
fadada send contract.pdf --signer "张三:13800138000" --subject "销售合同"
📖 API 文档
客户端初始化
from fadada_esign import FaDaDaClient
# 正式环境
client = FaDaDaClient(
app_id="your_app_id",
app_secret="your_app_secret",
open_corp_id="your_open_corp_id"
)
# 沙箱环境
client = FaDaDaClient(
app_id="your_app_id",
app_secret="your_app_secret",
open_corp_id="your_open_corp_id",
sandbox=True
)
一键发送文档
from fadada_esign import FaDaDaClient, Signer
client = FaDaDaClient(...)
# 方式1：发送给单个签署人（最简单）
result = client.send_to_single_signer(
file_path="/path/to/contract.pdf",
signer_name="张三",
signer_mobile="13800138000"
)
# 方式2：发送给多个签署人
signers = [
Signer(name="张三", mobile="13800138000", actor_id="signer1"),
Signer(name="李四", mobile="13900139000", actor_id="signer2")
]
result = client.send_document(
file_path="/path/to/contract.pdf",
signers=signers,
task_subject="多方合同"
)
# 返回结果
print(result)
# {
# "sign_task_id": "1774590564587181726",
# "sign_url": "https://fdd1.cn/dQFiT0SDcw1",
# "task_subject": "多方合同",
# "file_path": "/path/to/contract.pdf",
# "signers": [...]
# }
分步操作
from fadada_esign import FaDaDaClient, Signer
client = FaDaDaClient(...)
# 1. 上传文件
file_id = client.upload_file("/path/to/contract.pdf")
# 2. 创建签署任务
signer = Signer(name="张三", mobile="13800138000")
sign_task_id = client.create_sign_task(
task_subject="合同签署",
file_id=file_id,
signers=[signer]
)
# 3. 获取签署链接
sign_url = client.get_sign_url(sign_task_id)
查询签署状态
# 查询任务详情
detail = client.query_task_detail(sign_task_id)
print(detail)
# {
# "signTaskId": "xxx",
# "signTaskSubject": "合同签署",
# "signTaskStatus": "sign_progress",
# "actors": [...]
# }
下载已签署文档
# 获取下载链接
download_url = client.get_download_url(sign_task_id)
print(f"下载链接: {download_url}")
# 或者直接下载
import requests
response = requests.get(download_url)
with open("signed_contract.pdf", "wb") as f:
f.write(response.content)
🔧 命令行工具
配置管理
# 交互式配置
fadada config setup
# 查看当前配置
fadada config show
发送合同
# 基础用法
fadada send contract.pdf --signer "张三:13800138000"
# 多个签署人
fadada send contract.pdf \
--signer "张三:13800138000" \
--signer "李四:13900139000" \
--subject "合作协议"
# 保存结果到文件
fadada send contract.pdf \
--signer "张三:13800138000" \
--output result.json
查询状态
fadada status <task_id>
下载合同
fadada download <task_id> --output ./signed_contract.pdf
📋 签署任务状态
| 状态 | 说明 |
|---|
| draft | 创建中 |
| submitting | 提交中 |
| fill_wait | 等待填写 |
| filled | 填写完成 |
| sign_progress | 签署进行中 |
| finished | 已完成 |
| cancelled | 已撤销 |
| expired | 已过期 |
📝 签署人配置
from fadada_esign import Signer
# 基础配置
signer = Signer(
name="张三",
mobile="13800138000"
)
# 完整配置
signer = Signer(
name="张三",
mobile="13800138000",
actor_id="signer1",
actor_type="person", # person 或 corp
permissions=["sign"],
notification={
"sendNotification": True,
"notifyWay": "mobile",
"notifyAddress": "13800138000"
},
id_number="11010119900101xxxx", # 可选
email="zhangsan@example.com" # 可选
)
⚙️ 配置优先级
配置加载优先级（从高到低）：
- 代码中显式传入的参数
- 环境变量（
FADADA_APP_ID, FADADA_APP_SECRET, FADADA_OPEN_CORP_ID）
- 本地配置文件（
.fadada.json 或 fadada_config.json）
- 全局配置文件（
~/.fadada/config.json）
🔐 安全注意事项
- App Secret 不要硬编码在代码中，建议使用环境变量或配置文件
- 配置文件权限建议设置为
600（仅所有者可读写）
- 生产环境建议使用正式环境（sandbox=False）
🐛 错误处理
from fadada_esign import FaDaDaClient, Signer
from fadada_esign.exceptions import FaDaDaError, FaDaDaAuthError, FaDaDaAPIError
client = FaDaDaClient(...)
try:
result = client.send_to_single_signer(...)
except FaDaDaAuthError as e:
print(f"认证失败: {e}")
except FaDaDaAPIError as e:
print(f"API 错误: {e.code} - {e}")
except FaDaDaError as e:
print(f"操作失败: {e}")
📚 完整示例
#!/usr/bin/env python3
"""
法大大电子签 - 完整示例
"""
from fadada_esign import FaDaDaClient, Signer
def main():
# 初始化客户端
client = FaDaDaClient(
app_id="your_app_id",
app_secret="your_app_secret",
open_corp_id="your_open_corp_id",
sandbox=False # 生产环境
)
# 创建签署人
signers = [
Signer(name="张三", mobile="13800138000", actor_id="signer1"),
Signer(name="李四", mobile="13900139000", actor_id="signer2")
]
# 发送合同
result = client.send_document(
file_path="./劳动合同.pdf",
signers=signers,
task_subject="2024年劳动合同"
)
print("=" * 50)
print("✅ 合同发送成功！")
print("=" * 50)
print(f"任务 ID: {result['sign_task_id']}")
print(f"签署链接: {result['sign_url']}")
print()
# 保存任务ID供后续查询
task_id = result['sign_task_id']
# 稍后查询状态
# detail = client.query_task_detail(task_id)
# print(f"当前状态: {detail['signTaskStatus']}")
# 签署完成后下载
# download_url = client.get_download_url(task_id)
# print(f"下载链接: {download_url}")
if __name__ == "__main__":
main()
📄 文件结构
fadada_esign/
├── __init__.py # 包入口
├── client.py # 核心客户端
├── signer.py # 签署人模型
├── config.py # 配置管理
├── cli.py # 命令行工具
└── exceptions.py # 异常类
🔗 相关链接
📄 License
MIT License
