手工签署的API

基本介绍

该接口用于发起手工签署任务：

• 上传一个待签署文件（PDF/Word）
• 指定一个签署人（系统内已有用户）
• 系统创建一条 该签署人的手工签署任务
• 如上传的是 Word，会自动进入转码队列；PDF 则直接完成“上传成功”；

该接口不需要方案 plan_id，也不传 stamps 信息（与 自由签章集成 不同）。

接口名称

/api/manual?app_id=xxx

请求方式

POST，使用 multipart/form-data 上传。

鉴权方式

• timestamp：时间戳（秒）
• token：md5(app_id + app_secret + timestamp)

服务端校验要求：

• token 必须匹配
• timestamp 与服务器时间差不超过 60 秒

FORM 字段说明

1. 文件字段

字段名	是否必须	描述
file2signed	是	待签署文件（一次只上传一个文件）

支持的文件扩展名：pdf、doc、docx。

2. 业务字段

字段名	是否必须	类型	描述
signer	是	string	签署人姓名（必须是系统中存在的用户）
filesn	否	string	文件自身编号，不能超过60个字，系统不做排重使用
callback	否	string	签署完成后的回调地址

说明：

• signer 会被转换为系统用户 id，并写入 next_auditor。
• callback 的回调格式建议参考 doc_instructions/docs/Callback.md。

返回值（JSON）

成功时返回（示例字段）：

字段名	类型	描述
msg	string	提示信息（PDF 为“文件上传成功”，Word 为“已经将文件加入转换队列”）
report_id	int	本次创建的文件记录
sn	string	本次生成的文件防伪码（防伪系统的生成编号，不是文件自己的编号）

失败时：返回 HTTP 4xx，并带错误信息（例如：参数不完整、token 校验失败、签署人不存在、文件类型不支持等）。

示例代码

python3 示例（需要 requests）：

import requests
import time
import hashlib


def test_manual_sign_api(url_base, app_id, app_secret, file_path, signer, filesn="", callback=""):
    timestamp = int(time.time())
    plan_id = ""  # 手工签署接口：plan_id 取空字符串参与 token 计算
    token_src = f"{app_id}{app_secret}{timestamp}{plan_id}"
    token = hashlib.md5(token_src.encode("utf-8")).hexdigest()

    url = f"{url_base}/api/manual?app_id={app_id}"
    headers = {
        "timestamp": str(timestamp),
        "token": token,
    }

    with open(file_path, "rb") as f:
        files = {
            "file2signed": (file_path.rsplit("/", 1)[-1], f),
        }
        data = {
            "signer": signer,
            "filesn": filesn,
            "callback": callback,
        }
        resp = requests.post(url, headers=headers, files=files, data=data)
        print(resp.status_code)
        print(resp.text)


if __name__ == "__main__":
    test_manual_sign_api(
        url_base="http://localhost:3000",
        app_id="your_app_id",
        app_secret="your_app_secret",
        file_path=r"E:\\test.docx",
        signer="张三",
        filesn="CTSL9876543219",
        callback="https://your.callback/endpoint",
    )