Back to Details

docuseal-code

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

How References Are Organised

参考文档的组织结构

Reference files live in two subdirectories under 
references/
:
  • references/embed/
     — Embed UI components (signing forms, template builder). Each file is self-contained — load only the ones matching the user's stack.
  • references/api/
     — REST API endpoints and webhooks. One file per endpoint/webhook with parameters, schemas, code examples, and response samples.
参考文件存放在
references/
下的两个子目录中：
  • references/embed/
     — 嵌入UI组件（签署表单、模板构建器）。每个文件都是独立的，只需加载与用户技术栈匹配的文件即可。
  • references/api/
     — REST API端点和Webhooks。每个端点/Webhooks对应一个文件，包含参数、schema、代码示例和响应样本。

Embed UI Components

嵌入UI组件

ComponentTagPurposeJWT
Signing Form
<docuseal-form>
Embed document signing UI into a pageoptional
Form Builder
<docuseal-builder>
Embed a full template/document builderrequired
Each component ships in four frontend implementations: JavaScript / React / Vue / Angular.
组件标签用途JWT
签署表单
<docuseal-form>
将文档签署UI嵌入到页面中可选
表单构建器
<docuseal-builder>
嵌入完整的模板/文档构建器必填
每个组件提供四种前端实现：JavaScript / React / Vue / Angular。

Signing Form (
<docuseal-form>
)

