开始使用
使用 API
使用WOPI
附加 API
更多信息

转换 API

对于与 文档转换服务 的交互，使用 POST 请求。 请求参数在请求正文中以 JSON。 格式输入请求被发送到 https://documentserver/ConvertService.ashx, 其中 documentserver 是安装了ONLYOFFICE 文档服务器的服务器的名称

在 ONLYOFFICE 文档服务器4.2之前的版本中，使用了GET请求,请求参数在 QueryString 中。
参数 描述 类型 出现
定义转换请求类型：异步与否。
支持的值：
  • true
  • false
使用异步请求类型时，响应立即形成。 在这种情况下，要获得结果，必须在转换完成之前发送不更改参数的请求。 默认值为 false。 		boolean 可选的
如果是同步转换，文件转换时间比较长，可能会出现web请求超时错误。 虽然最终可以完成转换，但只有用相同的key再次发送请求才能得到结果。
定义从 csv 或 txt 格式转换时的文件编码。
主要支持的值：
  • 932 - 日语（Shift-JIS），
  • 950 - 繁体中文 (Big5),
  • 1250 - 中欧（Windows），
  • 1251 - 西里尔字母 (Windows),
  • 65001 - Unicode (UTF-8)。
您可以在 此文件中找到所有支持的值。 		integer 可选的
定义从 csv 格式转换时用于分隔值的定界符。
支持的值：
  • 0 - 没有定界符，
  • 1 - 制表符，
  • 2 - 分号，
  • 3 - 冒号，
  • 4 - 逗号，
  • 5 - 空格。
 integer 可选的
定义文档布局，该布局指定参数，用于说明将表单打印为 pdf 文档还是图像。 对象 可选的
定义是否将绘制占位符。 boolean 可选的
定义表单是否突出显示。 boolean 可选的
定义打印模式是打开还是关闭。此参数仅用于将 docx/docxf 转换为 pdf。 如果此参数等于 true，则使用 drawPlaceHolders 和 drawFormHighlight 标志，如上所述。 如果此参数为 false，则 drawFormHighlight 标志不起作用，并且 drawPlaceHolders 参数允许将表单保存为 pdf 格式。 默认值为 false。 boolean 可选的
定义从 pdf, xps, oxps转换时的文档渲染器。 对象 可选的
定义可以具有以下值的渲染模式：
  • blockChar - 所有文本都由单个字符转换。 每个字符都在自己的框中（如文本框），
  • blockLine - 所有文本都由单独的行转换。 每个文本行都在自己的框中。行可以在同一个块内组合，
  • plainLine - 所有文本都转换为纯文本。 但每一行都是一个单独的段落，
  • plainParagraph - 所有文本都转换为纯文本。 行被组合成段落。
默认值为 plainLine。 		string 可选的
定义要转换的文档文件的类型。 string 必需的
定义文档标识符,用于明确标识文档文件。 string 必需的
定义生成的转换文档类型。 从 7.0 版开始，可以指定文件格式而不是扩展名。 当我们事先不知道需要什么扩展时使用它们：
  • ooxml - 定义文件将被转换为 docx, docm, xlsx, xlsm, pptx 或 pptm。 例如，将 doc 文件转换为 OOXML 格式时，如果该文件包含宏，则生成的文件可以是 docx 或 docm（xls 和 ppt 也一样）。 它也适用于将 XML 文件转换为 OOXML 格式（docx, xlsx 或 pptx ，具体取决于内容）；
  • odf - 定义文件将被转换为 odt, ods 或 odp。 例如，它用于将 XML 文件转换为 ODF 格式（odt, ods 或 odp，具体取决于内容）。
