快速开始

最小化跑通发起签署与查看签署状态两条路径。

前置条件

环境信息

当前 Tencent eSign 仅提供新加坡生产环境，暂未开放沙盒环境与其他区域。

用途	域名
Open API 基础地址	`https://sgapi.tencent-esign.com`
OAuth Consent 前端页	由 `/openapi/v1/oauth/auth` 自动 302 跳转，无需直接拼接
内嵌页	由 `/openapi/v1/embedded/views` 返回完整 URL，无需直接拼接

ℹ️

联调测试请使用集成方自有测试邮箱与小额场景。凭证按地域颁发：当前仅新加坡一个地域，未来扩展时集成方需在新地域重新注册账户并创建 App，凭证不跨地域复用。

凭证准备

集成方在 Tencent eSign 控制台完成下列步骤后即可拿到接入凭证：

注册账户 — 集成方负责人到 Tencent eSign 控制台注册账户，自动创建一个集成方 Space（注册者为该 Space 管理员）
绑定计费资源包 — 在集成方 Space 内购买所需地域的计费资源包（具体购买流程见控制台说明）
创建 OAuth App — 在 App 管理页创建第三方应用，填写 App 名称、redirect_uri、申请的 scope、品牌定制信息（详见内嵌页交互 - 品牌定制）。创建后控制台展示 client_id 与 client_secret（client_secret 仅展示一次，请立即妥善保存；后续可在控制台重置）
多地域接入 — 在每个地域独立完成 1–3 步，凭证 / 资源包不跨地域复用

资源	必填	说明
`client_id`	是	控制台创建 App 时生成
`client_secret`	是	控制台创建 App 时生成，仅展示一次，需妥善保管；泄漏后可在控制台重置
`redirect_uri`	是	创建 App 时填写，自定义协议或 HTTPS URL（不接受 `http://` 明文回调）；与发起授权时传入的值须精确一致；调整在控制台修改
品牌定制配置	否	创建 App 时一并提交，详见内嵌页交互 - 品牌定制

ℹ️

同一 client_id 可被多个用户 Space 授权安装；各用户 Space 的授权与签署数据相互隔离。

步骤总览

A. 发起签署

首次接入需先完成 OAuth 授权：

[1] 集成方应用生成 PKCE
[2] 集成方应用打开 WebView 加载授权 URL
[3] 用户在 Consent 页完成登录、选 Space、点同意
[4] WebView 被 302 至 myapp://oauth-callback?code=...，集成方应用拦截
[5] 集成方应用用 code 换 access_token + refresh_token
[6] 集成方应用用 access_token 调 /openapi/v1/files/upload 上传待签署文件，拿到 FileId
[7] 集成方应用用 access_token 调 /openapi/v1/embedded/views，请求体里带上 FileId，拿到内嵌页 URL
[8] 集成方应用打开 WebView 加载内嵌页 URL，用户在内嵌页完成发起信封

B. 查看签署状态

需先完成 OAuth 授权拿 access_token：

[1] 集成方应用复用本地 access_token（过期则用 refresh_token 换新）
[2] 集成方应用调 /openapi/v1/embedded/views（OperateType=signature_status），拿到内嵌页 URL
[3] 集成方应用打开 WebView 加载该 URL，显示当前用户在选定 Space 下的合同列表

PKCE 生成

// 集成方应用生成
const verifier  = base64url(randomBytes(64));        // 43~128 字符
const challenge = base64url(sha256(verifier));       // PKCE S256

// 暂存 verifier 在内存或安全存储；challenge 用于下一步

打开授权 URL

https://sgapi.tencent-esign.com/openapi/v1/oauth/auth
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &redirect_uri=myapp%3A%2F%2Foauth-callback
  &code_challenge=CHALLENGE
  &code_challenge_method=S256
  &state=RANDOM_NONCE
  &scope=envelope%3Acreate%20envelope%3Aread

GET

授权端点

