把电子签接进你自己的系统：签名、接口、回调、MCP，以及三种语言的 SDK。
拿到密钥注册账号，在控制台的“应用密钥”里新建应用，得到 AppKey 和 AppSecret。 下载 SDKSDK 已经处理好签名和回调验签。也可以不用 SDK，按下面的规则自己签名。 跑通一份合同登记企业、上传文件、发起合同、拿签署链接。平台自带沙箱，没有腾讯云密钥也能跑通。 接口地址： https://esign.weig.tech/open/v1 。所有接口用 JSON 收发，成功时返回 {"code":"OK","data":
Java SDK Java 8 及以上，零依赖 [下载 Java SDK](https://esign.weig.tech/downloads/sdk/java.zip) Python SDK Python 3.8 及以上，零依赖 [下载 Python SDK](https://esign.weig.tech/downloads/sdk/python.zip) Go SDK Go 1.18 及以上，只用标准库 [下载 Go SDK](h
企业只需要认证一次。 register_org 可以重复调用：企业已存在时只会刷新信息并重新生成链接。
用 SDK 的话可以跳过这一节。每个请求带四个请求头： X Qs App Key 你的 AppKey X Qs Timestamp 当前时间，Unix 秒。与服务器相差不能超过 300 秒 X Qs Nonce 随机字符串，8 到 64 位，每次请求都不同 X Qs Signature 签名，小写十六进制 签名的算法只有两行： 路径从 /open/v1 开始，带上 ? 后面的查询串，与实际发出的完全一致。没有请求体时，对空字符串取 SH
下面的路径都接在 https://esign.weig.tech/open/v1 后面。 POST /orgs 登记企业并获取认证链接（幂等） GET /orgs 企业列表 GET /orgs/{openId} 企业详情，实时同步认证状态 POST /orgs/{openId}/console url 生成企业认证链接或电子签控制台链接 POST /orgs/{openId}/operators 新增、修改或离职员工 GET /orgs
POST /flows 的请求体： orgOpenId 必填 以哪家企业的名义发起 name 必填 合同名称，签署方能看到 fileId 或 templateId 二选一 文件发起传上传得到的 fileId；模板发起传模板编号 approvers 必填 签署方数组。详见“签署方怎么写” formFields 选填 模板发起时，由发起方填写的合同内容：[{"name":"员工姓名","value":"李四"}]，也可以写成 {"员工姓名"
approvers 是一个数组，每个元素代表一个签署方。签署方不需要提前在平台上创建，发起合同时直接写在请求里即可；只有“本平台登记的企业”需要先完成登记和认证。按对方是谁，有下面五种写法：
个人 对方是自然人，例如员工、客户。 name 填真实姓名，签署时要做实名认证，写昵称或错别字会导致对方无法签署。 mobile 是 11 位大陆手机号，不带 +86。 还可以传 idCardNumber（身份证号），进一步限定签署人的身份。
发起企业自己 合同要盖本企业的章，例如劳动合同里的甲方。 orgOpenId 是发起企业的 OpenId，openId 是由谁来经办盖章，填这家企业里一位已实名员工的 OpenId，最简单的是企业超管（企业详情里的 adminOpenId）。 不传 openId 时合同处于“待领取”状态，由企业里有权限的员工自己领取后签署。 传了 openId 就不用再传 name 和 mobile，以这位员工实名的信息为准。
本平台登记的另一家企业 对方企业也登记在本平台。 写法与“发起企业自己”相同，换成对方的企业 OpenId 和经办人 OpenId。对方企业必须已经完成认证。
平台外的企业 对方没有登记在本平台，只知道企业名称和经办人。 orgName 必须与营业执照上的名称完全一致，名称里的括号用中文括号（）。 name、mobile 是对方经办人的真实姓名和手机号。 不传 orgOpenId 时，平台会自动告诉腾讯电子签“这是平台外的企业”。对方经办人默认会收到短信通知，传 "notifyType": "NONE" 可以关掉。
本企业自动盖章 发起企业不想每份合同都手动盖章。需要先在腾讯电子签开通企业自动签。 文件发起时必须同时给出 sealId（用哪个章，从印章列表接口取）和 signPositions（盖在哪里）。 模板发起时盖章位置和自动签都在模板里设置，只需要传 type 和 recipientId。
全部字段 字段 是否必填 说明 type 必填 PERSON 个人；ORG 企业；ORG_AUTO 本企业自动盖章 name、mobile 个人必填；平台外企业必填 个人的真实姓名和手机号；企业签署方则是经办人的 idCardNumber 选填 签署人（或经办人）的身份证号，用来限定签署人的身份 orgName 平台外企业必填 企业全称，与营业执照一致 orgOpenId 本平台企业必填 签署企业在本平台的 OpenId。发起企业自己签时就是发起
文件发起和模板发起的区别 文件发起（传 fileId） 模板发起（传 templateId） 有哪些签署方 由你决定，数组里写几个就是几个 由模板决定。按模板里的签署方角色逐个给出 签署顺序 数组的顺序就是签署顺序；传 unordered: true 则同时签 由模板决定。数组要按模板里角色的顺序排列 类型 随意组合 必须与模板角色的类型一致：ENTERPRISE 角色给 ORG，INDIVIDUAL 角色给 PERSON；isPromoter 为 true 的
模板里可以放“填写控件”，例如员工姓名、岗位、合同金额。每个控件在模板里都归属于某一方： 归属发起方的控件，在发起合同时通过 formFields 填好，签署方打开合同时看到的就是填好的内容。 归属某个签署方的控件，由那一方在签署页面上自己填写，接口里不能代填，也不需要传。 文件发起的合同内容就是你上传的 PDF 本身，没有需要填写的字段，这一节只适用于模板发起。
第一步：查出要填哪些字段 调用模板列表接口，加上 initiatorOnly=true 。返回的 fields 就是这份模板需要发起方填写的全部内容， recipients 是签署方角色： fields 里每个控件一项： type 是控件类型，决定值的格式； options 是下拉选择类控件的可选项，其它类型为空数组； required 表示是否必填。不加 initiatorOnly 时， fields 会包含所有参与方的控件，每个控件的 recipientId
第二步：按字段名填值 formFields 是一个数组，每个元素是 {"name": 字段名, "value": 值} ： name 要与模板里的控件名称完全一致，包括空格和标点。 同名的控件只给一次。同一份模板里可以有多个同名的控件，例如正文和落款处各有一个“员工姓名”。腾讯电子签按名称匹配，给一次，所有同名的位置都会填上同一个值。 fields 里它们会各占一项，你按名称去重即可；同一个名称给了两次而且值不同，平台会返回 InvalidParameter
日期的格式 日期控件只接受一种写法： yyyy年MM月dd日 。四位年份，月和日各占两位、不足两位在前面补零，中间是汉字“年”“月”“日”，没有空格。 正确 2026年11月01日 2026年01月09日 不接受 2026 11 01 2026/11/01 2026年11月1日（日没有补零） 20261101 带时分秒的写法 不要手写拼接，用 SDK 提供的方法把语言自带的日期类型转成这个格式： 沙箱会按上面的规则检查每个字段：字段名不存在、必填的
完整的例子 用上面那份“劳动合同”模板发起一份合同。请求体： 用 SDK 写：
常见问题 fields 是空的。说明模板里没有归属发起方的填写控件，不需要传 formFields 。腾讯电子签的第三方应用集成里，“把填写控件分配给发起方”是需要单独开通的功能；没有开通时，模板编辑页面上只能把控件分配给签署方，由签署方在签署时填写。需要在发起时代填的话，请联系腾讯电子签的对接经理开通。 recipients 是空的。模板里还没有设置签署方，不能用来发起合同。到控制台的“模板”里编辑模板，添加签署方并为每一方放好签署控件。 提示
上面的简化接口覆盖了最常用的流程。腾讯电子签第三方应用集成的全部 99 个接口，都可以通过 POST /actions/{Action} 调用： params 里不需要传 Agent ，平台会根据 orgOpenId 自动填好，而且只允许使用你自己账号下的企业。返回的 data 就是腾讯电子签的原始响应。登录控制台后，可以在“接口调试”里逐个试。 有十几个接口的作用范围是整个平台，例如应用模板库、全平台用量与账单、批量开通企业。它们只对
腾讯电子签的回调是 AES 加密的，而且一个应用只能配一个地址。平台替你接收和解密，再把明文事件推到你在“回调通知”里配置的地址。你收到的请求是这样的： type 和 data 分别是腾讯电子签回调里的 MsgType 和 MsgData，平台不改动它们的内容。请求头里有： X Qs Timestamp 推送时间，Unix 秒 X Qs Signature "v1=" + hex(HMAC SHA256(回调密钥, 时间戳 + "."
出错时 HTTP 状态码为 4xx 或 5xx，响应体是 {"code":"…","message":"…","requestId":"…"} 。 AuthFailure.MissingHeader 401 缺少签名请求头 AuthFailure.InvalidAppKey 401 AppKey 不存在或已停用 AuthFailure.SignatureMismatch 401 签名不对。检查 AppSecret、签名串的拼接顺序，以及
平台管理员没有接入腾讯电子签之前，平台运行在沙箱模式：企业认证、签署都由平台模拟，接口的入参和出参结构与正式环境相同，回调照常推送，事件里的 sandbox 为 true。沙箱返回的认证链接和签署链接会打开平台自带的模拟页面，点一下按钮就算完成。 切换到正式环境后，代码不用改。区别只有三点：链接会打开腾讯电子签的页面或小程序；签署具有法律效力；沙箱里的企业和合同不会带过去，需要重新登记企业。
接入一共要做哪几步 1. 注册账号，在控制台“开发者 → 应用密钥”里拿到 AppKey 和 AppSecret。 2. 下载 SDK（Java、Python、Go），或者按“请求签名”一节自己实现签名。 3. 登记企业并完成认证：POST /open/v1/orgs，把返回的认证链接交给企业经办人。 4. 上传合同文件（POST /open/v1/files）或准备好模板，发起合同（POST /open/v1/flows），拿签署链接（POST /ope
不写代码能用吗 能。控制台本身就是完整的电子签工具：添加企业、上传 PDF 或用模板发起合同、管理印章、查看进度、催办、撤销、下载，都可以在页面上完成。
沙箱和正式环境有什么区别 沙箱里所有接口由平台模拟：认证和签署在模拟页面里点一下完成，数据是模拟的，签署不具备法律效力，不产生腾讯侧的费用。接口的入参、出参结构和回调格式与正式环境一致，所以代码不用改。平台管理员在“平台管理”里填入腾讯云密钥并切换到正式环境后，全平台一起切换；沙箱里的企业和合同不会带到正式环境，需要重新登记企业。控制台顶部会显示当前是“沙箱模式”还是“正式环境”，接口 GET /api/meta 的 mode 字段也能看到。
签署有法律效力吗 正式环境下的签署、实名认证和存证由腾讯电子签完成，签署具有法律效力。沙箱模式下的一切都是模拟的，不具备法律效力。具体合同是否适合用电子签（例如涉及不动产转让、婚姻继承等法律另有规定的情形），请咨询法务。
合同额度怎么算 每成功发起一份合同扣 1 份额度，合同组按里面的子合同份数扣。发起失败会自动退回；发起成功后撤销、拒签、过期都不退。通过嵌入页面等方式在平台之外发起的合同，平台在收到它的第一条回调时计 1 份。新注册的账号有一些赠送额度，用完后联系平台管理员增加。
签署人需要注册或安装什么吗 不需要提前注册。正式环境下签署人打开链接后进入腾讯电子签小程序（微信里）或 H5 页面，按提示完成实名认证后签署。企业签署方的经办人需要是该企业在电子签里已实名的员工。
个人和企业签署有什么不同 个人签的是手写签名，签署时做个人实名认证（姓名、手机号、刷脸等）。企业签的是盖章，由经办人（企业里有用印权限的员工）代表企业操作；也可以开通自动签让系统自动盖章。
签署顺序怎么控制 文件发起：approvers 数组的顺序就是签署顺序，前一个签完后一个才能签；传 unordered: true 则所有人可以同时签。模板发起：顺序由模板决定。
怎么指定签名或盖章的位置 文件发起时在签署方里传 signPositions：[{"page":1,"x":100,"y":600,"kind":"SEAL"}]，单位是 pt，原点在页面左上角，kind 为 SIGNATURE（签名）、SEAL（印章）或 DATE（日期）。所有签署方都不传时，由签署人在签署时自己拖放位置。模板发起时位置在模板里已经放好。控制台“发起合同”页可以在 PDF 预览上直接拖放。
怎么知道合同签完了 推荐用回调：配置回调地址后，合同每次状态变化都会收到 FlowStatusChange 事件，data.FlowStatus 为 ALL 表示全部签完。也可以主动查询 GET /open/v1/flows/{flowId}。不建议高频轮询。
签完的合同在哪里下载 控制台合同详情页点“下载 PDF”。接口是 GET /open/v1/flows/{flowId}/download，返回的下载地址有时效（几分钟），拿到后尽快下载并保存到你自己的存储。平台只长期保存你上传的原始文件，签完的合同 PDF 每次都是实时从电子签取的。
文件存在哪里，安全吗 你通过平台上传的原始文件会存一份在平台的对象存储里，按租户分目录存放，只有上传它的账号能取回。GET /open/v1/files/{fileId} 返回文件信息和一个临时下载地址。
一个账号可以管理多家企业吗 可以。一个账号下可以登记多家企业，每家各自认证，接口里用 orgOpenId 区分。控制台顶部可以切换“当前企业”。
支持哪些语言的 SDK Java（8 及以上，零依赖）、Python（3.8 及以上，零依赖）、Go（1.18 及以上，只用标准库）。在接入文档页或控制台“接入文档”里下载。SDK 里包含签名、常用接口的封装、原生接口透传（invoke）、回调验签和可运行的示例。别的语言按“请求签名”一节实现签名即可，算法只有两行。
简化接口不够用怎么办 所有原生接口都可以通过 POST /open/v1/actions/{接口名} 调用，params 与腾讯电子签官方文档一致，不用传 Agent。简化接口的大部分请求体也支持 extra 字段，里面的内容会原样合并进底层接口的参数。控制台“开发者 → 接口调试”可以逐个接口试。
可以让 AI 助手直接操作电子签吗 可以，通过 MCP。在“开发者 → MCP 接入”里创建一个令牌，把平台的 MCP 地址和令牌配置到 Claude、Cursor 等支持 MCP 的客户端里，就能用自然语言让 AI 查合同进度、按模板发起合同、催办等。令牌可以限定为只读。详见“MCP 接入”。
Copilot 会看到我的数据吗 没登录时，Copilot 只能查文档、接口目录和 SDK 源码。登录后，它可以只读地查询你自己账号下的数据（合同台账、调用日志、回调事件与投递记录等）来帮你排查问题，查不到别的账号的任何东西；交给大模型的内容里手机号和证件号会先打码，日志详情里的签署链接、登录链接会被去掉，应用密钥和回调密钥不会提供给它。它不能替你发起、修改或撤销任何东西。回答里不会加载外部图片，站外链接在新窗口打开。
忘记密码或想修改密码 登录后点右上角的头像，选“修改密码”。忘记密码请联系平台管理员。
回调地址可以配几个，能按事件类型订阅吗 每个账号最多 10 个回调地址，每个地址可以订阅全部事件或只订阅指定的类型，可以单独启用、停用、重置密钥、发送测试事件。平台已知的事件类型：FlowStatusChange（合同状态变化）、OrgAuth（企业认证结果）、OperateSeal（印章变动）、AuditSealAuth（印章审核结果）、SealPolicyWorkflow（用印审批）、EmployeeSealAuth（员工执业章授权）。电子签今后新增的类型也会照常转发。
接口有调用频率限制吗 平台本身没有对开放 API 设置频率限制；底层的腾讯电子签接口各有自己的频率限制，超过时会返回对应的错误（通常是 RequestLimitExceeded 开头）。批量操作时建议控制并发并在失败时退避重试。
租户、账号 在平台上注册的一个公司或团队就是一个租户（也叫账号）。租户之间的数据完全隔离：企业、合同、文件、回调、日志都只能看到自己的。合同额度按租户计算。
应用、AppKey、AppSecret 应用代表你的一个业务系统。每个应用有一对 AppKey 和 AppSecret，用来给开放 API 的请求签名。在控制台“开发者 → 应用密钥”里创建、查看、重置、停用。一个账号最多 20 个应用。AppSecret 只应保存在你的服务端，不要放进前端代码或 App 安装包；怀疑泄露时在控制台重置，旧密钥立即失效。
企业（子客企业）、企业 OpenId（orgOpenId） 要用自己的名义发起合同、盖章的公司，在平台上叫“企业”。每家企业有一个你自己起的唯一标识 orgOpenId（字母、数字、下划线、短横线，最长 64 位），之后所有接口都用它来指明“以哪家企业的身份”。企业必须先完成认证才能发起合同。orgOpenId 在整个平台内唯一，先登记者拥有。
企业认证、认证链接 登记企业后会得到一个认证链接，由企业的经办人打开，按页面提示提交营业执照、完成法定代表人或超管的实名，认证通过后企业才可用。认证只需要做一次。沙箱模式下认证链接打开的是平台自带的模拟页面，点一下就算通过。
超管、经办人、员工 OpenId（openId / operatorOpenId） 超管是企业在电子签里的最高管理员，通常是完成企业认证的那个人。员工是企业里能发起或签署合同的人，每个员工有一个 openId。接口里的 operatorOpenId 表示“这次操作由哪位员工经办”，不传时默认用企业超管。企业作为签署方时，approvers 里的 openId 表示由哪位员工代表企业盖章。
合同（签署流程）、合同编号（flowId） 发起一次签署就产生一份合同，也叫签署流程（Flow），用 flowId 标识。合同的状态：INIT 待签署、PART 签署中（有人签了但还没签完）、ALL 已完成、REJECT 已拒签、CANCEL 已撤销、DEADLINE 已过期、INVALID 已失效、RELIEVED 已解除。
签署方（approver） 合同里需要签字或盖章的每一方。类型有三种：PERSON 个人；ORG 企业（由经办人代表企业盖章）；ORG_AUTO 发起企业自动盖章。签署方的状态：PENDING 待签署、WAITPICKUP 待领取（企业签署方还没有指定经办人）、ACCEPT 已签署、REJECT 已拒签等。
文件发起、模板发起 发起合同有两种方式。文件发起：上传一份 PDF，签署方和签署位置由你在请求里指定。模板发起：先在电子签里做好模板（固定的正文、填写控件、签署位置、签署方角色），发起时只需要填内容和指定每个角色是谁。合同格式固定、批量签的场景用模板更省事。
模板、签署方角色（recipient）、填写控件（component） 模板里预先定义了有哪几方签（角色，每个角色有 recipientId）、每一方在哪里签、合同里有哪些需要填写的内容（填写控件，例如员工姓名、金额、日期）。归属发起方的控件在发起时通过 formFields 填好；归属签署方的控件由对方在签署时填。
印章、用印授权 企业在电子签里的电子印章：公章、合同专用章、财务章、人事章、法定代表人章等。企业签署时盖的就是它。新建的印章需要审核。可以指定哪些员工能使用哪个印章，这叫用印授权。
签署链接 发起合同后，每个签署方有一个自己的签署链接。把链接发给对方，对方打开后完成实名认证并签署。正式环境下链接会打开腾讯电子签小程序或 H5 页面；沙箱模式下打开平台自带的模拟签署页。链接有有效期，过期后重新获取即可。
回调、事件、回调地址、回调密钥 合同状态变化、企业认证完成、印章变动时，平台会主动向你配置的回调地址发一个 HTTP POST 请求，请求体是一条 JSON 事件。每个回调地址有一把回调密钥（whsec_ 开头），用来验证请求确实来自平台。在控制台“开发者 → 回调通知”里配置，一个账号最多 10 个地址，每个地址可以只订阅部分事件类型。
投递、重试 一条事件向一个回调地址发送一次，叫一次投递。你的服务在 5 秒内返回 HTTP 2xx 表示收到；否则平台会按 5 秒、30 秒、2 分钟、10 分钟、30 分钟、1 小时、2 小时的间隔重试，全部失败后可以在控制台手动重新投递。
沙箱模式、正式环境 平台管理员没有接入腾讯电子签正式环境之前，平台运行在沙箱模式：所有接口由平台模拟，入参出参的结构与正式环境一致，认证和签署都在模拟页面里点一下完成，回调照常推送（事件里 sandbox 为 true）。沙箱里的签署不具备法律效力。切换到正式环境后代码不用改，但沙箱里的企业和合同不会带过去。
合同额度 每个租户能发起的合同份数。每成功发起一份合同扣 1 份（合同组按子合同份数扣），发起失败会退回，撤销不退。额度用完时发起接口返回 QuotaExceeded（HTTP 402），需要联系平台管理员增加。
简化接口、原生接口、透传 简化接口是平台整理过的十几个 REST 接口（/orgs、/files、/flows 等），参数少、命名统一，覆盖最常用的流程。原生接口是腾讯电子签第三方应用集成的全部接口（约 99 个），通过 POST /open/v1/actions/{接口名} 原样调用，这种方式叫透传：params 与官方文档一致，Agent 由平台自动填。
Agent 腾讯电子签原生接口里用来表明“哪个应用、哪家企业、哪位员工”的结构体。直接对接腾讯电子签时每个请求都要自己组装；通过平台调用时不用传，平台会根据 orgOpenId 和 operatorOpenId 生成，而且只允许使用你自己账号下的企业。
授权签、自动签 不需要每次手动操作就能完成签署的能力。企业自动签：企业的章由系统自动盖上（ORG_AUTO），需要先开通“企业自动签”扩展服务。企业之间的授权签：一家企业授权另一家企业代它自动盖章。个人自动签：个人开通后，指定场景的合同由系统代他自动签名。在控制台“授权签”页面办理。
存证、验签、出证报告 合同签完后，签署过程（谁、什么时间、用什么方式认证并签署）会被记录并存证。验签是检查一份合同 PDF 里的数字签名是否有效、文件是否被改动过。出证报告是一份记录签署全过程的文件，发生纠纷时可以提交给法院或仲裁机构。在控制台“存证验签”页面办理。
嵌入页面 把电子签的页面（创建印章、编辑模板、发起合同、合同详情等）放进你自己系统的 iframe 里，用户不用离开你的产品。链接由你的服务端向平台申请，自带登录态，有有效期。在控制台“开发者 → 嵌入页面”里可以生成和预览。
一码多签、签署码 针对一个模板生成一个二维码，任何人扫码都能各自签一份合同，适合入职登记、活动报名这类一对多的场景。在控制台“模板”页面生成和作废。
合同组 把多份合同打包成一组一起发出，签署人一次确认就全部签完，例如入职时的劳动合同、保密协议和员工手册。
动态合同 发起时不确定全部签署人，之后可以陆续追加签署人的合同。全部签完后需要手动结束。
MCP、MCP 令牌 MCP（Model Context Protocol）是让 AI 助手调用外部工具的开放协议。平台提供了一个 MCP 服务，Claude、Cursor 等支持 MCP 的 AI 客户端连上以后，可以直接用自然语言让 AI 查合同、发合同、催办。连接需要一个 MCP 令牌（qsmcp_ 开头），在控制台“开发者 → MCP 接入”里创建，可以限定只读、读写或完整权限。
Copilot（智能助手） 页面右下角的问答助手。可以问接入方法、名词解释、参数写法、错误原因；登录后还能结合你账号里的调用日志、回调投递记录帮你排查具体问题。它只读取数据，不会替你发起或修改任何东西。
requestId（请求 ID） 每次接口调用的唯一编号，出现在响应的 requestId 字段和控制台的调用日志里。向平台或腾讯电子签反馈问题时带上它，能快速定位到那一次调用。沙箱模式下以 sandbox 开头。
MCP 是什么，能用它做什么 MCP（Model Context Protocol）是让 AI 助手调用外部工具的开放协议。平台内置了一个 MCP 服务，把电子签的能力做成了一组 AI 可以直接调用的工具。在 Claude、Cursor、Cherry Studio、Cline 等支持 MCP 的客户端里配置好以后，可以直接对 AI 说： “帮我看看这周还有哪些合同没签完，催一下。” “用劳动合同模板给李四发一份，岗位店长，月薪 9000，11 月 1 日入职。” “
连接地址和鉴权 地址： https://esign.weig.tech/mcp 传输方式：Streamable HTTP（无状态，POST 一个 JSON RPC 请求，返回 JSON） 鉴权：请求头 Authorization: Bearer <MCP 令牌 令牌在控制台“开发者 → MCP 接入”里创建，以 qsmcp_ 开头，只在创建时显示一次，平台只保存它的哈希。令牌可以随时停用或删除，可以设置有效期。 有的客户端不能设置自定义请求头，这时可以
令牌的权限 权限 能做什么 只读 read 查企业、员工、模板、印章、合同及进度、下载地址、账号概况、调用与回调记录，检索文档和接口说明 读写 write 在只读的基础上：登记企业、上传文件、用文字生成合同文件、发起合同、取签署链接、催办、撤销合同、生成嵌入页面链接 完整 full 在读写的基础上：调用任意原生接口（esign_invoke_api） 创建令牌时还可以：限定只能操作某一家企业；只勾选允许使用的部分工具。建议按“够用就行”来给：只需要
在各客户端里怎么配置 Claude Code： Cursor（ ~/.cursor/mcp.json 或项目里的 .cursor/mcp.json ）、以及其它使用 mcpServers 配置格式的客户端： Claude Desktop 等只支持本地（stdio）服务的客户端，用 mcp remote 转接： VS Code（ .vscode/mcp.json ）： 用代码连接（Python，官方 mcp 包 2.x）： 控制台的“MCP 接入”页会按你的实
提供了哪些工具 查询类（只读）： esign_get_account 账号概况：运行模式、额度、企业数、各状态合同数、应用与回调概况 esign_list_organizations / esign_get_organization 企业列表与详情 esign_list_employees 员工列表 esign_list_templates 模板列表，带签署方角色和发起方要填的字段 esign_list_seals 印章列表 esign_list_co
安全与数据范围 令牌只能访问创建它的那个账号的数据，工具不接受“账号”作为参数，查询条件由服务端强制限定。 令牌等同于一把能代表你操作电子签的钥匙：读写权限的令牌可以发起合同、消耗额度。不要把它提交到代码仓库或发到聊天群里；不再使用的令牌及时删除。 发起、撤销这类操作，工具说明里要求 AI 先向你确认。是否每次都弹出确认取决于你的客户端设置，建议对操作类工具保留人工确认。 每一次工具调用都有记录，在“MCP 接入 → 调用记录”里可以看到是哪个令牌、调
常见问题 返回 401：令牌不对、已停用或已过期。 工具列表里没有发起合同：令牌是只读权限，或者创建时没有勾选这个工具。 报“需要指定 org_open_id”：账号下有多家企业，告诉 AI 用哪一家，或创建一个限定企业的令牌。 起草的合同能直接用吗：esign_draft_document 生成的是排版简单的文档，没有预设签署位置，由签署人自己选位置。内容由 AI 起草，具有法律意义的合同请在签署前人工审阅；格式固定的合同建议做成模板。 协议版
排查问题的一般步骤 1. 看错误码和 message。平台的错误响应是 {"code","message","requestId"}，message 通常已经指出是哪个参数或哪个环节的问题。 2. 在控制台“开发者 → 调用日志”里找到这次调用，可以看到平台实际发给电子签的参数和返回内容。把结果筛选成“只看失败”能很快找到。 3. 回调类问题看“开发者 → 回调通知 → 事件记录”，每条事件的每次投递都有状态码、耗时、对方返回的内容。 4. 先在沙箱里复现
签名不正确：AuthFailure.SignatureMismatch 签名串是五行，用换行符 \n 连接：HTTP 方法（大写）、路径（含查询串）、时间戳、随机串、请求体的 SHA256（十六进制）。签名 = hex(HMAC SHA256(AppSecret, 签名串))。 常见原因，按出现频率排列： 路径没有带查询串。GET /open/v1/flows?status=ALL 参与签名的路径是 /open/v1/flows?status=ALL，问号后面的部分要原样带上，参数顺序和编码与实际发出的完全
时间戳过期：AuthFailure.TimestampExpired X Qs Timestamp 与服务器时间相差超过 300 秒。检查：服务器时钟是否准确（开启 NTP 同步）；是不是用了毫秒（应该是秒，10 位数字）；是不是把签好名的请求缓存起来过了很久才发。
随机串重复：AuthFailure.NonceReused 同一个 AppKey 在时间窗内用了同一个 X Qs Nonce。每次请求都要重新生成 8 到 64 位的随机串。重试失败的请求时也要重新生成随机串和时间戳并重新签名，不能把原请求原样重放。
AppKey 不存在或已停用：AuthFailure.InvalidAppKey 检查 X Qs App Key 是否抄错；应用是否在控制台被停用或删除；是不是把测试环境的 AppKey 用到了另一套部署上。
缺少签名请求头：AuthFailure.MissingHeader 四个请求头 X Qs App Key、X Qs Timestamp、X Qs Nonce、X Qs Signature 缺一不可。经过反向代理时确认代理没有丢弃自定义请求头。
企业不存在：OrgNotFound orgOpenId 写错，或者这家企业是另一个账号登记的。用 GET /open/v1/orgs 看当前账号下有哪些企业。注意 orgOpenId 区分大小写。
企业还没有认证 发起合同、查模板、查印章时提示企业未认证或未激活：企业登记后必须由经办人打开认证链接完成认证。用 GET /open/v1/orgs/{openId} 查看 activated 是否为 true；需要新的认证链接时调用 POST /open/v1/orgs/{openId}/console url。也可以配置回调，收到 OrgAuth 事件且 AuthSuccess 为 true 时表示认证完成。
OpenId 冲突：OpenIdConflict 企业或员工的 OpenId 在整个平台内唯一，这个标识已经被（可能是别的账号）占用。换一个，建议带上你自己系统的前缀。
合同额度不足：QuotaExceeded HTTP 402。账号的合同额度用完了，message 里会写剩余几份、本次需要几份。联系平台管理员增加额度。额度在控制台左下角和“概览”页可以看到。
合同不存在：FlowNotFound flowId 写错，或者这份合同不是通过当前账号发起的。通过嵌入页面等方式在平台之外发起的合同，要等平台收到它的第一条回调后才会进入台账。
参数错误：InvalidParameter message 会指出是哪个参数。发起合同时最常见的几种： fileId 和 templateId 必须给一个且只能给一个。 个人签署方缺 name 或 mobile；mobile 不是 11 位大陆手机号。 企业签署方既没给 orgName 也没给 orgOpenId。 模板发起时 approvers 的个数、顺序、类型与模板的 recipients 不一致，或者没带 recipientId。 formFields 里的字段名与模板控
模板发起时提示签署方与模板不一致 先调用 GET /open/v1/templates?orgOpenId=xxx&initiatorOnly=true 拿到模板的 recipients。approvers 要按 recipients 的顺序逐个对应：ENTERPRISE 角色给 ORG，INDIVIDUAL 角色给 PERSON，每个元素带上对应的 recipientId。isPromoter 为 true 的角色是发起方，由发起企业自己签。
模板的 fields 是空的 模板里没有归属发起方的填写控件，不需要传 formFields。腾讯电子签的第三方应用集成里，“把填写控件分配给发起方”是需要单独开通的功能；没有开通时控件只能分配给签署方，由签署方在签署时填写。
收不到回调 按顺序检查： 1. 控制台“开发者 → 回调通知”里有没有配置回调地址、是否启用、订阅的事件类型是否包含你要的类型。 2. 在回调地址上点“发送测试”，看能否送达。 3. 看“事件记录”：如果事件存在但投递失败，状态码和错误信息会告诉你原因（超时、连接被拒、证书问题、返回了非 2xx）。 4. 回调地址必须是公网可访问的 http 或 https 地址。指向内网、本机（localhost、192.168.x.x 等）的地址默认不允许；本
回调验签失败 签名是 "v1=" + hex(HMAC SHA256(回调密钥, 时间戳 + "." + 原始请求体))，在请求头 X Qs Signature 里，时间戳在 X Qs Timestamp 里。常见原因： 用解析后再序列化的 JSON 去验签。必须用收到的原始字节，很多 Web 框架需要专门的方式取原始请求体。 用了 AppSecret 而不是回调密钥。回调密钥以 whsec_ 开头，每个回调地址各有一把，在“回调通知”里查看。 回调
同一个事件收到多次，或者顺序不对 这是正常的：平台保证至少送达一次，重试会带来重复，网络延迟会带来乱序。用事件的 id 去重；更新合同状态时不要让“已完成”被迟到的“签署中”覆盖，可以比较事件的 createdAt，或者只接受状态向前推进。
合同状态没有更新 控制台的合同列表由回调实时更新。打开合同详情点“同步状态”会主动向电子签查询一次。接口方面，GET /open/v1/flows/{flowId} 默认会实时同步（refresh=true）。如果签署已完成而状态长时间不变，登录后让 Copilot 追踪这份合同，它会把事件、投递和相关调用放在一起看。
签署人打不开链接或无法签署 链接过期：重新调用 POST /open/v1/flows/{flowId}/sign urls 获取。 姓名或手机号与本人实名信息不一致：签署时要做实名认证，发起时填的必须是真实姓名和本人手机号。填错了只能撤销重发，或用“补充签署人”修正尚未指定的信息。 还没轮到他签：有序签署时要等前面的人签完。 企业签署方显示“待领取”：发起时没有指定经办人（openId），需要企业里有权限的员工领取，或在控制台合同列表里“指定经办人领取”。 沙箱
上传文件失败，或 fileId 用不了 文件内容要做 Base64 编码后放在 contentBase64 里，整个请求体不能超过 40MB。 发起合同只能用 PDF。Word、Excel、图片要先转成 PDF（控制台“合同 → 文件转 PDF”，或原生接口 CreateFileConvertTask）。 fileId 默认一小时内有效，过期后要重新上传。不要把 fileId 长期保存下来反复用。 加密的、带编辑限制的、已经带数字签名的 PDF 可能无法用来发起。
PlatformOnly 这个原生接口的作用范围是整个平台（应用模板库、全平台用量与账单、批量开通企业、嵌入页面主题等），只有平台管理员可以调用。普通账号需要这类操作时联系平台管理员。
PlatformNotConfigured（HTTP 503） 平台已经切换到正式模式，但腾讯云的密钥或应用号没有配置完整。这是平台侧的问题，联系平台管理员。
腾讯电子签返回的其它错误 不在上面列表里的错误码（例如 FailedOperation.xxx、InvalidParameter.xxx、OperationDenied.xxx、ResourceNotFound.xxx）是腾讯电子签原样返回的，code 和 message 与官方文档一致。常见的几类：企业没有开通某项功能或扩展服务（OperationDenied 开头）、参数不合法（InvalidParameter 开头）、资源不存在或已过期（ResourceN
连不上平台，或返回 5xx 确认接口地址写对了：开放 API 在 /open/v1 下面。 502 / 503 / 504 多半是部署层面的问题（平台重启、网关超时）。稍后重试，重试时重新生成随机串并重新签名。 500 InternalError 是平台内部错误，把 requestId 和发生时间告诉平台管理员。 413 RequestTooLarge：请求体超过 40MB。 429 TooManyAttempts：登录尝试过多，5 分钟后再试。
MCP 连不上 确认地址是 https://esign.weig.tech/mcp，传输方式选 Streamable HTTP（有的客户端写作 HTTP）。 令牌放在请求头 Authorization: Bearer qsmcp_… 里。返回 401 说明令牌不对、被停用或已过期，在“开发者 → MCP 接入”里检查。 工具列表里看不到发起合同等工具：令牌的权限是只读，换成读写权限的令牌。 工具调用报“只能操作企业 xxx”：令牌限定了企业，换一个不限