PDF合并API调用指南：多文件上传、排序与下载处理

合同正文、盖章页和附件经常分散为多个PDF。使用 POST /data/api/document/pdf/merge 可以把它们按指定顺序合成为一个文件，适合归档、报告拼装和在线交付。

一、接口规则与文件顺序

PDF合并接口采用 multipart/form-data，必填字段是 apikey 与多个 files。至少上传2个PDF，每个文件最大10MB；服务端按同名字段出现的顺序合并页面，因此前端排序就是最终文档排序。

字段	类型	说明
apikey	string	平台身份凭证，只在服务端使用
files	file[]	至少2个PDF，按append顺序合并
fileUrl	string	成功响应中的合并文件地址

二、cURL与JavaScript调用

curl -X POST 'https://5555api.com/data/api/document/pdf/merge' \
  -F 'apikey=YOUR_APIKEY' \
  -F 'files=@contract-main.pdf' \
  -F 'files=@signed-page.pdf' \
  -F 'files=@appendix.pdf'

const fd = new FormData();
fd.append('apikey', process.env.QINGYU_API_KEY);
for (const file of selectedFiles) fd.append('files', file);

const response = await fetch(
  'https://5555api.com/data/api/document/pdf/merge',
  { method: 'POST', body: fd }
);
const result = await response.json();
if (result.code !== 200) throw new Error(result.msg || 'PDF合并失败');
const downloadUrl = result.data.fileUrl;

三、前端排序与后端校验

文件选择器返回的顺序不一定等于用户想要的页序。建议先给每个文件一个可拖拽的序号，提交前按序重建数组。后端还应重新检查扩展名、MIME、文件数量和累计大小，不能只相信浏览器传来的文件名。

const orderedFiles = [...fileList].sort((a, b) => a.order - b.order);
if (orderedFiles.length < 2) throw new Error('至少选择两个PDF');
if (orderedFiles.some(file => file.type !== 'application/pdf')) {
  throw new Error('仅支持PDF文件');
}
orderedFiles.forEach(file => fd.append('files', file));

四、下载地址的生命周期

接口成功后返回 fileUrl 与 fileName。对重要合同和报告，不建议长期依赖临时地址：可以由后端立即下载并转存到自己的对象存储，再向用户返回业务文件ID。下载转存时记录原始文件、合并顺序和操作人，便于审计。

五、失败处理清单

文件少于2个：在客户端直接阻止提交。
单个文件超过10MB：提示压缩或拆分后再上传。
PDF加密或损坏：提示重新导出无密码版本。
请求超时：保留用户选择的文件，不要让用户重新选择。
返回非200：记录requestId（如响应提供）与错误消息，避免把完整文件内容写入日志。

六、相关能力

如果业务还需要拆分、加水印、转Word或转图片，可以从PDF批量处理实践了解处理策略，并查看PDF合并API文档中的最新字段。无需开发时，也可以先试用PDF在线处理工具。

常见问题

PDF合并API至少需要几个文件？

轻语PDF合并接口要求至少上传2个PDF文件，单个文件最大10MB，最终页序按files字段的上传顺序确定。

接口返回的PDF怎么保存？

成功响应会返回fileUrl和fileName。后端可以下载后转存到自己的对象存储，前端也可以在用户授权后打开fileUrl。

加密PDF可以合并吗？

带密码保护或损坏、无法解析的PDF可能被拒绝。建议在提交前做文件完整性检查，并在失败时提示用户重新导出。

结语

PDF合并的核心不在于把文件拼起来，而是确保顺序可控、输入可靠、输出可追踪。把文件校验、排序和转存放进同一条服务端链路，合同归档和自动报告生成都会更稳定。