调用约定

本文约定开放接口的通信方式、鉴权、报文格式与通用响应结构。具体字段以各接口文档为准。

基本约定

项	约定
协议	HTTPS
接口基址	开通时提供，下文记为 `{baseUrl}`
字符编码	UTF-8
鉴权	每个请求在 Header 携带 `X-Api-Key`
时间格式	`yyyy-MM-dd HH:mm:ss`；签署截止时间须晚于请求时刻
JSON 请求	`Content-Type: application/json`
附件上传	有补充附件时使用 `multipart/form-data`
文件大小	合同 PDF、单个附件均不超过 50MB

合同正文不随创建请求直接上传 PDF 二进制：由接入方提供可访问的 HTTPS 地址（fileUrl），平台在创建时拉取。地址无法访问或拉取超时返回 40003；非 PDF 或超限返回 40002。

除特别说明外，所有接口（含下载合同文件）均须携带：

http

X-Api-Key: sk_live_example

请替换为开通时分配的真实 apiKey。获取方式见接入凭证。

路径使用名词资源，由 HTTP 方法表示操作：

方法	路径	说明
`GET`	`/open/v1/templates`	模板列表
`GET`	`/open/v1/templates/{templateId}`	模板详情
`POST`	`/open/v1/contracts`	创建合同
`GET`	`/open/v1/contracts`	合同列表
`GET`	`/open/v1/contracts/{contractId}`	合同详情
`GET`	`/open/v1/contracts/{contractId}/file`	下载合同 PDF
`GET`	`/open/v1/contracts/{contractId}/sign-url`	获取合同签署链接
`PATCH`	`/open/v1/contracts/{contractId}`	撤回合同

完整说明见API概览。

除「下载合同文件」成功时直接返回 PDF 流外，其余 JSON 接口响应体统一为：

json

{
  "code": 0,
  "message": "ok",
  "data": {}
}

失败时的 HTTP 状态与业务 code 见错误码查询。

列表类接口使用查询参数：

参数	说明
`page`	页码，从 1 开始，默认 1
`pageSize`	每页条数，默认 20，最大 100

成功时 data 结构为：

json

{
  "total": 1,
  "list": []
}