用途:实现 Documenso 的文档创建与收件人管理工作流,适用于创建文档、管理收件人、添加签名字段和控制签署顺序等场景,同时覆盖 SDK 与 v1 REST API 的文档中心操作。
主要能力:创建文档外壳并上传 PDF;添加 SIGNER、VIEWER、APPROVER、CC 等收件人角色;通过 signingOrder 控制签署顺序(数字小者先执行);添加 SIGNATURE、DATE、NAME、TEXT 等字段,字段坐标使用百分比定位(X、Y 轴均为 0-100,原点为页面左上角);查询与筛选文档,支持分页、排序及获取单文档详情;文档状态流转为 DRAFT→PENDING→COMPLETED,另有 REJECTED、CANCELLED;仅 DRAFT 状态文档可修改。
使用方式:需先完成 documenso-install-auth 设置并了解 documenso-sdk-patterns,准备待签署 PDF。使用 @documenso/sdk-typescript 初始化客户端(apiKey 取自 DOCUMENSO_API_KEY),依次调用 documents.createV0、documents.setFileV0、documentsRecipients.createV0、documentsFields.createV0,最后调用 documents.sendV0 发送。也可通过 v1 REST API 以 FormData 提交 title 与 file 创建文档。
限制与错误处理:文档不存在返回 404;同一文档重复邮箱返回 400;字段位置超出 0-100 返回 400;已发送文档不可修改返回 400;文件过大返回 413,需压缩 PDF(具体上限因套餐而异)。建议使用合成测试文档与测试收件人验证角色、过期、认证与回调行为,验证后归档;若角色或收件人行为有误,应禁用工作流并修正后再推广,不要用真实签署人替代测试。模板工作流与直接签署链接见 documenso-core-workflow-b。