docuseal-code

参考资料的组织方式

参考文件位于 references/ 下的两个子目录中：

• references/embed/ — 嵌入式 UI 组件（签署表单、模板构建器）。每个文件均为独立文档——只加载与用户技术栈匹配的文件。
• references/api/ — REST API 端点和 Webhook。每个端点或 Webhook 对应一个文件，其中包含参数、架构、代码示例和响应示例。

嵌入式 UI 组件

组件	标签	用途	JWT
签署表单	<docuseal-form>	在页面中嵌入文档签署 UI	可选
表单构建器	<docuseal-builder>	嵌入完整的模板／文档构建器	必需

每个组件均提供四种前端实现：JavaScript / React / Vue / Angular。

签署表单（<docuseal-form>）

• JavaScript / HTML → references/embed/signing-form-js.md
• React → references/embed/signing-form-react.md
• Vue → references/embed/signing-form-vue.md
• Angular → references/embed/signing-form-angular.md
• 移动端（通过 WebView 支持 Android/iOS/React Native/Flutter）→ references/embed/signing-form-mobile-integration.md

表单构建器（<docuseal-builder>）

• JavaScript / HTML → references/embed/form-builder-js.md
• React → references/embed/form-builder-react.md
• Vue → references/embed/form-builder-vue.md
• Angular → references/embed/form-builder-angular.md

加载主要组件参考资料后，请点击其 ## Guides 部分中的链接，查看分步指南。

通用内容

• JWT 令牌生成 — 表单构建器（Node/TypeScript/Ruby/Python/PHP/Java/C#/Go）→ references/embed/form-builder-jwt-token.md
• JWT 令牌生成 — 签署表单的已完成／预览模式 → references/embed/signing-form-completed-preview-jwt-token.md
• EU Cloud / 可自托管的 host 配置 — 签署表单 → references/embed/signing-form-hosts.md
• EU Cloud / 可自托管的 host 配置 — 表单构建器 → references/embed/form-builder-hosts.md
• 自定义 CSS 主题 — 签署表单（深色主题参考）→ references/embed/signing-form-custom-css.md
• 自定义 CSS 主题 — 表单构建器（深色主题参考）→ references/embed/form-builder-custom-css.md
• 签署表单安全建议 → references/embed/signing-form-security-recommendations.md
• 表单构建器安全建议 → references/embed/form-builder-security-recommendations.md

软件包

框架	软件包	CDN
JavaScript	—	https://cdn.docuseal.com/js/form.js, https://cdn.docuseal.com/js/builder.js
React	@docuseal/react	—
Vue	@docuseal/vue	—
Angular	@docuseal/angular	—
React Native	使用 react-native-webview（无原生 SDK）	—
Flutter	使用 webview_flutter（无原生 SDK）	—

常见嵌入错误

#	错误	修正方法
1	在浏览器中生成 JWT	JWT 必须在后端签名 — API 密钥绝不能发送到客户端。参见 form-builder-jwt-token.md / signing-form-completed-preview-jwt-token.md。
2	将 API 密钥作为 data-token 传递	data-token 是一个使用 API 密钥签名的 JWT，而不是密钥本身。
3	在 EU 或可自托管环境中缺少 host/data-host	EU Cloud 请设置 data-host="cdn.docuseal.eu"；可自托管环境请设置为您自己的主机名。参见 signing-form-hosts.md / form-builder-hosts.md。
4	混淆 /d/{slug} 和 /s/{slug}	/d/{slug} 是模板 URL（用于单方模板）。/s/{slug} 是通过 /submissions API 创建的单个签署人 URL。
5	通过 data-src URL 使用多方模板	多方签署模板必须通过 /submissions API 启动 — 直接使用 /d/{slug} URL 仅适用于单方模板。
6	在 HTML 中使用 camelCase 属性	Web Component 使用 data-* kebab-case 属性。只有 React/Vue/Angular 使用 camelCase 属性。
7	期待提供原生移动端 SDK	目前没有。请通过 WebView 嵌入 — 参见 signing-form-mobile-integration.md。
8	将 customCss 作为样式表链接传递	customCss / data-custom-css 接受 CSS 字符串，而不是 URL。参见 signing-form-custom-css.md / form-builder-custom-css.md。
9	通过可枚举的 URL 嵌入签署表单	DocuSeal 的 slug 是随机的，但像 https://yourapp.com/contracts/123/sign 这样的嵌入页面会让攻击者可以遍历整数 ID，访问其他用户的签署表单。请将 DocuSeal slug 或 UUID 放入 URL，或要求用户通过嵌入页面的身份验证。参见 signing-form-security-recommendations.md。
10	在没有身份验证的情况下公开 Form Builder	渲染 <docuseal-builder> 的页面必须受您应用的身份验证保护。签发 JWT 的端点必须验证发起请求的用户拥有 external_id 引用的模板。否则，任何已登录用户都可以编辑任何模板。参见 form-builder-security-recommendations.md。
11	根据客户端的 completed 事件执行操作	浏览器事件可以伪造。请根据经过 HMAC 验证的 form.completed Webhook 驱动状态变更，而不是依赖 <docuseal-form> JavaScript 回调。参见 signing-form-security-recommendations.md。

