DocuSign Agreement Manager API 实战：把合同签署状态接回你自己的业务系统

把协议变成可编程资产，是最近企业签约领域一个明显的趋势。2026 年 7 月 1 日，DocuSign 在 Momentum London 2026 上发布了 Iris AI 引擎、Agent Studio，以及面向开发者开放的 MCP Server（Global Open Beta）和 Agreement Manager API（GA）。公开资料显示，Deloitte 借助其智能协议管理能力，实现了近 30% 的 ROI 提升，目前服务超过 4 万家企业客户。这些能力可以接入 Claude、Gemini、ChatGPT、Copilot 等模型。

不过今天我们不聊模型怎么帮你起草或审查协议，而是聊一个更落地的问题：当一份合同在 DocuSign 里被签署、拒签或过期之后，你怎么让这个状态实时回到你自己的 CRM 或订单系统？

最直接的思路是轮询：写个定时任务，逐个去查每个 envelope 的状态。问题是，业务量一大，轮询会很快吃掉 API 配额，而且状态更新天然有延迟。更稳妥的做法是 webhook：让 DocuSign 在事件发生的那一刻，主动把消息推送到你自己的服务。这省配额，也更及时。

下面给出一套可运行的思路骨架，域名与密钥均用 example.com 占位，落地时替换即可。

一、Flask 接收端骨架

核心做两件事：其一，校验签名，确认请求确实来自 DocuSign；其二，解析 envelope summary，把状态翻译成本地字段再回写业务系统。

from flask import Flask, request, abort
import hmac, hashlib, json

app = Flask(__name__)
WEBHOOK_SECRET = "replace_with_your_token"  # 你的 Connect webhook 密钥
BIZ_API = "https://api.example.com/v1/contracts/status"  # 自家业务系统占位域名

@app.route("/docusign/webhook", methods=["POST"])
def docusign_webhook():
    body = request.get_data()
    # 其一：校验签名，确认请求确实来自 DocuSign
    signature = request.headers.get("X-DocuSign-Signature-1", "")
    expected = hmac.new(WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401)
    # 其二：解析 envelope summary
    payload = json.loads(body)
    for msg in payload.get("events", []):
        envelope_id = msg.get("envelopeId")
        status = msg.get("status")  # sent / delivered / signed / completed / declined / voided
        user_a = msg.get("userName", "用户A")
        update_contract_status(envelope_id, status, user_a)
    return ("ok", 200)

def update_contract_status(envelope_id, status, operator):
    # 回调后更新业务系统里的"合同状态"字段
    mapping = {
        "signed": "已签署",
        "completed": "已完成",
        "declined": "已拒签",
        "voided": "已作废",
    }
    payload = {"envelope_id": envelope_id,
               "contract_status": mapping.get(status, status),
               "operator": operator}
    # 实际项目里在这里调用自家 CRM / 订单系统接口
    print("PUSH to", BIZ_API, payload)

if __name__ == "__main__":
    app.run(port=8000)

二、订阅哪些事件

在 DocuSign Connect 里配置订阅，告诉它你想收到哪些事件。关键是订阅 signed、completed、declined，这几个状态直接对应你业务系统里的合同生命周期。

{
  "webhookUrl": "https://api.example.com/docusign/webhook",
  "auth": { "type": "hmac", "secret": "replace_with_your_token" },
  "subscriptions": [
    { "event": "envelope-signed", "label": "签署方A 完成签署" },
    { "event": "envelope-completed", "label": "全部签署完成" },
    { "event": "envelope-declined", "label": "签署方B 拒签" },
    { "event": "envelope-voided", "label": "协议作废" }
  ]
}

三、回调后如何更新业务系统

收到 webhook 后，不要只把原始状态存下来。建议做一层映射：把 DocuSign 的英文状态翻译成你业务系统里统一的"合同状态"字段（已签署 / 已完成 / 已拒签 / 已作废），再触发后续动作。

举个例子，订单系统里有一笔待签约订单，关联了某个 envelopeId。当 webhook 推送 completed，就把该订单的"合同状态"置为"已完成"，并解锁发货或开通权限；若推送 declined，则置为"已拒签"，进入人工跟进流程。这样业务侧无需关心 DocuSign 内部状态机，只看自己的字段即可。

如果一份协议涉及多个签署方，注意 signed 和 completed 的差别：signed 通常表示签署方A 完成自己的部分，completed 才表示全部签署方（含签署方B）完成。按业务需要决定监听哪一个，避免状态提前翻转。

关于公司简介

上海华万，专注为企业提供 SaaS 产品的一站式选型与集成服务。国内产品线涵盖腾讯会议、企业微信、腾讯电子签等腾讯生态产品，国际产品线包括 Microsoft Teams、Zoom、DocuSign 等协作与签约工具。从需求诊断、产品选型到系统部署、API 集成与长期运维，华万为企业量身定制落地路径，覆盖售前咨询、方案设计、部署实施与售后服务全流程。目前已服务制造、零售、教育、金融等多个行业的中小企业客户。

官方文档：https://developers.docusign.com （产品页：https://www.docusign.com ）