企业官网建设流程全解析

如何用 DocuSeal /submissions/pdf API 从 PDF 文件创建一次性签署提交

【免费下载链接】docusealOpen source DocuSign alternative. Create, fill, and sign digital documents ✍️项目地址: https://gitcode.com/GitHub_Trending/do/docuseal

当你手上有一份临时 PDF（合同、报价单、声明书等），需要发给一个或多个签署人，但不想在 DocuSeal 里先创建一个可复用的模板时，可以直接调用POST /submissions/pdf接口。该接口从 PDF 文件本身创建一次性的签署提交（one-off submission request），文档接口定义见 docs/api/shell.md 和 docs/openapi.json。适用前提：已有一个 DocuSeal 账号及其 API key；服务端点为https://api.docuseal.com（Global Server）或https://api.docuseal.eu（EU Server），两者均来自 OpenAPI 规范中的servers声明。

与模板提交的区别：无需 template_id

普通的POST /submissions接口要求传入template_id和submitters，即提交必须基于一个已存在的模板。而/submissions/pdf的必填项是documents和submitters——你把 PDF 文件本身和签署人列表传进去即可，接口描述原文是 "create one-off submission request from a PDF"。

字段有两种定义方式，二选一即可：

1. 文本标签：在 PDF 内使用{{Field Name;role=Signer1;type=date}}形式的文本标签定义可填写字段。标签中role指定负责填写的签署角色，type指定字段类型。文档接口示例中给出的标签示例为{{Field Name;role=Signer1;type=date}}。
2. fields参数：在请求体中用像素坐标指定字段位置。每个字段包含name、type、role、areas；areas中的每个区域必须包含x、y、w、h、page五个值，page从 1 开始。文档说明：如果使用了{{...}}文本标签，fields参数可以省略（"Fields are optional if you use {{...}} text tags to define fields in the document"）。

type的可选枚举值为：heading、text、signature、initials、date、number、image、checkbox、multiple、file、radio、select、cells、stamp、payment、phone、verification、kba、strikethrough。select字段通过options数组提供选项值，radio/multiple字段的选项值写在areas的option字段中。

准备 PDF 文件内容

documents数组中每个文档对象必须包含name（文档名称）和file。file接受两种形式（OpenAPI 描述原文）："Base64-encoded content of the PDF file or downloadable file URL."，即 PDF 文件的 Base64 编码字符串，或一个可下载文件的 URL。

如果走 Base64 路线，本地辅助编码命令如下（以 Linux 为例，该命令只读取本地文件并输出编码结果，无其他副作用；contract.pdf替换为你的实际文件名）：

base64 -w 0 contract.pdf

将输出的整行编码字符串作为请求体中file的值。

发送创建请求

文档给出的原始 curl 示例如下（见 docs/api/shell.md 的 "Create a submission from PDF" 一节）：

curl --request POST \ --url https://api.docuseal.com/submissions/pdf \ --header 'X-Auth-Token: API_KEY' \ --header 'content-type: application/json' \ --data '{"name":"Test Submission Document","documents":[{"name":"string","file":"base64","fields":[{"name":"string","areas":[{"x":0,"y":0,"w":0,"h":0,"page":1}]}]}],"submitters":[{"role":"First Party","email":"john.doe@example.com"}]}'

需要替换的部分：

• API_KEY：你的 DocuSeal API key，放在X-Auth-Token请求头中（OpenAPI 中该认证方案为apiKey，位置为 header，名称X-Auth-Token）；
• "file":"base64"：替换为上一步得到的 Base64 字符串，或可下载文件的 URL；
• 两个"string"：文档名称和字段名称，替换为实际值；
• "email"：签署人邮箱。使用文本标签方式定义字段时，fields数组整个省略即可。

请求体中常用的可选参数（均出自 OpenAPI 定义，默认值与文档一致）：

submitters数组中每个签署人除role和email外，还有几个在集成时常用的字段：

• values：按字段名预填值的对象；
• completed：传true时该签署人被标记为已完成并通过 API 自动签署；
• order：工作流顺序号，相同的order值表示同一顺序组；
• require_email_2fa/require_phone_2fa：要求通过邮箱或短信一次性验证码二次验证后才能访问文档；
• invite_by：指定由哪个前序角色通过邮件邀请该签署人；
• external_id：你应用侧的签署人唯一标识；
• send_email：仅对该签署人禁用请求邮件。

验证创建结果

创建成功时接口返回200 OK，响应体必含字段为id、submitters、source、submitters_order、status、documents、expire_at、created_at。以下是 OpenAPI 规范中给出的示例响应（文档示例，字段值仅用于说明结构，不是固定预期输出，此处按关键部分节选）：

{ "id": 5, "name": "Test Submission", "submitters": [ { "id": 1, "uuid": "884d545b-3396-49f1-8c07-05b8b2a78755", "email": "john.doe@example.com", "slug": "pAMimKcyrLjqVt", "status": "sent", "role": "First Party", "embed_src": "https://docuseal.com/s/pAMimKcyrLjqVt" } ], "source": "api", "submitters_order": "preserved", "status": "pending", "schema": [ { "name": "Demo PDF", "attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf" } ] }

据此可以做两层核对：

1. 接口层核对：返回了id，且status为pending、source为api；submitters数组中每个签署人有自己的slug和embed_src（embed_src是用于嵌入签署表单或直接签署的链接值）。签署人status的枚举值为completed、declined、opened、sent、awaiting。
2. 查询端点复核：用创建返回的id调用查询接口（1001为文档示例 ID，替换为实际值）：

curl --request GET \ --url https://api.docuseal.com/submissions/1001 \ --header 'X-Auth-Token: API_KEY'

签署流程走完以后，用文档接口取回最终文件，merge=true时将所有文档合并为单个 PDF：

curl --request GET \ --url https://api.docuseal.com/submissions/1001/documents?merge=true \ --header 'X-Auth-Token: API_KEY'

文档说明：提交未完成时该端点返回部分填写的文档列表，提交完成后返回最终签署文档。

限制与边界

• file只接受 Base64 编码内容或可下载文件 URL 两种形式，二者取其一；文档类型限定为 PDF（DOCX 有独立的/submissions/docx端点，不在本任务范围内）。
• documents和submitters是必填项，缺少任一项请求不成立；template_ids是可选的，仅在需要把已有模板和临时 PDF 组成多文档提交时使用。
• 使用remove_tags: false的场景文档限定为"transparent text tags"（透明文本标签）配合，不要在没有该前提时随意关闭标签移除。
• order的preserved默认值意味着多签署人场景下邮件是顺序发送的，第二方在前一方签署后才收到请求；如果你的流程需要所有人同时收到邮件，必须显式传order: "random"。

完成以上步骤后，一次性的 PDF 签署提交即创建成功：你可以用响应中的embed_src把签署表单嵌入自己的页面，或由签署人通过请求邮件完成签署；全部签署完毕后再通过GET /submissions/{id}/documents拉取最终文件。

【免费下载链接】docusealOpen source DocuSign alternative. Create, fill, and sign digital documents ✍️项目地址: https://gitcode.com/GitHub_Trending/do/docuseal