签签开放平台

创建合同 ​

接口说明 ​

两种创建方式共用该地址。请求须且只能包含 fileUrl 与 templateId 其中之一。两个同时出现，或都不出现时，返回 40001。

方式识别条件Content-Type
指定合同文件地址含 fileUrl，不含 templateId无附件时为 application/json；有附件时为 multipart/form-data
使用模板含 templateId，不含 fileUrl无附件时为 application/json；有附件时为 multipart/form-data

请求地址：/open/v1/contracts

请求方式：POST

在线调试

请求参数 ​

无附件时，下表字段构成 JSON 正文。有附件时，下表中除 attachments 外的字段组成 JSON，放入表单字段 data，文件放入 attachments。每个请求须携带请求头 X-Api-Key。

参数名称数据类型必须说明
fileUrl
string条件
合同 PDF 的 HTTPS 地址。文件方式必填，模板方式不传
templateId
string条件
模板 ID。模板方式必填，文件方式不传
contractName
string条件
合同名称。文件方式必填；模板方式省略时使用模板名称
deadline
string是
签署截止时间，yyyy-MM-dd HH:mm:ss，须晚于请求时刻
signOrder
string否
parallel 同时签署，sequence 按 signers 数组顺序。默认 parallel
watermark
string否
none / visitor / custom，默认 none
watermarkText
string条件
watermark 为 custom 时必填，最多 30 个字
signers
array是
签署方，至少 1 个
type
string是
person 或 company
templateSignatoryId
string条件
仅模板方式必填
name
string条件
个人姓名
mobile
string条件
个人手机号
companyName
string条件
企业名称
creditCode
string条件
统一社会信用代码
agentName
string条件
经办人姓名
agentMobile
string条件
经办人手机号
needSeal
boolean否
是否须盖章，默认 true
willAuth
string否
none / face / sms，默认 none
seals
array条件
仅文件方式且 needSeal 为 true 时必填。坐标是当前页比例，原点在左上角，x 向右、y 向下，取值 0 到 1
page
number条件
页码，从 1 开始。骑缝章不传
x
number条件
距左侧比例。骑缝章不传
y
number是
距顶部比例
sealType
string是
章类型。
个人：unspecified、rect、handwriting、square
企业：unspecified、official、finance、legal、contract、invoice、hr
showTime
boolean否
是否加签署时间，默认 false。骑缝章不传
acrossPages
boolean条件
骑缝章为 true
fields
object条件
仅模板方式。形如 {"<fieldId>":"填写内容"} 的对象，不是数组。键必须等于模板详情 initiatorFields[].fieldId（通常为数字字符串 ID），值是填写内容。模板无 initiatorFields 时可省略整段；其中 required: true 的必须传，否则 40001。signers[].fields（fillBy=signer）不要写入这里
fieldId
string条件
动态键名 = initiatorFields[].fieldId；对应值为该控件填写内容（string）
attachments
file否
补充附件，最多 9 个，单个不超过 50MB

响应参数 ​

参数名称数据类型必须说明
code
number是
0 表示成功
message
string是
说明
data
object是
业务数据
contractId
string是
合同 ID
signUrl
string是
签署短链（如 https://h5.xwkc.com/r8k2mQ）。落地页可进微信小程序，也可点「在浏览器中签署」
h5SignUrl
string是
浏览器 H5 直达链接（可跳过落地页）。正式 m.xwkc.com，测试 h5dev.xwkc.com；只发短链时可不单独下发此字段

响应示例 ​

json
{
  "code": 0,
  "message": "ok",
  "data": {
    "contractId": "ct_20001",
    "signUrl": "https://h5.xwkc.com/r8k2mQ",
    "h5SignUrl": "https://m.xwkc.com/#/ePackage/pages/contractDetail/index?taskId=ct_20001&sceneCon=personShare"
  }
}

指定合同文件地址 ​

合同正文不随请求上传。传入 fileUrl，不传 templateId、fields。平台在创建时按 fileUrl 拉取 PDF。地址无法访问或拉取超时返回 40003。内容不是 PDF，或超过 50MB，返回 40002。needSeal 为 false 时不传 seals。

bash
curl -X POST "{baseUrl}/open/v1/contracts" \
  -H "X-Api-Key: sk_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "fileUrl": "https://files.example.com/contracts/purchase.pdf",
    "contractName": "采购合同",
    "deadline": "2026-11-20 18:00:00",
    "signOrder": "sequence",
    "watermark": "none",
    "signers": [
      {
        "type": "company",
        "companyName": "示例科技有限公司",
        "creditCode": "91310000MA1EXAMPLE",
        "agentName": "张三",
        "agentMobile": "13800000001",
        "needSeal": true,
        "willAuth": "sms",
        "seals": [
          { "page": 1, "x": 0.72, "y": 0.81, "sealType": "official", "showTime": true }
        ]
      },
      {
        "type": "person",
        "name": "李四",
        "mobile": "13900000002",
        "needSeal": true,
        "willAuth": "face",
        "seals": [
          { "page": 2, "x": 0.68, "y": 0.80, "sealType": "handwriting", "showTime": false },
          { "acrossPages": true, "y": 0.50, "sealType": "rect" }
        ]
      }
    ]
  }'

有补充附件时使用 multipart/form-data：上述 JSON 放入表单字段 data，附件文件放入 attachments。

使用模板 ​

不传 fileUrl，不传 seals。章的位置与类型取自模板。signers 与模板签署方一一对应。

fields 是对象（不是数组），只填发起方控件：

json
"fields": {
  "<initiatorFields[].fieldId>": "<填写内容>"
}

键必须与模板详情返回的 initiatorFields[].fieldId 完全一致；required: true 的必须传。签署方控件在详情的 signers[].fields（fillBy=signer），创建时不要放进 fields。

bash
curl -X POST "{baseUrl}/open/v1/contracts" \
  -H "X-Api-Key: sk_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "1987000000000000001",
    "contractName": "劳动合同-李四",
    "deadline": "2026-11-20 18:00:00",
    "signOrder": "parallel",
    "fields": {
      "1987000000000001001": "产品经理"
    },
    "signers": [
      {
        "templateSignatoryId": "1987000000000002001",
        "type": "company",
        "companyName": "示例科技有限公司",
        "creditCode": "91310000MA1EXAMPLE",
        "agentName": "张三",
        "agentMobile": "13800000001",
        "needSeal": true,
        "willAuth": "sms"
      },
      {
        "templateSignatoryId": "1987000000000002002",
        "type": "person",
        "name": "李四",
        "mobile": "13900000002",
        "needSeal": true,
        "willAuth": "face"
      }
    ]
  }'

上例 fields 里的 1987000000000001001 对应模板详情示例中的发起方控件；signers[].fields 里的签署方控件（如住址）不要出现在创建请求的 fields 中。实际对接请先调模板详情，用返回的真实 ID 替换。

有补充附件时使用 multipart/form-data：上述 JSON 放入表单字段 data，附件文件放入 attachments。

开放平台开发者中心

Copyright © 2026 签签