string 必需的
如果文档文件受密码保护，则定义其密码。 string 可选的
定义从 电子表格 格式转换为 pdf时货币、日期和时间的默认显示格式。 使用四个字母（en-US、 fr-FR等）语言代码设置。 默认值为 en-US。 string 可选的
定义将电子表格转换为 pdf 的设置。 对象 可选的
请注意，将电子表格转换为pdf或图像格式后，一次可以返回的最大页数不超过1500。
设置转换区域的高度，以页数为单位。默认值为0。 默认值为 0。 integer 可选的
设置转换区域的宽度，以页数为单位。 默认值为0。默认值为 0。 integer 可选的
允许在输出 PDF 文件中包含或不包含网格线。 默认值为 false。 boolean 可选的
允许在输出 PDF 文件中包含或不包含标题。 默认值为 false。 boolean 可选的
确定是否忽略为电子表格文件选择的打印区域。 默认值为 true。 boolean 可选的
设置输出 PDF 文件的边距。 对象 可选的
设置输出 PDF 文件的下边距。默认值为19.1mm。 默认值为 19.1mm。 string 可选的
设置输出 PDF 文件的左边距。 默认值为 17.8mm。 string 可选的
设置输出 PDF 文件的右边距。 默认值为 17.8mm。 string 可选的
设置输出 PDF 文件的上边距。 默认值为 19.1mm。 string 可选的
设置输出 PDF 文件的方向。 可以是 横向打印格式，也可以是 纵向打印格式。默认值为 纵向打印格式。 string 可选的
设置输出 PDF 文件的页面大小。 对象 可选的
设置输出 PDF 文件的页面高度。 默认值为 297mm。 string 可选的
设置输出 PDF 文件的页面宽度。 默认值为 210mm。 string 可选的
允许设置输出 PDF 文件的缩放比例。 默认值为 100。 integer 可选的
在将图像格式（bmp, gif, jpg, png）指定为 outputtype时，定义缩略图的设置。 对象 可选的
定义使图像适合指定的高度和宽度的模式。 支持的值：
  • 0 - 拉伸文件以适应高度和宽度，
  • 1 - 保持图像的外观，
  • 2 - 在这种情况下，不使用宽度和高度设置。 取而代之的是，页面的米制尺寸被转换为 96dpi 的像素。 例如，A4 (210x297mm) 页面将变成尺寸为 794x1123pix 的图片。
默认值为 2。 		integer 可选的
定义是否应仅为首页或所有文档页面生成缩略图。 如果为 false，将创建包含所有页面缩略图的zip存档。 默认值为 false。 boolean 可选的
以像素为单位定义缩略图高度。 默认值为 100。 integer 可选的
以像素为单位定义缩略图宽度。 默认值为 100。 integer 可选的
定义转换后的文件名。 string 可选的
以 令牌的形式定义添加到 文档服务器 配置的加密签名。 string 配置要求
定义要转换的文档的绝对 URL。 使用本地链接时请务必添加 token。 否则会出现错误。 string 必需的
定义一个 JSON 对象，其中包含水印的属性 ,在转换过程中将其插入到 pdf 和图像文件中。 object 可选的
定义水印透明度。 float 可选的
定义形状类型，指定当前水印的预设形状几何形状。 string 可选的
定义以毫米为单位测量的水印宽度。 number 可选的
定义以毫米为单位测量的水印高度。 number 可选的
定义水印旋转角度（以度为单位）。 number 可选的
定义水印形状中的文本边距（以毫米为单位）。 数值数组 可选的
以 RGB 格式定义水印填充颜色，或图像的 URL（base64 支持：data:image/png;...）。 空数组[]表示水印没有填充。 数值数组 | string 可选的
定义以毫米为单位测量的水印描边宽度。 number 可选的
以 RGB 格式定义水印描边颜色。 空数组[]表示水印笔划没有填充。 数值数组 可选的
定义水印形状中的垂直文本对齐方式：0 - 底部、1 - 中心、4 - 顶部。 number 可选的
使用当前水印中的段落及其属性定义数组。 对象数组 可选的
定义当前段落中的水平文本对齐方式：0 - 右、1 - 左、2 - 居中、3 - 两端对齐。 number 可选的
以 RGB 格式定义段落突出显示。 空数组[]表示该段落不突出显示。 数值数组 可选的
定义当前段落中的文本行间距。 number 可选的
定义包含当前段落中的runs及其属性的数组。 对象数组 可选的
watermark.paragraphs.runs.text 定义run文本。 string 可选的
以 RGB 格式定义文本突出显示。 空数组[]表示文本不突出显示。 数值数组 可选的
定义文本字体系列。 string 可选的
定义以磅 (pt) 为单位测量的文本字体大小。 string 可选的
定义当前文本是否显示为粗体。 boolean 可选的
定义当前文本是否显示为斜体。 boolean 可选的
定义当前文本是否显示为删除线。 boolean 可选的
定义当前文本是否显示下划线。 boolean 可选的
* - 在下表中，您可以看到将文档转换为最知名的文件格式的可能性，其中 输入格式 列对应于 filetype 参数的值， 输出格式 列对应于 outputtype 参数的值。

