DocuSign API实战：HR系统入职合同自动发起（eSignature v2.1）

原创于 2026-08-19 14:03:15 发布 · 30 阅读

本内容遵循CC 4.0 BY-SA版权协议

员工入职时，HR 系统（北森 / Moka / 自研）一旦完成入职登记，就自动触发 DocuSign 发起劳动合同、保密协议，员工在手机上签完，签署状态再回写 HR 系统——这条链路是「入转调离」电子签自动化的第一步。本文用 Python 演示如何用 eSignature REST API v2.1 把这件事跑通。

注：DocuSign 于 2026 年 6 月在美国推出 IAM for HR 早期访问，强调员工协议集中管理并与 HCM 同步；本文聚焦最通用的 eSignature API 集成路径，适用于已开通 eSignature 的账号。

一、准备：JWT 鉴权拿 access token

服务端集成推荐用 JWT（不依赖人工登录），用企业级 Integration Key + RSA 私钥换取 token。

import requests, time, jwt, json
from datetime import datetime, timezone

BASE = "https://demo.docusign.net/restapi"  # 生产换成 account.docusign.net
ACCOUNT_ID = "你的ACCOUNT_ID"
INTEGRATION_KEY = "你的IK"
USER_ID = "你的USER_ID（impersonated user）"
PRIVATE_KEY = open("private_key.pem", "r").read()

def get_token():
    now = int(time.time())
    payload = {
        "iss": INTEGRATION_KEY,
        "sub": USER_ID,
        "aud": BASE.replace("https://", "").replace("http://", ""),
        "iat": now,
        "exp": now + 3600,
        "scope": "signature",
    }
    token = jwt.encode(payload, PRIVATE_KEY, algorithm="RS256")
    r = requests.post(
        "https://account.docusign.com/oauth/token",
        data={"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
              "assertion": token},
    )
    return r.json()["access_token"]

二、核心：用模板批量发起入职合同

先在 DocuSign 后台把「劳动合同」「保密协议」做成 Template，记下 template_id；模板里定义好角色（如 employee）和占位字段。

def send_onboarding(envelope_def, token):
    headers = {"Authorization": f"Bearer {token}",
               "Content-Type": "application/json"}
    r = requests.post(
        f"{BASE}/v2.1/accounts/{ACCOUNT_ID}/envelopes",
        headers=headers, json=envelope_def,
    )
    return r.json()  # 返回 envelopeId

def build_envelope(name, email, template_id, role="employee"):
    return {
        "templateId": template_id,
        "templateRoles": [{
            "roleName": role,
            "name": name,
            "email": email,
            "clientUserId": "hr_" + email,  # 嵌入式签署时可定位
            # 动态字段：把 HR 系统里的真实数据填进模板 tab
            "tabs": {
                "textTabs": [
                    {"tabLabel": "empName", "value": name},
                    {"tabLabel": "startDate", "value": "2026-08-19"},
                ]
            },
        }],
        "status": "sent",  # sent=立即发；created=先存草稿
    }

三、批量：从 HR 系统拉新员工，循环发起

真实场景里，新员工来自 HR 系统的数据库或每日导出。下面用 CSV 示意：

def batch_onboarding(csv_path, template_id, token):
    results = []
    with open(csv_path, encoding="utf-8") as f:
        for row in csv.DictReader(f):
            env = build_envelope(row["name"], row["email"], template_id)
            resp = send_onboarding(env, token)
            results.append({"name": row["name"],
                            "envelopeId": resp.get("envelopeId")})
    return results

# 调用示例（token 建议缓存，快过期再刷新）
token = get_token()
batch_onboarding("new_hires.csv", "你的TEMPLATE_ID", token)

四、闭环：用 Connect / Webhook 回收签署状态

员工签完，DocuSign 通过 Connect（Webhook）推送事件，把状态回写 HR 系统，形成「发起→签署→回写」完整链路。

from flask import Flask, request
app = Flask(__name__)

@app.route("/docusign/webhook", methods=["POST"])
def webhook():
    # 生产环境务必校验 DocuSign 的 HMAC 签名，防止伪造回调
    body = request.get_json()
    for env in body.get("data", {}).get("envelopeSummary", []):
        envelope_id = env.get("envelopeId")
        status = env.get("status")  # completed / declined ...
        # TODO: 按 envelope_id 回写 HR 系统的签署状态
    return "ok", 200