合同签署接口

合同签署相关的全部 API 接口文档，包含创建合同、查询状态、下载文件、撤销合同

创建合同

POST/api/v1/contract/create

创建一个电子合同签署任务，上传合同文件并配置签署方信息。合同创建后自动向所有签署方发送签署通知。

请求参数

参数名	类型	必填	说明
contractName	String	是	合同名称，长度 1-100 个字符
contractFile	String	是	合同文件 Base64 编码内容
contractFileName	String	是	合同文件名，含扩展名（如 contract.pdf）
signers	Array<Signer>	是	签署方列表，至少 1 人，最多 50 人
signers[].name	String	是	签署方姓名
signers[].phone	String	是	签署方手机号（11 位）
signers[].role	String	是	角色：signer(签署方) \| approver(审批方) \| cc(抄送方)
signers[].signType	String	否	签署方式：seal(印章) \| signature(手签)，默认 seal
signOrder	Integer	是	签署顺序：1=顺序签署，2=并行签署
expireAt	String	否	签署截止日期（YYYY-MM-DD），默认发起后 30 天
callbackUrl	String	否	自定义回调地址，覆盖应用级别的默认回调配置

响应参数

参数名	类型	说明
contractId	String	合同编号，后续操作的核心标识
status	String	合同状态，创建后为 pending（待签署）
signUrl	String	签署链接，可直接发送给签署方
createdAt	String	创建时间（ISO 8601 格式）

请求示例

JSON

{
  "appId": "app_xxxxxx",
  "timestamp": 1705312800000,
  "nonce": "a1b2c3d4e5",
  "sign": "calculated_signature",
  "data": {
    "contractName": "技术服务协议",
    "contractFile": "JVBERi0xLjQKJeLj...",
    "contractFileName": "contract.pdf",
    "signers": [
      {
        "name": "张三",
        "phone": "13800138000",
        "role": "signer",
        "signType": "seal"
      },
      {
        "name": "李四",
        "phone": "13900139000",
        "role": "signer",
        "signType": "signature"
      }
    ],
    "signOrder": 1,
    "expireAt": "2025-02-15"
  }
}

响应示例

JSON

{
  "code": 0,
  "message": "ok",
  "data": {
    "contractId": "CT202501150001",
    "status": "pending",
    "signUrl": "https://sign.flashsign.cn/s/abc123",
    "createdAt": "2025-01-15T10:30:00+08:00"
  },
  "traceId": "trace_xxxxxx"
}

查询合同状态

POST/api/v1/contract/status

查询指定合同的当前状态和签署进度，包括各签署方的签署状态。

请求参数

参数名	类型	必填	说明
contractId	String	是	合同编号

响应数据

参数名	类型	说明
contractId	String	合同编号
contractName	String	合同名称
status	String	合同状态
signers	Array	签署方列表（含每个人的签署状态）
signers[].name	String	签署方姓名
signers[].status	String	个人签署状态：pending \| signed \| refused
signers[].signedAt	String	签署时间（仅已签署时有值）
completedAt	String	合同签署完成时间

下载合同文件

POST/api/v1/contract/download

下载已签署的合同文件，包含数字签名和签章可视化效果。支持 PDF 和 OFD 两种格式。

请求参数

参数名	类型	必填	说明
contractId	String	是	合同编号
format	String	否	下载格式：pdf \| ofd，默认 pdf

响应数据

参数名	类型	说明
fileName	String	文件名
content	String	文件内容 Base64 编码
size	Long	文件大小（字节）
hash	String	文件 SM3 哈希值，可用于验签

撤销合同

POST/api/v1/contract/cancel

撤销尚未签署完成的合同。仅在合同状态为 pending（待签署）时可撤销，已完成签署的合同不可撤销。

请求参数

参数名	类型	必填	说明
contractId	String	是	合同编号
reason	String	否	撤销原因，最多 200 字

合同状态枚举

状态值	含义	说明
draft	草稿	合同已创建但尚未发送给签署方
pending	待签署	合同已发送，等待签署方操作
signed	已完成	所有签署方均已完成签署
expired	已过期	超过签署截止日期，合同自动失效
cancelled	已撤销	发起方主动撤销合同
rejected	已拒签	签署方拒绝签署

认证鉴权

SDK 使用说明

参数名

类型

必填

说明

contractName

String

是

合同名称，长度 1-100 个字符

contractFile

String

是

合同文件 Base64 编码内容

contractFileName

String

是

合同文件名，含扩展名（如 contract.pdf）

signers

Array<Signer>

是

签署方列表，至少 1 人，最多 50 人

signers[].name

String

是

签署方姓名

signers[].phone

String

是

签署方手机号（11 位）

signers[].role

String

是

角色：signer(签署方) | approver(审批方) | cc(抄送方)

signers[].signType

String

否

签署方式：seal(印章) | signature(手签)，默认 seal

signOrder

Integer

是

签署顺序：1=顺序签署，2=并行签署

expireAt

String

否

签署截止日期（YYYY-MM-DD），默认发起后 30 天

callbackUrl

String

否

自定义回调地址，覆盖应用级别的默认回调配置

参数名

类型

说明

contractId

String

合同编号，后续操作的核心标识

status

String

合同状态，创建后为 pending（待签署）

signUrl

String

签署链接，可直接发送给签署方

createdAt

String

创建时间（ISO 8601 格式）

{ "appId": "app_xxxxxx", "timestamp": 1705312800000, "nonce": "a1b2c3d4e5", "sign": "calculated_signature", "data": { "contractName": "技术服务协议", "contractFile": "JVBERi0xLjQKJeLj...", "contractFileName": "contract.pdf", "signers": [ { "name": "张三", "phone": "13800138000", "role": "signer", "signType": "seal" }, { "name": "李四", "phone": "13900139000", "role": "signer", "signType": "signature" } ], "signOrder": 1, "expireAt": "2025-02-15" } }

{ "code": 0, "message": "ok", "data": { "contractId": "CT202501150001", "status": "pending", "signUrl": "https://sign.flashsign.cn/s/abc123", "createdAt": "2025-01-15T10:30:00+08:00" }, "traceId": "trace_xxxxxx" }

参数名

类型

必填

说明

contractId

String

是

合同编号

参数名

类型

说明

contractId

String

合同编号

contractName

String

合同名称

status

String

合同状态

signers

Array

签署方列表（含每个人的签署状态）

signers[].name

String

签署方姓名

signers[].status

String

个人签署状态：pending | signed | refused

signers[].signedAt

String

签署时间（仅已签署时有值）

completedAt

String

合同签署完成时间

参数名

类型

必填

说明

contractId

String

是

合同编号

format

String

否

下载格式：pdf | ofd，默认 pdf

参数名

类型

说明

fileName

String

文件名

content

String

文件内容 Base64 编码

size

Long

文件大小（字节）

hash

String

文件 SM3 哈希值，可用于验签

参数名

类型

必填

说明

contractId

String

是

合同编号

reason

String

否

撤销原因，最多 200 字

状态值

含义

说明

draft

草稿

合同已创建但尚未发送给签署方

pending

待签署

合同已发送，等待签署方操作

signed

已完成

所有签署方均已完成签署

expired

已过期

超过签署截止日期，合同自动失效

cancelled

已撤销

发起方主动撤销合同

rejected

已拒签

签署方拒绝签署