/openapi/v1/oauth/auth

OAuth 授权入口，WebView 打开此 URL

用 code 换 token

curl -X POST https://sgapi.tencent-esign.com/openapi/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code\
&code=AUTH_CODE_FROM_CALLBACK\
&code_verifier=VERIFIER_FROM_PKCE_STEP\
&client_id=YOUR_CLIENT_ID\
&client_secret=YOUR_CLIENT_SECRET\
&redirect_uri=myapp%3A%2F%2Foauth-callback"

{
  "access_token":  "AT_xxx",
  "token_type":    "Bearer",
  "expires_in":    3600,
  "refresh_token": "RT_xxx",
  "scope":         "envelope:create envelope:read"
}

POST

令牌端点

/openapi/v1/oauth/token

换取或刷新 access_token

上传文件

集成方应用（不在 WebView 内）用 access_token 调上传接口拿到 FileId：

curl -X POST https://sgapi.tencent-esign.com/openapi/v1/files/upload \
  -H "Authorization: Bearer AT_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "Files": [
      { "FileName": "contract.pdf", "FileBody": "<Base64编码内容>" }
    ]
  }'

{
  "Response": {
    "RequestId": "req_01HJ8XYZ...",
    "Data": {
      "Files": [
        { "FileId": "DOC_xxx", "FileName": "contract.pdf" }
      ]
    }
  }
}

返回的 FileId 用于换取内嵌页 URL 时通过 OperateParam.FileIds 绑定到 webview token。

POST

上传文件

/openapi/v1/files/upload

上传待签署文件，获取 FileId

换内嵌页 URL

curl -X POST https://sgapi.tencent-esign.com/openapi/v1/embedded/views \
  -H "Authorization: Bearer AT_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "OperateType":  "request_signatures",
    "OperateParam": { "FileIds": ["DOC_xxx"] }
  }'

{
  "Response": {
    "RequestId": "req_01HJ8XYZ...",
    "Data": {
      "Url":       "https://<frontend-host>/console/envelopes/edit/EV_xxx?EmbeddedToken=xxx",
      "ExpiresAt": "2026-06-24T11:00:00Z"
    }
  }
}

集成方应用把 Url 在 WebView 里打开，剩余流程见内嵌页交互。

POST

获取内嵌页 URL

/openapi/v1/embedded/views

用 access_token 换内嵌页 URL

查看签署状态

复用已有 access_token，调同一个 /embedded/views 端点，把 OperateType 改为 signature_status 即可：

curl -X POST https://sgapi.tencent-esign.com/openapi/v1/embedded/views \
  -H "Authorization: Bearer AT_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "OperateType": "signature_status" }'

响应结构与上一步一致（Url + ExpiresAt），用 WebView 打开 Url 即显示当前用户在选定 Space 下的合同列表。

指定 Space 模式

适用企业/组织场景，用户归属 Space 由集成方预先指定。在上述 OAuth 授权步骤前，需先完成成员预添加：

[0] 集成方应用用 access_token 调 /openapi/v1/members/add，将目标用户预添加为待激活成员（同时发送邀请邮件）
[1] 集成方应用生成 PKCE（同上）
[2] 集成方应用打开 WebView 加载授权 URL（额外带 space_id + login_hint）
[3] 用户在 Consent 页完成登录并点「同意」（无 Space 选择步骤；点同意即视为接受邀请，自动激活成员）
[4] WebView 被 302 至 redirect_uri?code=...，集成方应用拦截
[5-8] 后续与开放模式完全相同（换 token → 上传文件 → 换内嵌页 URL → 发起签署）

ℹ️

用户也可以不经过 OAuth 授权，直接点击邀请邮件链接完成激活，两条路径互不影响。完整时序图见 OAuth 授权流程 - 指定 Space 模式。

POST

预添加成员

/openapi/v1/members/add

指定 Space 模式专用：预添加目标用户为待激活成员

概述 OAuth 授权流程