文本文档文件格式

输入格式 输出格式
bmp docm docx docxf dotm dotx epub fb2 gif html jpg odt ott pdf pdfa png rtf txt
djvu
doc
docm
docx
docxf
dot
dotm
dotx
epub
fb2
fodt
htm
html
mht
mhtml
odt
ott
oxps
pdf
rtf
stw
sxw
txt
wps
wpt
xml
xps
输入格式 输出格式
bmp csv gif jpg ods ots pdf pdfa png xlsm xlsx xltm xltx
csv
et
ett
fods
ods
ots
sxc
xls
xlsb
xlsm
xlsx
xlt
xltm
xltx
xml
输入格式 输出格式
bmp gif jpg odp otp pdf pdfa png potm potx ppsm ppsx pptm pptx
dps
dpt
fodp
odp
otp
pot
potm
potx
pps
ppsm
ppsx
ppt
pptm
pptx
sxi 
{
    "async": false,
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "pdf",
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-document.docx"
}

其中 example.com 是安装了 文档管理器 和 文档存储服务 的服务器的名称。 有关文档服务器服务客户机-服务器交互的更多信息，请参阅 它是如何运作的 部分。 

{
    "async": false,
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "pdf",
    "password": "123456",
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-document.docx"
}

其中 example.com 是安装了 文档管理器 和 文档存储服务 的服务器的名称。 有关文档服务器服务客户机-服务器交互的更多信息，请参阅 它是如何运作的 部分。 

{
    "async": false,
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "pdf",
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-document.docx",
    "watermark": {
        "align": 1,
        "fill": [255, 0, 0],
        "height": 100,
        "margins": [ 10, 10, 10, 10 ],
        "paragraphs": [
            {
                "align": 2,
                "fill": [255, 0, 0],
                "linespacing": 1,
                "runs": [
                    {
                        "bold": true,
                        "italic": false,
                        "fill": [0, 0, 0],
                        "font-family": "Arial",
                        "font-size": 40,
                        "strikeout": false,
                        "text": "Watermark",
                        "underline": false
                    },
                    {
                        "text": "<%br%>"
                    }
                ]
            }
        ],
        "rotate": -45,
        "transparent": 0.3,
        "type": "rect",
        "stroke-width": 1,
        "stroke": [0, 0, 255],
        "width": 100
    }
}

example.com 是安装文档管理器和文档存储服务的服务器的名称。 请参阅工作原理部分，了解有关文档服务器服务客户端与服务器交互的更多信息。 

{
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "png",
    "thumbnail": {
        "aspect": 0,
        "first": true,
        "height": 150,
        "width": 100
    },
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-document.docx"
}

其中 example.com 是安装了 文档管理器 和 文档存储服务 的服务器的名称。 有关文档服务器服务客户机-服务器交互的更多信息，请参阅 它是如何运作的 部分。 