REST API

身份验证

所有请求都必须在 X-Auth-Token 标头中传递 API 密钥：

X-Auth-Token: YOUR_API_KEY

获取您的 API 密钥：https://console.docuseal.com/api

基础 URL

环境	基础 URL
Global Cloud	https://api.docuseal.com
EU Cloud	https://api.docuseal.eu
可自托管	https://docuseal.yourdomain.com/api

API 客户端 SDK

官方 SDK 库封装了 REST API，并处理身份验证、请求构建和响应解析。如果用户使用的语言有对应 SDK，请优先使用 SDK，而不是原始 HTTP。

语言	包	安装
JavaScript / TypeScript	@docuseal/api	npm install @docuseal/api
Python	docuseal	pip install docuseal
Ruby	docuseal	gem install docuseal
PHP	docusealco/docuseal	composer require docusealco/docuseal

每个端点参考文件中都包含 SDK 使用示例（标题中标有 “SDK”）。

端点

模板

• GET /templates — 列出所有模板
• GET /templates/{id} — 获取模板
• DELETE /templates/{id} — 归档模板
• PUT /templates/{id} — 更新模板
• PUT /templates/{id}/documents — 更新模板文档
• POST /templates/{id}/clone — 克隆模板
• POST /templates/html — 根据 HTML 创建模板
• POST /templates/docx — 根据 DOCX 创建模板
• POST /templates/pdf — 根据 PDF 创建模板
• POST /templates/merge — 合并模板

提交

• GET /submissions — 列出所有提交
• GET /submissions/{id} — 获取提交
• GET /submissions/{id}/documents — 获取提交文档
• DELETE /submissions/{id} — 归档提交
• PUT /submissions/{id} — 更新提交
• POST /submissions/emails — 根据邮件创建提交
• POST /submissions/pdf — 根据 PDF 创建提交
• POST /submissions/docx — 根据 DOCX 创建提交
• POST /submissions/html — 根据 HTML 创建提交
• POST /submissions — 创建提交

提交者

• GET /submitters/{id} — 获取提交者
• PUT /submitters/{id} — 更新提交者
• GET /submitters — 列出所有提交者

Webhook

• 表单 Webhook
• 提交 Webhook
• 模板 Webhook

配置 Webhook URL：https://console.docuseal.com/webhooks

设置、密钥、HMAC 签名验证和本地开发 → references/api/use-webhooks.md

常见 API 模式

1. 发送文档以供签署： 创建模板（或使用现有模板）→ 使用提交者邮箱调用 POST /submissions → 提交者会收到签署链接
2. 在应用中嵌入签署功能： 创建提交时设置 send_email: false → 将返回的 slug 与 <docuseal-form> 配合使用（参见上文的嵌入式 UI 组件）
3. 预填并自动签署： 调用 POST /submissions 并设置 fields[].default_value 和 completed: true
4. 跟踪完成状态： 轮询 GET /submissions/{id}，或配置 Webhook 监听 form.completed
5. 下载已签署的文档： GET /submissions/{id}/documents 会返回 PDF URL

快速决策流程

1. 嵌入组件？ → Signing Form 或 Form Builder → 从 references/embed/ 加载。
2. 调用 API？ → 检查用户使用的语言是否有 SDK（JS/TS、Python、Ruby、PHP），并优先使用 SDK，而不是原始 HTTP。加载 references/api/ 中对应的端点。
3. 关于嵌入的操作指南问题？ 遵循组件参考文档 ## Guides 部分中的链接。
4. 移动端？ 加载 references/embed/signing-form-mobile-integration.md。
5. 需要 JWT？ Form Builder 始终需要——加载 references/embed/form-builder-jwt-token.md。Signing Form 仅在使用 data-token（预览/完成模式）时需要——加载 references/embed/signing-form-completed-preview-jwt-token.md。
6. 不在 docuseal.com 上？ 根据组件加载 references/embed/signing-form-hosts.md 或 references/embed/form-builder-hosts.md。
7. 自定义主题？ 根据组件加载 references/embed/signing-form-custom-css.md 或 references/embed/form-builder-custom-css.md。
8. 身份验证、URL 处理、Webhook 验证或任何涉及安全的嵌入操作？ 根据组件加载 references/embed/signing-form-security-recommendations.md 或 references/embed/form-builder-security-recommendations.md。
9. CLI 命令？ 从同一仓库加载同级的 docuseal-cli 技能。