签署表单 (
<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
  • Mobile (Android/iOS/React Native/Flutter via WebView) → references/embed/signing-form-mobile-integration.md
  • 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
  • 移动端（Android/iOS/React Native/Flutter 通过 WebView）→ references/embed/signing-form-mobile-integration.md

Form Builder (
<docuseal-builder>
)

表单构建器 (
<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
After loading the main component reference, follow a link from its 
## Guides
section for step-by-step walkthroughs.
  • 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
加载主组件参考文档后，请查看其
## 指南
部分的链接，获取分步教程。

Cross-cutting

通用配置

  • JWT token generation — Form Builder (Node/TypeScript/Ruby/Python/PHP/Java/C#/Go) → references/embed/form-builder-jwt-token.md
  • JWT token generation — Signing Form completed/preview mode → references/embed/signing-form-completed-preview-jwt-token.md
  • EU Cloud / self-hosted 
    host
    configuration — Signing Form → references/embed/signing-form-hosts.md
  • EU Cloud / self-hosted 
    host
    configuration — Form Builder → references/embed/form-builder-hosts.md
  • Custom CSS theming — Signing Form (dark theme reference) → references/embed/signing-form-custom-css.md
  • Custom CSS theming — Form Builder (dark theme reference) → references/embed/form-builder-custom-css.md
  • 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
  • 欧盟云/自托管环境的
    host
    配置 — 签署表单 → references/embed/signing-form-hosts.md
  • 欧盟云/自托管环境的
    host
    配置 — 表单构建器 → references/embed/form-builder-hosts.md
  • 自定义CSS主题 — 签署表单（深色主题参考）→ references/embed/signing-form-custom-css.md
  • 自定义CSS主题 — 表单构建器（深色主题参考）→ references/embed/form-builder-custom-css.md

Packages

包资源

FrameworkPackageCDN
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 Nativeuses 
react-native-webview
(no native SDK)		—
Flutteruses 
webview_flutter
(no native SDK)		—
框架包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）		—

Common Embed Mistakes

常见嵌入错误

#MistakeFix
1Generating JWT in the browserJWT must be signed on the backend — the API key must never ship to the client. See form-builder-jwt-token.md / signing-form-completed-preview-jwt-token.md.
2Passing the API key as 
data-token
data-token
is a JWT signed with the API key, not the key itself.
3Missing 
host
/
data-host
on EU or self-hosted		Set 
data-host="cdn.docuseal.eu"
for EU Cloud or your own hostname for self-hosted. See signing-form-hosts.md / form-builder-hosts.md.
4Confusing 
/d/{slug}
vs 
/s/{slug}
/d/{slug}
is the template URL (single-party templates). 
/s/{slug}
is an individual signer URL created via the 
/submissions
API.
5Multi-party template via 
data-src
URL		Templates with multiple signing parties must be initiated via the 
/submissions
API — the direct 
/d/{slug}
URL only works for single-party templates.
6camelCase props in HTMLThe web component uses 
data-*
kebab-case attributes. Only React/Vue/Angular use camelCase props.
7Expecting a native mobile SDKNone exists. Embed via WebView — see signing-form-mobile-integration.md.
8Passing 
customCss
as a stylesheet link
customCss
/ 
data-custom-css
takes a CSS string, not a URL. See signing-form-custom-css.md / form-builder-custom-css.md.
#错误修复方案
1在浏览器中生成JWTJWT必须在后端签署 — API密钥绝对不能发送到客户端。请查看form-builder-jwt-token.md / signing-form-completed-preview-jwt-token.md。
2将API密钥作为
data-token
传递
data-token
是用API密钥签署的JWT，而不是密钥本身。
3欧盟或自托管环境中缺少
host
/
data-host
欧盟云环境设置
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中使用驼峰式属性Web组件使用
data-*
短横线命名法属性。只有React/Vue/Angular使用驼峰式属性。
7期望有原生移动SDK不存在原生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。

REST API

REST API

Authentication

身份验证

All requests require an API key passed in the 
X-Auth-Token
header:
X-Auth-Token: YOUR_API_KEY
Get your API key: https://console.docuseal.com/api
所有请求都需要在
X-Auth-Token
请求头中传递API密钥：
X-Auth-Token: YOUR_API_KEY
获取API密钥：https://console.docuseal.com/api

Base URLs

基础URL

EnvironmentBase URL
Global Cloud
https://api.docuseal.com
EU Cloud
https://api.docuseal.eu
Self-hosted
https://docuseal.yourdomain.com/api
环境基础URL
全球云
https://api.docuseal.com
欧盟云
https://api.docuseal.eu
自托管
https://docuseal.yourdomain.com/api

API Client SDKs

API客户端SDK

Official SDK libraries wrap the REST API and handle authentication, request building, and response parsing. Prefer SDKs over raw HTTP when the user's language has one.
LanguagePackageInstall
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 usage examples are included in each endpoint reference file below (marked with "SDK" in the heading).
官方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”）。

Endpoints

端点

Templates
  • GET /templates
    — List all templates
  • GET /templates/{id}
    — Get a template
  • DELETE /templates/{id}
    — Archive a template
  • PUT /templates/{id}
    — Update a template
  • PUT /templates/{id}/documents
    — Update template documents
  • POST /templates/{id}/clone
    — Clone a template
  • POST /templates/html
    — Create a template from HTML
  • POST /templates/docx
    — Create a template from Word DOCX
  • POST /templates/pdf
    — Create a template from PDF
  • POST /templates/merge
    — Merge templates
Submissions
  • GET /submissions
    — List all submissions
  • GET /submissions/{id}
    — Get a submission
  • GET /submissions/{id}/documents
    — Get submission documents
  • DELETE /submissions/{id}
    — Archive a submission
  • POST /submissions/emails
    — Create submissions from emails
  • POST /submissions/pdf
    — Create a submission from PDF
  • POST /submissions/docx
    — Create a submission from DOCX
  • POST /submissions/html
    — Create a submission from HTML
  • POST /submissions
    — Create a submission
Submitters
  • GET /submitters/{id}
    — Get a submitter
  • PUT /submitters/{id}
    — Update a submitter
  • GET /submitters
    — List all submitters
模板
  • 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
    — 从Word DOCX创建模板
  • POST /templates/pdf
    — 从PDF创建模板
  • POST /templates/merge
    — 合并模板
提交记录
  • GET /submissions
    — 列出所有提交记录
  • GET /submissions/{id}
    — 获取单个提交记录
  • GET /submissions/{id}/documents
    — 获取提交记录文档
  • DELETE /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
    — 列出所有提交者

Webhooks

Webhooks

  • Form Webhook
  • Submission Webhook
  • Template Webhook
Configure webhook URL: https://console.docuseal.com/webhooks
  • 表单Webhook
  • 提交记录Webhook
  • 模板Webhook
配置Webhook URL：https://console.docuseal.com/webhooks

Common API Patterns

常见API使用模式

  1. Send a document for signing: create a template (or use existing) → 
    POST /submissions
    with submitter emails → submitters receive signing links
  2. Embed signing in your app: create submission with 
    send_email: false
    → use returned 
    slug
    with 
    <docuseal-form>
    (see Embed UI Components above)
  3. Pre-fill and auto-sign: 
    POST /submissions
    with 
    fields[].default_value
    and 
    completed: true
  4. Track completion: poll 
    GET /submissions/{id}
    or configure webhooks for 
    form.completed
  5. Download signed documents: 
    GET /submissions/{id}/documents
    returns PDF URLs
  1. 发送文档进行签署：创建模板（或使用现有模板）→ 通过
    POST /submissions
    接口传入提交者邮箱 → 提交者收到签署链接
  2. 在应用中嵌入签署功能：创建提交记录时设置
    send_email: false
    → 使用返回的
    slug
    配合
    <docuseal-form>
    组件（见上方嵌入UI组件部分）
  3. 预填充并自动签署：调用
    POST /submissions
    时传入
    fields[].default_value
    和
    completed: true
    参数
  4. 跟踪完成状态：轮询
    GET /submissions/{id}
    接口，或配置
    form.completed
    事件的Webhook
  5. 下载已签署文档：调用
    GET /submissions/{id}/documents
    接口获取PDF文件URL

Quick Decision Flow

快速决策流程

  1. Embedding a component? → Signing Form or Form Builder → load from 
    references/embed/
    .
  2. Making API calls? → Check if the user's language has an SDK (JS/TS, Python, Ruby, PHP) and prefer it over raw HTTP. Load the matching endpoint from 
    references/api/
    .
  3. How-to question about embed? Follow links from the component reference's 
    ## Guides
    section.
  4. Mobile? Load references/embed/signing-form-mobile-integration.md.
  5. JWT needed? Always for Form Builder — load references/embed/form-builder-jwt-token.md. For Signing Form only when using 
    data-token
    (preview/completed mode) — load references/embed/signing-form-completed-preview-jwt-token.md.
  6. Not on 
    docuseal.com
    ?     Load references/embed/signing-form-hosts.md or references/embed/form-builder-hosts.md depending on the component.
  7. Custom theme? Load references/embed/signing-form-custom-css.md or references/embed/form-builder-custom-css.md depending on the component.
  8. CLI commands? Load the sibling 
    docuseal-cli
    skill from this same repo.
  1. 需要嵌入组件？ → 选择签署表单或表单构建器 → 从
    references/embed/
    目录加载对应文档。
  2. 需要调用API？ → 检查用户使用的语言是否有SDK（JS/TS、Python、Ruby、PHP），优先使用SDK而非原生HTTP请求。从
    references/api/
    目录加载对应端点文档。
  3. 有嵌入相关的操作问题？ 查看组件参考文档中
    ## 指南
    部分的链接。
  4. 移动端集成？ 加载references/embed/signing-form-mobile-integration.md文档。
  5. 需要JWT？ 表单构建器始终需要JWT → 加载references/embed/form-builder-jwt-token.md文档。签署表单仅在使用
    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. 需要CLI命令？ 加载同一仓库中的
    docuseal-cli
    技能文档。