{
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "pdf",
    "region": "en-US",
    "spreadsheetLayout": {
        "ignorePrintArea": true,
        "orientation": "portrait",
        "fitToWidth": 0,
        "fitToHeight": 0,
        "scale": 100,
        "headings": false,
        "gridLines": false,
        "pageSize": {
        "width": "210mm",
        "height": "297mm"
        },
        "margins": {
        "left": "17.8mm",
            "right": "17.8mm",
            "top": "19.1mm",
            "bottom": "19.1mm"
        }
    },
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-spreadsheet.xlsx"
}

其中 example.com 是安装了 文档管理器 和 文档存储服务 的服务器的名称。 有关文档服务器服务客户机-服务器交互的更多信息，请参阅 它是如何运作的 部分。 

{
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxldHlwZSI6ImRvY3giLCJrZXkiOiJLaGlyejZ6VFBkZmQ3Iiwib3V0cHV0dHlwZSI6InBkZiIsInRpdGxlIjoiRXhhbXBsZSBEb2N1bWVudCBUaXRsZS5kb2N4IiwidXJsIjoiaHR0cDovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLWRvY3VtZW50LmRvY3gifQ.U-YAfuuy7clWjn-xOncfJ-sxVG5DlcYn0AOzJYkoR0M"
}

其中 example.com 是安装了 文档管理器 和 文档存储服务 的服务器的名称。 有关文档服务器服务客户机-服务器交互的更多信息，请参阅 它是如何运作的 部分。

请求结果以 XML 格式返回。 要接收 JSON 格式的响应，您需要在 HTTP 请求中使用 application/json 值指定 Accept 标头（从 4.3 版开始提供）。 在形成结果文件的链接时，使用与转换请求相同的服务器名称。

参数 描述 类型 示例
定义转换是否完成。 boolean true
定义转换期间发生的错误。可以在 此处找到可能的错误代码。 integer -3
定义转换文件的扩展名。 string "docm"
定义到已转换文档的链接。仅当 endConvert 参数设置为 true时才会接收到此参数。 string "https://documentserver/url-to-converted-document.pdf"
定义文件转换的百分比。如果 endConvert 参数设置为 true，则 percent 等于 100。 integer 100
XML 格式的响应示例

在形成结果文件的链接时，使用与转换请求相同的服务器名称。

<?xml version="1.0" encoding="utf-8"?>
<FileResult>
    <EndConvert>True</EndConvert>
    <FileType>docm</FileType>
    <FileUrl>https://documentserver/url-to-converted-document.pdf</FileUrl>
    <Percent>100</Percent>
</FileResult>
JSON 格式的响应示例

在形成到结果文件的链接时，使用与转换请求相同的服务器名称。

{
    "endConvert": true,
    "fileType": "docm",
    "fileUrl": "https://documentserver/url-to-converted-document.pdf",
    "percent": 100
}
XML 格式的异步请求（带有参数 async=true）的中间响应示例
<?xml version="1.0" encoding="utf-8"?>
    <FileResult>
    <EndConvert>False</EndConvert>
    <FileType></FileType>
    <FileUrl></FileUrl>
    <Percent>95</Percent>
</FileResult>
JSON 格式的异步请求（带参数 async=true）的中间响应示例
{
    "endConvert": false,
    "percent": 95
}
XML 格式发生错误时的响应示例
<?xml version="1.0" encoding="utf-8"?>
<FileResult>
    <Error>-3</Error>
</FileResult>
JSON 格式发生错误时的响应示例
{
    "error": -3
}
错误代码 描述
-1 未知错误。
-2 转换超时错误。
-3 转换错误。
-4 下载要转换的文档文件时出错。
-5 密码错误。
-6 访问转换结果数据库时出错。
-7 输入错误。
-8 令牌无效。
-9 当转换器无法自动确定输出文件格式时出错。 此错误意味着客户端必须明确指定文件应转换为哪种格式（文本文档或电子表格）。 它用于在 XML 类型未知的情况下将 XML 转换为 OOXML。
© Ascensio System SIA 2024. All rights reserved