# @docuseal/api 中文文档

规范地址：https://npmcn.com/package/%40docuseal/api/

版本：1\.0\.25
npm 元数据更新时间：2026-08-24T15:20:43.115Z
中文译文更新时间：2026-11-12T14:22:25.477Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40docuseal/api
原文对照：https://npmcn.com/package/%40docuseal/api/?lang=original
项目主页：https://www.docuseal.com/docs/api?lang=javascript
源码仓库：https://github.com/docusealco/docuseal-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：110 kB，20 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2024-12-28T14:28:36.235Z
- 最新版本发布：2026-08-24T15:20:42.889Z
- 近 30 天下载量：137956（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 5 个）

## 中文简介

用于 DocuSeal API 的 JavaScript / TypeScript 库

## 安装

```sh
npm install @docuseal/api
```

也可以使用：`pnpm add @docuseal/api`、`yarn add @docuseal/api`、`bun add @docuseal/api`

## README

# DocuSeal JavaScript / 打字符

DocuSeal JavaScript / Typescript 库提供与 DocuSeal API 的无缝集成,允许开发者与 DocuSeal 的电子签名和文档管理功能直接在 JS/TS 应用程序内互动. 这个库旨在简化API互动,提供高效执行的工具.

## 文档

详细文件见 [DocuSel API 文档](https://www.docuseal.com/docs/api?lang=javascript)。 。 。 .

## 所需资源

节点14或以上.

## 安装

要安装库, 请运行 :

```sh
npm install @docuseal/api
```

或:

```sh
yarn add @docuseal/api
```

## 使用量

### 配置

根据您的部署设置您的 DocuSeal API 密钥 。 从合适的位置获取您的 API 密钥 :

#### 全球云

全球云的 API 密钥可以从您获取 [全球 DocuSel 控制台](https://console.docuseal.com/api)。 。 。 .

```javascript
const docuseal = require("@docuseal/api");

docuseal.configure({ key: "your_api_key_here" });
```

或启动新的 api 客户端对象 :

```javascript
const { DocusealApi } = require("@docuseal/api");

const docuseal = new DocusealApi({ key: "your_api_key_here" });
```

#### 欧盟云

欧盟云的 API 密钥可以从您获取 [欧盟多克赛尔控制台](https://console.docuseal.eu/api)。 。 。 .

```javascript
const docuseal = require("@docuseal/api");

docuseal.configure({
  key: "your_api_key_here",
  url: "https://api.docuseal.eu"
});
```

#### 内容

对于配置设备,API密钥可以从您已部署应用程序的API设置页面中取出,例如, [https://yourdocusealapp.com/ settings/api 页面存档备份,存于互联网档案馆](https://yourdocusealapp.com/settings/api)。 。 。 .

```javascript
const docuseal = require("@docuseal/api");

docuseal.configure({
  key: "your_api_key_here",
  url: "https://yourdocusealapp.com/api"
});
```

## API 方法

### 附录(段落)

[文档](https://www.docuseal.com/docs/api?lang=javascript#list-all-submissions)

提供检索现有提交材料清单的能力.

```javascript
const { data, pagination } = await docuseal.listSubmissions({ limit: 10 });
```

### 获取子任务( id)

[文档](https://www.docuseal.com/docs/api?lang=javascript#get-a-submission)

提供获取提交材料信息的功能.

```javascript
const submission = await docuseal.getSubmission(1001);
```

### 获取子任务文件( id)

[文档](https://www.docuseal.com/docs/api?lang=javascript#get-submission-documents)

此端点返回已部分填充的文档列表以供提交 。 如果划界案已经完成,则交回最后签字文件.

```javascript
const submission = await docuseal.getSubmissionDocuments(1001);
```

### 创建子任务( 数据)

[文档](https://www.docuseal.com/docs/api?lang=javascript#create-a-submission)

此 API 端点允许您为文档模板创建签名请求( 提交) 并将其发送给指定的提交者( 签名人 ) .

**相关指南:**  
[通过 API 发送文档签名](https://www.docuseal.com/guides/send-documents-for-signature-via-api) [使用 API 预填入 PDF 文档窗体字段](https://www.docuseal.com/guides/pre-fill-pdf-document-form-fields-with-api)

```javascript
const submission = await docuseal.createSubmission({
  template_id: 1000001,
  send_email: true,
  submitters: [
    {
      role: "First Party",
      email: "john.doe@example.com"
    }
  ]
});
```

### 创建来自Pdf( 数据) 的子任务

[文档](https://www.docuseal.com/docs/api?lang=javascript#create-a-submission-from-pdf)

提供从 PDF 创建一次性提交请求的功能。 使用 `{{Field Name;role=Signer1;type=date}}` 在文档中定义可填充字段的文本标记。 见 [https://www.docuseal.com/examples/fieldtags.pdf (中文(简体) )](https://www.docuseal.com/examples/fieldtags.pdf) 用于更多的文本标签格式。 或指定文档字段的确切像素坐标 `fields` 一、导 言.

**相关指南:**  
[使用嵌入式文字字段标记来创建可填充表单](https://www.docuseal.com/guides/use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form)

```javascript
const submission = await docuseal.createSubmissionFromPdf({
  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"
    }
  ]
});
```

### 创建来自 Docx( 数据) 的子任务

[文档](https://www.docuseal.com/docs/api?lang=javascript#create-a-submission-from-docx)

提供功能,从DOCX文件创建一个带有动态内容变量的一次性提交请求. 使用 `[[variable_name]]` 用于定义文档中动态内容变量的文本标记。 见 [https://www.docuseal.com/examples/demo template.docx 页面存档备份,存于互联网档案馆](https://www.docuseal.com/examples/demo_template.docx) 用于特定的文本变量语法,包括动态内容表和列表。 你也可以使用这个 `{{signature}}` 字段语法来定义可填充字段,如PDF.

**相关指南:**  
[在 DOCX 中使用动态内容变量创建个性化文档](https://www.docuseal.com/guides/use-dynamic-content-variables-in-docx-to-create-personalized-documents)

```javascript
const submission = await docuseal.createSubmissionFromDocx({
  name: "Test Submission Document",
  variables: {
    variable_name: "value"
  },
  documents: [
    {
      name: "string",
      file: "base64"
    }
  ],
  submitters: [
    {
      role: "First Party",
      email: "john.doe@example.com"
    }
  ]
});
```

### 创建来自Html( 数据) 的子任务

[文档](https://www.docuseal.com/docs/api?lang=javascript#create-a-submission-from-html)

此 API 端点允许您使用所提供的 HTML 内容创建一次性提交请求文件, 并使用特殊字段标记作为可填充和可签名的形式 .

**相关指南:**  
[用 HTML 创建 PDF 文档可填充表单](https://www.docuseal.com/guides/create-pdf-document-fillable-form-with-html-api)

```javascript
const submission = await docuseal.createSubmissionFromHtml({
  name: "Test Submission Document",
  documents: [
    {
      name: "Test Document",
      html: `<p>Lorem Ipsum is simply dummy text of the
<text-field
  name="Industry"
  role="First Party"
  required="false"
  style="width: 80px; height: 16px; display: inline-block; margin-bottom: -4px">
</text-field>
and typesetting industry</p>
`
    }
  ],
  submitters: [
    {
      role: "First Party",
      email: "john.doe@example.com"
    }
  ]
});
```

### 更新子任务( id, 数据)

[文档](https://www.docuseal.com/docs/api?lang=javascript#update-a-submission)

允许您更新一个提交文件:更改其名称、到期日期并存档或解存档 .

```javascript
const submission = await docuseal.updateSubmission(1001, {
  name: "New Submission Name",
  expire_at: "2024-09-01 12:00:00 UTC",
  archived: true
});
```

### 归档子任务( id)

[文档](https://www.docuseal.com/docs/api?lang=javascript#archive-a-submission)

允许您归档提交文件 .

```javascript
await docuseal.archiveSubmission(1001);
```

### 列表附录( 段落)

[文档](https://www.docuseal.com/docs/api?lang=javascript#list-all-submitters)

提供检索提交者名单的能力.

```javascript
const { data, pagination } = await docuseal.listSubmitters({ limit: 10 });
```

### 获取Submitter( id)

[文档](https://www.docuseal.com/docs/api?lang=javascript#get-a-submitter)

提供了检索提交者信息的功能,以及提交者的文档和字段值.

```javascript
const submitter = await docuseal.getSubmitter(500001);
```

### 更新Submitter( id, 数据)

[文档](https://www.docuseal.com/docs/api?lang=javascript#update-a-submitter)

允许您更新提交器细节, 预填或更新字段值并重新发送邮件 .

**相关指南:**  
[通过 API 自动签名文档](https://www.docuseal.com/guides/pre-fill-pdf-document-form-fields-with-api#automatically-sign-documents-via-api)

```javascript
const submitter = await docuseal.updateSubmitter(500001, {
  email: "john.doe@example.com",
  fields: [
    {
      name: "First Name",
      default_value: "Acme"
    }
  ]
});
```

### 列表 模板( 段落)

[文档](https://www.docuseal.com/docs/api?lang=javascript#list-all-templates)

提供检索可用文档模板清单的能力.

```javascript
const { data, pagination } = await docuseal.listTemplates({ limit: 10 });
```

### 获取模板( id)

[文档](https://www.docuseal.com/docs/api?lang=javascript#get-a-template)

提供获取文档模板信息的功能.

```javascript
const template = await docuseal.getTemplate(1000001);
```

### 从 Pdf( 数据) 创建模板

[文档](https://www.docuseal.com/docs/api?lang=javascript#create-a-template-from-pdf)

提供为 PDF 文件创建可填充文档模板的功能。 使用 `{{Field Name;role=Signer1;type=date}}` 在文档中定义可填充字段的文本标记。 见 [https://www.docuseal.com/examples/fieldtags.pdf (中文(简体) )](https://www.docuseal.com/examples/fieldtags.pdf) 用于更多的文本标签格式。 或指定文档字段的确切像素坐标 `fields` 一、导 言.

**相关指南:**  
[使用嵌入式文字字段标记来创建可填充表单](https://www.docuseal.com/guides/use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form)

```javascript
const template = await docuseal.createTemplateFromPdf({
  name: "Test PDF",
  documents: [
    {
      name: "string",
      file: "base64",
      fields: [
        {
          name: "string",
          areas: [
            {
              x: 0,
              y: 0,
              w: 0,
              h: 0,
              page: 1
            }
          ]
        }
      ]
    }
  ]
});
```

### 从 Docx( 数据) 创建模板

[文档](https://www.docuseal.com/docs/api?lang=javascript#create-a-template-from-word-docx)

提供为已存在的Microsoft Word文档创建可填充文档模板的功能. 使用 `{{Field Name;role=Signer1;type=date}}` 在文档中定义可填充字段的文本标记。 见 [https://www.docuseal.com/examples/fieldtags.docx 页面存档备份,存于互联网档案馆](https://www.docuseal.com/examples/fieldtags.docx) 用于更多的文本标签格式。 或指定文档字段的确切像素坐标 `fields` 一、导 言.

**相关指南:**  
[使用嵌入式文字字段标记来创建可填充表单](https://www.docuseal.com/guides/use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form)

```javascript
const template = await docuseal.createTemplateFromDocx({
  name: "Test DOCX",
  documents: [
    {
      name: "string",
      file: "base64"
    }
  ]
});
```

### 从Html( 数据) 创建模板

[文档](https://www.docuseal.com/docs/api?lang=javascript#create-a-template-from-html)

通过使用提供的 HTML 内容,同时包含预先定义的字段,提供无缝生成 PDF 文档模板的功能.

**相关指南:**  
[用 HTML 创建 PDF 文档可填充表单](https://www.docuseal.com/guides/create-pdf-document-fillable-form-with-html-api)

```javascript
const template = await docuseal.createTemplateFromHtml({
  html: `<p>Lorem Ipsum is simply dummy text of the
<text-field
  name="Industry"
  role="First Party"
  required="false"
  style="width: 80px; height: 16px; display: inline-block; margin-bottom: -4px">
</text-field>
and typesetting industry</p>
`,
  name: "Test Template"
});
```

### 克隆模板( id, 数据)

[文档](https://www.docuseal.com/docs/api?lang=javascript#clone-a-template)

允许您将已有模板复制到新模板中.

```javascript
const template = await docuseal.cloneTemplate(1000001, {
  name: "Cloned Template"
});
```

### 合并模板( 数据)

[文档](https://www.docuseal.com/docs/api?lang=javascript#merge-templates)

允许您将多个模板与文档和字段合并为新的合并模板.

```javascript
const template = await docuseal.mergeTemplates({
  template_ids: [
    321,
    432
  ],
  name: "Merged Template"
});
```

### 更新 Template( id, 数据)

[文档](https://www.docuseal.com/docs/api?lang=javascript#update-a-template)

提供将文档模板移动到不同文件夹并更新模板名称的功能.

```javascript
const template = await docuseal.updateTemplate(1000001, {
  name: "New Document Name",
  folder_name: "New Folder"
});
```

### 更新模板文件( id, 数据)

[文档](https://www.docuseal.com/docs/api?lang=javascript#update-template-documents)

允许您使用提供的 PDF/DOCX 文件或 HTML 内容在模板中添加、删除或替换文档.

```javascript
const template = await docuseal.updateTemplateDocuments(1000001, {
  documents: [
    {
      file: "string"
    }
  ]
});
```

### 归档Template( id)

[文档](https://www.docuseal.com/docs/api?lang=javascript#archive-a-template)

允许您归档文档模板.

```javascript
await docuseal.archiveTemplate(1000001);
```

### 配置超时

设置超时以避免挂起请求 :

```javascript
const { DocusealApi } = require('@docuseal/api')

const docuseal = new DocusealApi({
  key: 'your_api_key_here',
  openTimeout: 30000
});
```

## 支助

对于特性请求或错误报告,请访问 [GitHub 问题页面](https://github.com/docusealco/docuseal-js/issues)。 。 。 .

## 许可证

图书馆可按以下规定作为开放源码提供: [MIT 许可证](https://opensource.org/licenses/MIT)。 。 。 .

## 常见问题

### @docuseal/api 是什么？

用于 DocuSeal API 的 JavaScript / TypeScript 库

### 如何安装 @docuseal/api？

在项目目录运行 npm install @docuseal/api，或使用 pnpm add / yarn add / bun add。

### @docuseal/api 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @docuseal/api 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @docuseal/api 可以商用吗？

@docuseal/api 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @docuseal/api 的下载量有多少？

根据 npm 官方下载统计，@docuseal/api 在 2026/10/13 – 2026/11/11 这 30 天内被下载 137,956 次，日均约 4,599 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @docuseal/api 还在维护吗？

最新版本 1\.0\.25 发布于 2026/08/24（2 个月前）；至今共发布 24 个版本，其中过去 12 个月发布了 5 个；首次发布于 2024/12/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。